# Query the task status (/en/api-reference/api-ref/speech-to-text/query)

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

Queries the status of a Real-time STT task.

- OpenAPI: /openapi/speech-to-text/v7.en.yaml
- Operation ID: query
- Method: GET
- Path: /api/speech-to-text/v1/projects/{appid}/agents/{agentId}
- Endpoint: https://api.agora.io/api/speech-to-text/v1/projects/{appid}/agents/{agentId}

## Servers

- https://api.agora.io

Use this method to query the status of a Real-time STT task.


## Authorization

This endpoint requires authentication.

- `BasicAuth`

## Parameters

- `appid` (path, required, string) - The App ID of the project.
- `agentId` (path, required, string) - The unique identifier of the agent you received in the response body of the `join` method.

## Request body

No request body.

## Request examples

### curl

```bash
curl --request GET \
  --url https://api.agora.io/api/speech-to-text/v1/projects/:appid/agents/:agentId \
  --header 'Authorization: Basic <credentials>'
```

### Python

```python
import requests

url = "https://api.agora.io/api/speech-to-text/v1/projects/:appid/agents/:agentId"

headers = {"Authorization": "Basic <credentials>"}

response = requests.request("GET", url, headers=headers)

print(response.text)
```

### Node.js

```javascript
const url = 'https://api.agora.io/api/speech-to-text/v1/projects/:appid/agents/:agentId';
const options = {method: 'GET', headers: {Authorization: 'Basic <credentials>'}};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));
```


### Response

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


## Responses

### 200

OK

- `message` (string) - Details of the request result
- `agent_id` (string) - The ID of the agent.
- `create_ts` (integer) - The Unix timestamp (in seconds) when the transcription task 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`: Agent exit failed
  - Allowed: `IDLE` | `STARTING` | `RUNNING` | `STOPPING` | `STOPPED` | `RECOVERING` | `FAILED`
### default

Error response.

- `message` (string) - Details of the failed request.
- `agent_id` (string) - The ID of the agent.
- `create_ts` (integer) - The Unix timestamp (in seconds) when the transcription task was created.
- `status` (string) - The status of the agent. If the returned status code is not 200, the request failed. Troubleshoot according to the `details` and `reason` fields.
  - Allowed: `FAILED`

### Response

Refer to message and code fields to understand the possible reasons for failure.


## Response examples

### 200

```json
{
  "message": "Details of the request result.",
  "agent_id": "Agent ID.",
  "create_ts": null,
  "status": "RUNNING"
}
```
### default

```json
{
  "message": "Details of the failed request.",
  "agent_id": "Agent ID.",
  "create_ts": null,
  "status": "FAILED"
}
```