Retrieve a list of agents

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.

Request

Path parameters

appid stringrequired

The App ID of the project.

Query parameters

channel stringnullable

The channel to query for a list of agents.

from_time numbernullable

Default: 2 hours ago

The start timestamp (in seconds) for the query.

to_time numbernullable

Default: Current time

The end timestamp (in seconds) for the query.

state stringnullable

Default: 2

The agent state 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.

limit integernullable

Default: 20

The maximum number of entries returned per page.

cursor stringnullable

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
  Agent data.
  Show propertiesHide properties
  count integer
  The number of agents returned.
  list array
  A list of agents that meets the criteria.
  Show propertiesHide properties
  start_ts integer
  Agent creation timestamp.
  status string
  Possible values: IDLE, STARTING, RUNNING, STOPPING, STOPPED, RECOVERING, FAILED
  The current state of the agent.
  agent_id string
  The agent ID.
- meta object
  Returns meta information about the list.
  Show propertiesHide properties
  cursor string
  Paging cursor.
  total integer
  The total number of agents that meet the query conditions.
- status string
  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 to understand the possible reasons for failure.

Authorization

This endpoint requires Basic Auth.

Request example

curl
Python
Node.js

curl --request get \
  --url 'https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/agents?state=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"
}