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

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

<CalloutContainer type="warning">
  <CalloutDescription>
    Real-Time STT API versions v5.x and v6.x are deprecated since June 2025 and will reach end-of-life on June 11, 2026. Use the v7 REST API for new projects.
  </CalloutDescription>
</CalloutContainer>

## Endpoint [#endpoint]

* Method: `GET`

* Endpoint: `https://api.agora.io/v1/projects/{appId}/rtsc/speech-to-text/tasks/{taskId}`

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

## Request [#request]

### Path parameters [#path-parameters]

**`appId`** Type: `string` Required

The App ID of the project

**`taskId`** Type: `string` Required

The unique identifier of the Real-Time STT task you received in the response body of the [`start`](start) method.

### Query parameters [#query-parameters]

**`builderToken`** Type: `string` Required

The `tokenName` value you obtained in the response body of the [`acquire`](acquire) method.

## Response [#response]

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

  #### OK [#ok]

**`taskId`** Type: `string` Required

The unique identifier of this transcription task.

**`createTs`** Type: `integer` Required

The Unix timestamp (in seconds) when the transcription task was created.

**`status`** Type: `string` Required

The current status of the transcription task:

* `IDLE`: Task not initialized

* `PREPARING`: Task has received an initialization request

* `PREPARED`: Task initialization completed

* `STARTING`: Task is beginning to start

* `CREATED`: Task startup partially completed

* `STARTED`: Task startup fully completed

* `IN_PROGRESS`: Task is currently running

* `STOPPING`: Task is in the process of being paused

* `STOPPED`: Task has been terminated

* `FAILURE_STOP`: Task termination failed

* If the returned status code is not `200`, the request failed. Refer to `message` and `code` fields to understand the possible reasons for failure.

#### Non-200 [#non-200]

**`message`** Type: `string`

The reason why the request failed.

## Authorization [#authorization]

This endpoint requires [Basic Auth](../authentication).

## Request example [#request-example]

<CodeBlockTabs defaultValue="curl">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="curl">
      curl
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="python">
      Python
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="nodejs">
      Node.js
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="curl">
    ```bash
          curl --request GET \
            --url https://api.agora.io/v1/projects/:appId/rtsc/speech-to-text/tasks/:taskId?builderToken=your_builder_token \
            --header 'Authorization: Basic <credentials>' \
            --header 'Content-Type: <string>'
    ```
  </CodeBlockTab>

  <CodeBlockTab value="python">
    ```python
        import requests

        url = "https://api.agora.io/v1/projects/:appId/rtsc/speech-to-text/tasks/:taskId?builderToken=your_builder_token"

        headers = {
            "Authorization": "Basic <credentials>",
            "Content-Type": "<string>"
        }

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

        print(response.text)
    ```
  </CodeBlockTab>

  <CodeBlockTab value="nodejs">
    ```js
        const url = 'https://api.agora.io/v1/projects/:appId/rtsc/speech-to-text/tasks/:taskId?builderToken=your_builder_token';
        const options = {
          method: 'GET',
          headers: {Authorization: 'Basic <credentials>', 'Content-Type': '<string>'}
        };

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

## Response example [#response-example]

### 200 [#200]

```json
    {
      "taskId": "XXXX",
      "createTs": 1678505852,
      "status": "IN_PROGRESS"
    }
```

### Non-200 [#non-200-1]

```json
    {
      "message": "The reason why the request failed.",
    }
```