Skip to main content

Query agent status

Query agent status

GET
https://api.agora.io/api/conversational-ai-agent/v2/projects/{appid}/agents/{agentId}

Use this endpoint to get the current status of the specified Conversational AI agent instance.

Request

Path parameters

appid stringrequired

The App ID of the project

agentId stringrequired

The agent instance ID you obtained after successfully calling join to start the conversational agent.

Response

  • If the returned status code is 200, the request was successful. The response body contains the result of the request.

    OK
    • message string

      Request message.

    • start_ts integer

      Agent creation timestamp.

    • stop_ts integer

      Agent stop timestamp.

    • status string

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

      Current status.

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

    • agent_id string

      Unique id of the agent instance

  • 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/:agentId \
_3
--header 'Authorization: Basic <credentials>'

Response example


_7
{
_7
"message": "agent exits with reason: xxxx",
_7
"start_ts": 1735035893,
_7
"stop_ts": 1735035900,
_7
"status": "FAILED",
_7
"agent_id": "1NT29X11GQSxxxxxNU80BEIN56XF"
_7
}

vundefined