# Retrieve a list of agents (/en/api-reference/api-ref/conversational-ai/list)

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

Retrieves Conversational AI agents that match specified conditions.

- OpenAPI: /openapi/conversational-ai/rest-api.en.yaml
- Operation ID: get-agent-list
- Method: GET
- Path: /v2/projects/{appid}/agents

## Servers

- https://api.agora.io/api/conversational-ai-agent

## Parameters

- `appid` (path, required) - The App ID of the project.
- `channel` (query, optional) - The channel to query for a list of agents.
- `from_time` (query, optional) - The start timestamp (in seconds) for the query. Defaults to `2 hours ago`.
- `to_time` (query, optional) - The end timestamp (in seconds) for the query. Defaults to the current time.
- `state` (query, optional) - The agent state to filter by. Specify one or more states as a comma-separated list. For example, `state=0,1,2`.

- `0`: `IDLE` Agent is idle.

- `1`: `STARTING` The agent is starting.

- `2`: `RUNNING` The agent is running.

- `3`: `STOPPING` The agent is stopping.

- `4`: `STOPPED` The agent has exited.

- `6`: `FAILED` The agent failed to execute.
- `limit` (query, optional) - The maximum number of entries returned per page.
- `cursor` (query, optional) - The paging cursor, indicating the starting position (`agent_id`) of the next page of results.

## Request body

No request body.

## Responses

### 200

The request was successful. The response body contains the result of the request.

- `data` (object) - Agent data.
  - `data.count` (integer) - The number of agents returned.
No schema.
  - `data.list` (array) - A list of agents that meets the criteria.
    - `data.list.items` (object)
      - `data.list.items.start_ts` (integer) - Agent creation timestamp.
No schema.
      - `data.list.items.status` (string) - The current state of the agent.
No schema.
      - `data.list.items.agent_id` (string) - The agent ID.
No schema.
- `meta` (object) - Returns meta information about the list.
  - `meta.cursor` (string) - Paging cursor.
No schema.
  - `meta.total` (integer) - The total number of agents that meet the query conditions.
No schema.
- `status` (string) - Request status.
No schema.
### default

The request failed. The response body includes the error details.

- `detail` (string) - Detailed error information.
No schema.
- `reason` (string) - The reason for the failure.
No schema.