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

List Real-time STT agents

GET
https://api.agora.io/api/speech-to-text/v1/projects/{appid}/agents

Use this method to retrieve a list of real-time transcription and translation agents that match specified criteria.

Request​

Path parameters​

appId stringrequired

The App ID of the project.

Query parameters​

QUERY
  • channel stringnullable

    Filters the agent list by channel name.

  • from_time integernullable

    Default: 1 day ago

    The start of the query time range, as a Unix timestamp in seconds.

  • to_time integernullable

    Default: Current time

    The end of the query time range, as a Unix timestamp in seconds.

  • state stringnullable

    Default: 2

    Filters agents by status. Only one status value can be specified per request:

    • 0 - IDLE: The agent is not initialized.
    • 1 - STARTING: The agent is starting.
    • 2 - RUNNING: The agent is running.
    • 3 - STOPPING: The agent is exiting.
    • 4 - STOPPED: The agent exited successfully.
    • 5 - RECOVERING: The agent is recovering.
    • 6 - FAILED: The agent exited with a failure.
  • limit integernullable

    Default: 20

    The maximum number of agents to return per page.

  • cursor stringnullable

    The pagination cursor. Set this to the agent_id of the last item from the previous page to retrieve 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
      Show propertiesHide properties
      • count integer

        The number of agents returned in this response.

      • list array

        The list of agents matching the query criteria.

        Show propertiesHide properties
        • start_ts integer

          The Unix timestamp (in seconds) when the agent was created.

        • status string

          The current status of the agent:

          • IDLE: The agent is not initialized.
          • STARTING: The agent is starting.
          • RUNNING: The agent is running.
          • STOPPING: The agent is exiting.
          • STOPPED: The agent exited successfully.
          • RECOVERING: The agent is recovering.
          • FAILED: The agent exited with a failure.
        • agent_id string

          The agent ID.

    • meta object

      Metadata about the returned list.

      Show propertiesHide properties
      • cursor string

        The pagination cursor for the next page of results.

      • total integer

        The total number of agents matching the query criteria.

    • status string

      The request status.

  • If the returned status code is not 200, the request failed. Refer to the detail and reason fields to understand the possible reasons for failure.

    Non-200
    • detail string

      Details of the request failure.

    • reason string

      The reason why the request failed.

Authorization

This endpoint requires Basic Auth.

Request example


_3
curl --request GET \
_3
--url 'https://api.agora.io/api/speech-to-text/v1/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": "1NT29X11GQSxxxxx80BEIN56XF"
_17
}
_17
]
_17
},
_17
"meta": {
_17
"cursor": "",
_17
"total": 1
_17
},
_17
"status": "ok"
_17
}