---
title: Retrieve a list of agents
description: 'Retrieve a list of agents that meet the specified conditions.

  '
sidebar_position: 5
platform: android
exported_from: https://docs.agora.io/en/conversational-ai/rest-api/agent/list
exported_on: '2026-06-11T15:04:03.402741Z'
exported_file: list.md
---

> For a complete site index fetch https://docs.agora.io/llms.txt. For all pages in this product fetch https://docs.agora.io/en/conversational-ai/overview/product-overview.md

[HTML Version](https://docs.agora.io/en/conversational-ai/rest-api/agent/list)

# Retrieve a list of agents


**Method:** GET
**Endpoint:** `https://api.agora.io/api/conversational-ai-agent/v2/projects/{appid}/agents`

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

## Request

### Path parameters

- **appid** (string, required): The App ID of the project.
### Query parameters

- **channel** (string, optional): The channel to query for a list of agents.
- **from_time** (number, optional, default: 2 hours ago): The start timestamp (in seconds) for the query.
- **to_time** (number, optional, default: Current time): The end timestamp (in seconds) for the query.
- **state** (integer[], optional, default: 2): 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** (integer, optional, default: 20): The maximum number of entries returned per page.
- **cursor** (string, optional): The paging cursor, indicating the starting position (`agent_id`) of the next page of results.

## Response

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

  **OK**

- **data** (object, optional): Agent data.
  - **count** (integer, optional): The number of agents returned.
  - **list** (array, optional): A list of agents that meets the criteria.
    - **start_ts** (integer, optional): Agent creation timestamp.
    - **status** (string, optional, possible values: `IDLE`, `STARTING`, `RUNNING`, `STOPPING`, `STOPPED`, `FAILED`): The current state of the agent.
    - **agent_id** (string, optional): The agent ID.
- **meta** (object, optional): Returns meta information about the list.
  - **cursor** (string, optional): Paging cursor.
  - **total** (integer, optional): The total number of agents that meet the query conditions.
- **status** (string, optional): Request status.

- 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](https://docs-md.agora.io/en/conversational-ai/rest-api/reference.md) to understand the possible reasons for failure.

## Authorization

This endpoint requires [authentication](https://docs-md.agora.io/en/conversational-ai/rest-api/restful-authentication.md).

## Request example

**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'
```

**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'
    }

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

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

**Node.js**
```js
    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'
      }
    };

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

## Response example

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