Retrieve a list of agents

Updated 2026/09/11 14:11:21

Retrieves Conversational AI agents that match specified conditions.

GET

https://api.agora.io/api/conversational-ai-agent/v2/projects/{appid}/agents

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

Path Parameters

appidstring

Required

The App ID of the project.

Query Parameters

channelstring

The channel to query for a list of agents.

from_timenumber

The start timestamp (in seconds) for the query. Defaults to 2 hours ago.

to_timenumber

The end timestamp (in seconds) for the query. Defaults to the current time.

statearray<integer>

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.

limitinteger

Default:

The maximum number of entries returned per page.

cursorstring

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.
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 to understand the possible reasons for failure.

Response Body

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

dataobject

Agent data.

metaobject

Returns meta information about the list.

statusstring

Request status.

Authorization

This endpoint requires authentication.

tokenAuthbasicAuth

Request examples

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

Response example

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