---
title: Query agent status
description: 'Get the current state information of the specified agent instance.

  '
sidebar_position: 4
platform: android
exported_from: https://docs.agora.io/en/conversational-ai/rest-api/agent/query
exported_on: '2026-06-05T05:02:51.927535Z'
exported_file: query.md
---

> For a complete site index fetch https://docs.agora.io/llms.txt. For all pages in this product fetch https://docs.agora.io/en/conversational-ai/overview/product-overview.md

[HTML Version](https://docs.agora.io/en/conversational-ai/rest-api/agent/query)

# Query agent status


**Method:** GET
**Endpoint:** `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** (string, required): The App ID of the project.
- **agentId** (string, required): The agent instance ID you obtained after successfully calling `join` to [Start a conversational AI agent](https://docs-md.agora.io/en/conversational-ai/rest-api/agent/join.md).

## Response

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

  **OK**

- **message** (string, optional): Request message.
- **start_ts** (integer, optional): Agent creation timestamp.
- **stop_ts** (integer, optional): Agent stop timestamp.
- **name** (string, optional): The agent name provided when calling [Start a conversational AI agent](https://docs-md.agora.io/en/conversational-ai/rest-api/agent/join.md). Unique within a channel.
- **status** (string, optional, possible 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_id** (string, optional): 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](https://docs-md.agora.io/en/conversational-ai/rest-api/reference.md) to understand the possible reasons for failure.

## Authorization

This endpoint requires [authentication](https://docs-md.agora.io/en/conversational-ai/rest-api/restful-authentication.md).

## Request example

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

**Python**
```python
    import requests

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

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

**Node.js**
```js
    const axios = require("axios");

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

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

## Response example

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