> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vaanivoice.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List Agents

> List all agents associated with your organization

## List Agents

Retrieve all agents associated with the authenticated user's organization. Supports optional search filtering by display name or agent name, as well as pagination.

***

## Query Parameters

**search** `string`

Filter agents by display name or agent slug.

**page** `integer`

Page number for pagination (1-indexed). When omitted, returns all agents as a list.

**page\_size** `integer` (default: 10)

Number of agents per page (max 200).

**published\_only** `boolean` (default: false)

Filter to only return published agents.

***

## Request Example

```bash cURL theme={null}
curl -X GET "https://api.vaanivoice.ai/api/agents?search=support&page=1&page_size=10" \
  -H "X-API-Key: vaani_<your_key>"
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.vaanivoice.ai/api/agents?search=support&page=1&page_size=10", {
  method: "GET",
  headers: {
    "X-API-Key": "vaani_<your_key>",
  },
});

const data = await response.json();
console.log(data);
```

```python Python (Requests) theme={null}
import requests

response = requests.get(
    "https://api.vaanivoice.ai/api/agents",
    headers={
        "X-API-Key": "vaani_<your_key>",
    },
    params={
        "search": "support",
        "page": 1,
        "page_size": 10,
    },
)
print(response.json())
```

```python Python SDK theme={null}
from vaani_sdk import VaaniClient

with VaaniClient(api_key="vaani_<your_key>") as client:
    # List all agents
    agents = client.agents.list()
    for agent in agents:
        print(agent.id, agent.display_name, agent.agent_name)

    # Search with pagination
    filtered = client.agents.list(search="support", page=1, page_size=10)
```

***

## Response

```json Paginated (200 OK) theme={null}
{
  "data": [
    {
      "id": "7ec4155e-0e62-440a-b983-5974f7697854",
      "agent_name": "clientnamesupportbot",
      "display_name": "Support Bot",
      "client_id": "9abf5eff-e978-4e87-954d-7ff6ba570796",
      "client_name": "Acme Corp",
      "published": true,
      "published_at": "2026-09-01T12:00:00Z",
      "last_edited_at": "2026-09-25T10:00:00Z",
      "deployment_config": {},
      "status": "running",
      "gsheet_config": null,
      "archived": false
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 10,
    "total_count": 1,
    "total_pages": 1,
    "has_next": false,
    "has_previous": false
  }
}
```

```json Non-Paginated (200 OK) theme={null}
[
  {
    "id": "7ec4155e-0e62-440a-b983-5974f7697854",
    "agent_name": "clientnamesupportbot",
    "display_name": "Support Bot",
    "client_id": "9abf5eff-e978-4e87-954d-7ff6ba570796",
    "client_name": "Acme Corp",
    "published": true,
    "published_at": "2026-09-01T12:00:00Z",
    "last_edited_at": "2026-09-25T10:00:00Z",
    "deployment_config": {},
    "status": "running",
    "gsheet_config": null,
    "archived": false
  }
]
```

**data** `array`

List of agent objects.

**agent properties**

**id** `string`

Unique identifier (UUID) of the agent.

**agent\_name** `string`

Internal system slug identifier of the agent.

**display\_name** `string`

Human-readable display name of the agent.

**client\_id** `string`

UUID of the organization owning the agent.

**client\_name** `string`

Name of the organization.

**published** `boolean`

Whether the agent has been published for active use.

**published\_at** `string`

ISO timestamp when the agent was published.

**last\_edited\_at** `string`

ISO timestamp when the agent was last edited.

**status** `string`

Current agent status (e.g. `running`, `stopped`, `initialized`).

**archived** `boolean`

Whether the agent is archived.

**pagination** `object`

Pagination metadata included when `page` parameter is provided.

**pagination properties**

**page** `integer`

Current page number.

**page\_size** `integer`

Number of items per page.

**total\_count** `integer`

Total matching agents.

**total\_pages** `integer`

Total number of pages.

**has\_next** `boolean`

Whether more pages exist.

**has\_previous** `boolean`

Whether a prior page exists.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.