Skip to main content
Conversational AI Engine: Create advanced voice apps by combining Agora's real-time audio with powerful conversational AI.

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


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

Response example


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