Retrieve a list of agents

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

• Method: GET
• Endpoint: https://api.agora.io/api/conversational-ai-agent/v2/projects/{appid}/agents
• Authorization: Basic Auth

Parameter	Type	Required	Description
appid	string	Yes	The App ID of the project

Parameter	Type	Description
channel	string	The channel to query for a list of agents
from_time	number	The start timestamp (in seconds) for the query. Default: 2 hours ago.
to_time	number	The end timestamp (in seconds) for the query. Default: current time.
status	string	The agent status to filter by. Only one state can be specified per query: IDLE (0): Agent is idle. STARTING (1): The agent is being started. RUNNING (2): The agent is running. STOPPING (3): The agent is stopping. STOPPED (4): The agent has exited. RECOVERING (5): The agent is recovering. FAILED (6): The agent failed to execute. Default value: 1
limit	string	The maximum number of entries returned per page. Default: 20.
cursor	string	The paging cursor, indicating the starting position (agent_id) of the next page of results.

Use one of the following request examples as a starting point:

Sample request:

Select a language:curlPythonNode.js

curl --request get \
  --url https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/agents \
  --header 'Authorization: Basic <credentials>'

• 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 error code and description. Refer to status codes to understand the possible reasons for failure.

Parameter	Type	Description
data	object	Agent data
⇒count	integer	The number of agents returned.
⇒list	array	A list of agents that meets the criteria.
⇒⇒startTs	integer	Agent creation timestamp.
⇒⇒stateName	string	The current state of the agent.
⇒⇒taskId	integer	The agent ID.
meta	Returns meta information about the list.
⇒cursor	string	Paging cursor
⇒total	integer	The total number of agents that meet the query conditions.
status	string	Request status

Sample response

_17

{

_17

"data": {

_17

"count": 1,

_17

"list": [

_17

{

_17

"startTs": 1735035893,

_17

"status": "RUNNING",

_17

"taskId": "1234567890ABCDE1CVGZNU80BEIN56XF"

_17

}

_17

]

_17

},

_17

"meta": {

_17

"cursor": "",

_17

"total": 1

_17

},

_17

"status": "ok"

_17

}