> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telzino.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List Agents
> Returns a paginated list of agents accessible by the authenticated account
## Query Parameters
Filter by organization ID (UUID format). Only returns agents belonging to this organization.
Filter by agent provider
Page number for pagination (1-indexed)
Number of items per page (max 100)
```bash cURL theme={null}
# List all agents
curl "https://api.telzino.com/v1/agents?page=1&limit=50" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
# Filter by organization
curl "https://api.telzino.com/v1/agents?organization_id=123e4567-e89b-12d3-a456-426614174000" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
```javascript JavaScript theme={null}
// List all agents
const response = await fetch('https://api.telzino.com/v1/agents?page=1&limit=50', {
headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN' }
});
const { data, pagination } = await response.json();
// Filter by organization
const orgResponse = await fetch(
'https://api.telzino.com/v1/agents?organization_id=123e4567-e89b-12d3-a456-426614174000',
{ headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN' } }
);
```
```python Python theme={null}
import requests
# List all agents
response = requests.get(
'https://api.telzino.com/v1/agents',
params={'page': 1, 'limit': 50},
headers={'Authorization': 'Bearer YOUR_ACCESS_TOKEN'}
)
agents = response.json()
```
```json 200 theme={null}
{
"data": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"organization_id": "987fcdeb-51a2-3bc4-d567-890123456789",
"name": "Customer Support Agent",
"description": "Handles customer inquiries",
"greeting_message": "Hello! How can I help you today?",
"system_prompt": "You are a helpful customer support agent...",
"agent_type": "simple",
"model": "gpt-4.1",
"voice_model": "gpt-4o-realtime-preview",
"stt_model": "deepgram",
"tts_model": "cartesia",
"voice_settings": {"voice_id": "f786b574-daa5-4673-aa0c-cbe3e8534c02", "speed": 1.0},
"config": {"enable_recording": true},
"extensions": {},
"integrations": {},
"transfer_enabled": false,
"status": "active",
"is_active": true,
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
},
{
"id": "456e7890-e89b-12d3-a456-426614174001",
"organization_id": "987fcdeb-51a2-3bc4-d567-890123456789",
"name": "Appointment Scheduler",
"description": "Schedules appointments via Google Calendar",
"greeting_message": "Hi! I can help you schedule an appointment.",
"system_prompt": "You are an appointment scheduling assistant...",
"agent_type": "advanced",
"model": "gpt-4.1",
"voice_model": "gpt-4o-realtime-preview",
"stt_model": "deepgram",
"tts_model": "minimax",
"voice_settings": {"voice_id": "English_radiant_girl"},
"config": {"user_timezone": "America/New_York"},
"extensions": {},
"integrations": {"google_calendar": {"enabled": true}},
"transfer_enabled": true,
"status": "active",
"is_active": true,
"created_at": "2024-01-10T08:00:00Z",
"updated_at": "2024-01-14T16:45:00Z"
}
],
"pagination": {
"page": 1,
"limit": 50,
"total": 150,
"totalPages": 3,
"hasNext": true,
"hasPrev": false
}
}
```
```json 401 theme={null}
{
"error": "invalid_token",
"error_description": "Missing or invalid authorization token"
}
```
```json 403 theme={null}
{
"error": "forbidden",
"error_description": "No access to this organization"
}
```
## Agent Object Fields
| Field | Type | Description |
| --------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | string | Unique agent identifier (UUID) |
| `organization_id` | string | Organization the agent belongs to |
| `name` | string | Display name |
| `description` | string | Agent description |
| `greeting_message` | string | Initial message when call starts |
| `outbound_greeting_message` | string | Greeting used for outbound calls the agent places |
| `system_prompt` | string | AI behavior instructions |
| `agent_type` | string | Configuration type: `simple`, `advanced`, `custom`, `appointment_scheduler` |
| `model` | string | LLM model (e.g., `gpt-4.1`) — see [List LLM Models](/api-reference/llm-models) for all supported values |
| `voice_model` | string | Voice model |
| `stt_model` | string | Speech-to-text model |
| `tts_model` | string | Text-to-speech model: `cartesia`, `minimax`, `deepgram` |
| `voice_settings` | object | Voice configuration (varies by TTS model) |
| `config` | object | General configuration |
| `extensions` | object | `tools` (webhooks) and `mcp_servers` (each item stored in snake\_case, e.g. `id`, `connection_name`, `mcp_endpoint_url` (SSE URL vs streamable HTTP URL depending on `transport_type`), `transport_type` lowercase `sse` or `http`, optional `auth_headers`, `initialization_options`, `fingerprint`, `tools` with `name`/`description` only — see [Get Agent](/api-reference/agents/get#stored-mcp-connection-shape)) |
| `integrations` | object | Third-party integrations (calendar, modmed) |
| `transfer_enabled` | boolean | Whether call transfer is enabled |
| `status` | string | Status: `active`, `inactive`, `cancelled`, `pending` |
| `is_active` | boolean | Whether agent is currently active |
| `created_at` | datetime | Creation timestamp |
| `updated_at` | datetime | Last update timestamp |
## Pagination
Responses include pagination metadata to help navigate through large result sets:
| Field | Type | Description |
| ------------ | ------- | -------------------------------- |
| `page` | integer | Current page number |
| `limit` | integer | Items per page |
| `total` | integer | Total number of agents |
| `totalPages` | integer | Total number of pages |
| `hasNext` | boolean | Whether there are more pages |
| `hasPrev` | boolean | Whether there are previous pages |