Retrieve a list of agents

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.

appid stringrequired

The App ID of the project.

APPLICATION/JSON

BODY

• 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.

• status stringnullable

  Possible values: IDLE, STARTING, RUNNING, STOPPING, STOPPED, RECOVERING, FAILED

  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.

• limit stringnullable

  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.

• 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.

    • count integer

      The number of agents returned.

    • list array

      A list of agents that meets the criteria.

      • start_ts integer

        Agent creation timestamp.

      • status string

        The current state of the agent.

      • agent_id string

        The agent ID.

  • meta object

    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.

• 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

_3

curl --request get \

_3

--url https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/agents \

_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

}