# List agents (/en/api-reference/api-ref/conversational-ai/platform/list-agents)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

> Documentation: Conversational AI API.
> Documentation version: Preview.
> This document describes only this version. [Version index](/llms/doc-versions-convoai-api-v2.txt).


Retrieves the agents saved in your project.

- OpenAPI: /openapi/conversational-ai/rest-api-platform.en.yaml
- Operation ID: list-agents
- Method: GET
- Path: /v1/projects/{appid}/agents
- Endpoint: https://preview.ai.agora.io/conversational-ai/v1/projects/{appid}/agents

## Servers

- https://preview.ai.agora.io/conversational-ai

## Authorization

This endpoint requires authentication.

- `tokenAuth`
- `basicAuth`

## Parameters

- `appid` (path, required, string) - The App ID of your project.
- `limit` (query, optional, integer) - The maximum number of agents to return on each page.
  - Default: `50`
  - Range: `[1, 200]`
- `cursor` (query, optional, string) - The `next_cursor` value from the previous page of results. Omit it to get the first page. The cursor is opaque, so pass it back unchanged.
- `order` (query, optional, string) - The sort order of the results:

- `create_ts.desc`: Newest first.
- `create_ts.asc`: Oldest first.
  - Allowed: `create_ts.desc` | `create_ts.asc`
  - Default: `create_ts.desc`

## Request body

No request body.

## Responses

### 200

The request was successful. The response body contains a page of agents.

- `has_more` (boolean) - Whether more results are available after this page.
- `next_cursor` (string | null | null) - The cursor for the next page. Pass it in the `cursor` query parameter of your next request. `null` on the last page.
- `data` (object)
  - `data.count` (integer) - The number of agents on this page.
  - `data.list` (array) - The agents on this page. Retrieve an agent to get its configuration.
    - `data.list.items` (object)
      - `data.list.items.agent_id` (string, required) - The ID of the agent.
        - Format: `uuid`
      - `data.list.items.agent_name` (string, required) - The name of the agent.
      - `data.list.items.create_ts` (integer, required) - The time the agent was created, as a Unix timestamp in seconds.
      - `data.list.items.update_ts` (integer, required) - The time the agent was last updated, as a Unix timestamp in seconds.
### 401

Authentication is missing or invalid. The reason is `InvalidPermission`.

- `detail` (string, required) - A human-readable description of the error. It names the field or resource involved, when there is one. Don't parse it; branch on `reason` instead.
- `reason` (string, required) - A machine-readable error reason, such as `InvalidFieldValue` or `ResourceNotFound`. For all reasons, see [Status codes](/en/api-reference/api-ref/conversational-ai/platform/status-codes).
### default

The request failed. The response body contains the `reason` and `detail` of the failure. For possible reasons, see [Status codes](/en/api-reference/api-ref/conversational-ai/platform/status-codes).

- `detail` (string, required) - A human-readable description of the error. It names the field or resource involved, when there is one. Don't parse it; branch on `reason` instead.
- `reason` (string, required) - A machine-readable error reason, such as `InvalidFieldValue` or `ResourceNotFound`. For all reasons, see [Status codes](/en/api-reference/api-ref/conversational-ai/platform/status-codes).

## Response examples

### 200

```json
{
  "data": {
    "count": 1,
    "list": [
      {
        "agent_id": "3f6c2a9e-8d1b-4e7a-9c55-0b2f7d1e4a10",
        "agent_name": "Customer Support Agent",
        "create_ts": 1786543331,
        "update_ts": 1787733713
      }
    ]
  },
  "has_more": false,
  "next_cursor": null
}
```