# 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
- Endpoint: https://api.agora.io/api/conversational-ai-agent/v2/projects/{appid}/agents

## Servers

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

Get a list of Conversational AI agents that meet the specified conditions.


## Authorization

This endpoint requires authentication.

- `tokenAuth`
- `basicAuth`

## Parameters

- `appid` (path, required, string) - The App ID of the project.
- `channel` (query, optional, string) - The channel to query for a list of agents.
- `from_time` (query, optional, number) - The start timestamp (in seconds) for the query. Defaults to `2 hours ago`.
- `to_time` (query, optional, number) - The end timestamp (in seconds) for the query. Defaults to the current time.
- `state` (query, optional, array) - 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.
  - Default: `2`
- `limit` (query, optional, integer) - The maximum number of entries returned per page.
  - Default: `20`
- `cursor` (query, optional, string) - The paging cursor, indicating the starting position (`agent_id`) of the next page of results.

## Request body

No request body.

## Request examples

### curl

```bash
curl --request get \
        --url 'https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/agents?state=0,1,2&limit=20' \
        --header 'Authorization: Basic <credentials>'
```

### Python

```python
import requests

    url = 'https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/agents'
    params = {
        'state': '0,1,2',
        'limit': '20'
    }
    headers = {
        'Authorization': 'Basic <credentials>'
    }

    response = requests.get(url, headers=headers, params=params)

    print(response.status_code)
    print(response.json())
```

### Node.js

```javascript
const url = 'https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/agents?state=0,1,2&limit=20';

    const options = {
      method: 'GET',
      headers: {
        'Authorization': 'Basic <your_base64_encoded_credentials>'
      }
    };

    fetch(url, options)
      .then(res => res.json())
      .then(json => console.log(json))
      .catch(err => console.error(err));
```


### Response

- If the returned status code is `200`, the request was successful. The response body contains the result of the request.

- If the returned status code is not `200`, the request failed. The response body includes the `detail` and `reason` for failure. Refer to [status codes](/en/api-reference/api-ref/conversational-ai/status-codes) to understand the possible reasons for failure.


## 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.
  - `data.list` (array) - A list of agents that meets the criteria.
    - `data.list.items` (object)
      - `data.list.items.start_ts` (integer) - Agent creation timestamp.
      - `data.list.items.status` (string) - The current state of the agent.
        - Allowed: `IDLE` | `STARTING` | `RUNNING` | `STOPPING` | `STOPPED` | `FAILED`
      - `data.list.items.agent_id` (string) - The agent ID.
- `meta` (object) - Returns meta information about the list.
  - `meta.cursor` (string) - Paging cursor.
  - `meta.total` (integer) - The total number of agents that meet the query conditions.
- `status` (string) - Request status.
### default

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

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

## Response examples

### 200

```json
{
  "data": {
    "count": 1,
    "list": [
      {
        "start_ts": 1735035893,
        "status": "RUNNING",
        "agent_id": "1234567890ABCDE1CVGZNU80BEIN56XF"
      }
    ]
  },
  "meta": {
    "cursor": "",
    "total": 1
  },
  "status": "ok"
}
```