# Query agent status (/en/api-reference/api-ref/conversational-ai/query)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

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

- OpenAPI: /openapi/conversational-ai/rest-api.en.yaml
- Operation ID: query-agent-status
- Method: GET
- Path: /v2/projects/{appid}/agents/{agentId}
- Endpoint: https://api.agora.io/api/conversational-ai-agent/v2/projects/{appid}/agents/{agentId}

## Servers

- https://api.agora.io/api/conversational-ai-agent

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


## Authorization

This endpoint requires authentication.

- `tokenAuth`
- `basicAuth`

## Parameters

- `appid` (path, required, string) - The App ID of the project.
- `agentId` (path, required, string) - The agent instance ID you obtained after successfully calling `join` to [Start a conversational AI agent](/en/api-reference/api-ref/conversational-ai/join).

## Request body

No request body.

## Request examples

### curl

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

### Python

```python
import requests

    url = "https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/agents/:agentId"
    headers = {"Authorization": "Basic <credentials>"}

    response = requests.get(url, headers=headers)
    print(response.text)
```

### Node.js

```javascript
const axios = require("axios");

    const url = "https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/agents/:agentId";
    const headers = { Authorization: "Basic <credentials>" };

    axios.get(url, { headers })
      .then(response => console.log(response.data))
      .catch(error => console.error(error.response ? error.response.data : error.message));
```


### 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](/en/api-reference/api-ref/conversational-ai/status-codes) to understand the possible reasons for failure.


## Responses

### 200

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

- `message` (string) - Request message.
- `start_ts` (integer) - Agent creation timestamp.
- `stop_ts` (integer) - Agent stop timestamp.
- `name` (string) - The agent name provided when calling [Start a conversational AI agent](/en/api-reference/api-ref/conversational-ai/join). Unique within a channel.
- `status` (string) - 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.
  - Allowed: `IDLE` | `STARTING` | `RUNNING` | `STOPPING` | `STOPPED` | `FAILED`
- `agent_id` (string) - Unique id of the agent instance
### default

The request failed. The response body includes the error details.

- `detail` (string) - Detailed error information.
- `reason` (string) - The reason for the failure.

## Response examples

### 200

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