Query agent status

Updated 2026/09/11 14:11:21

Retrieves the current status of a specified Conversational AI agent instance.

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.

Path Parameters

appidstring

Required

The App ID of the project.

agentIdstring

Required

The agent instance ID you obtained after successfully calling join to Start a conversational AI agent.

Response

If the returned status code is 200, the request was successful. The response body contains the result of the request.
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.

Response Body

The request was successful. The response body contains the result of the request.

messagestring

Request message.

start_tsinteger

Agent creation timestamp.

stop_tsinteger

Agent stop timestamp.

namestring

The agent name provided when calling Start a conversational AI agent. Unique within a channel.

statusstring

Allowed values:

IDLE, STARTING, RUNNING, STOPPING, STOPPED, 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. FAILED (6): The agent failed to execute.

agent_idstring

Unique id of the agent instance

Authorization

This endpoint requires authentication.

tokenAuthbasicAuth

Request examples

curl --request get \      --url https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/agents/:agentId \      --header 'Authorization: Basic <credentials>'

Response example

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