# 查询云端转码状态 (/zh-CN/api-reference/api-ref/cloud-transcoding/query)

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

查询云端转码任务的当前状态。

- OpenAPI: /openapi/cloud-transcoding/cloud-transcoding.zh-CN.yaml
- Operation ID: get-v1-projects-appId-rtsc-cloud-transcoder-tasks-taskId
- Method: GET
- Path: /v1/projects/{appId}/rtsc/cloud-transcoder/tasks/{taskId}
- Endpoint: https://api.sd-rtn.com/v1/projects/{appId}/rtsc/cloud-transcoder/tasks/{taskId}

## Servers

- https://api.sd-rtn.com

`Query` 方法用于在创建云端转码任务后查询转码状态。


## Authorization

This endpoint requires authentication.

- `Basic Auth`

## Parameters

- `Content-Type` (header, required, string) - `application/json`
- `builderToken` (query, required, string) - 通过 `Acquire` 方法的响应包体得到的 `tokenName` 的值。 
> [!CAUTION]
> 请确保填入的 `builderToken` 和你在 `Create` 接口中传入的 `builderToken` 一致。
- `taskId` (path, required, string) - 转码任务 ID，为 UUID，用于标识本次请求操作的 Cloud transcoder。
- `appId` (path, required, string) - 声网为每个开发者提供的 **App ID**。在声网控制台创建一个项目后即可得到一个 App ID。一个 App ID 是一个项目的唯一标识。

## Request body

No request body.

## Responses

### 2XX

如果状态码为 2XX，则请求成功。

- `taskId` (string) - 转码任务 ID，为 UUID，用于标识本次请求操作的 Cloud transcoder。
- `createTs` (number) - 转码任务创建时的 Unix 时间戳（秒）。
- `status` (string) - 转码任务的运行状态：

- `"IDLE"`: 任务未开始。
- `"PREPARED"`: 任务已收到开启请求。
- `"STARTING"`: 任务正在开启。
- `"CREATED"`: 任务初始化完成。
- `"STARTED"`: 任务已经启动。
- `"IN_PROGRESS"`: 任务正在进行。
- `"STOPPING"`: 任务正在停止。
- `"STOPPED"`: 任务已经停止。
- `"EXIT"`: 任务正常退出。
- `"FAILURE_STOP"`: 任务异常退出。

**注意**：你可以用该字段监听任务的状态。
- `services` (object)
  - `services.cloudTranscoder` (object)
    - `services.cloudTranscoder.config` (object) - 同你在 `Create` 请求包体中设置的 `config` 字段。
    - `services.cloudTranscoder.createTs` (number) - 创建服务时的 Unix 时间戳（秒）。
    - `services.cloudTranscoder.details` (object) - 预留字段。
    - `services.cloudTranscoder.message` (string) - 预留字段。
    - `services.cloudTranscoder.serviceType` (string) - 服务类型，此处为 `"cloudTranscoderV2"`。
    - `services.cloudTranscoder.status` (string) - 转码任务中的转码服务的运行状态：

- `"serviceIdle"`: 服务未开始。
- `"serviceReady"`: 服务已经就绪。
- `"serviceStarted"`: 服务已经开始。
- `"serviceInProgress"`: 服务正在进行。
- `"serviceCompleted"`: 服务已经停止，任务全部完成。
- `"servicePartialCompleted"`: 服务已经停止，任务部分完成。
- `"serviceValidationFailed"`: 服务参数验证失败。
- `"serviceAbnormal"`: 服务异常退出。
- `"serviceUnknown"`: 服务未知状态。

**注意**：该字段可用于让声网技术团队调查问题，你无需过多关注。
- `eventHandlers` (object) - 预留字段。
- `execution` (object)
  - `execution.workflows` (object) - 预留字段。
- `properties` (object) - 预留字段。
- `sequenceId` (string) - 预留字段。
- `variables` (object) - 预留字段。
- `workflows` (object) - 预留字段。
### 非 2XX

如果状态码不为 2XX，请求失败。请根据响应状态码和 `message` 字段进行排查。

- `message` (string) - 描述请求失败的原因。

## Response examples

### 2XX

```json
{
  "createTs": 1661420011,
  "eventHandlers": {},
  "execution": {
    "workflows": {}
  },
  "properties": {},
  "sequenceId": "0",
  "services": {
    "cloudTranscoder": {
      "config": {},
      "createTs": 1661420011,
      "message": "OnSlaveServiceQueryUpdated",
      "serviceType": "cloudTranscoderV2",
      "status": "serviceInProgress"
    }
  },
  "status": "IN_PROGRESS",
  "taskId": "c0077139e34d0949c719189a393aa***",
  "variables": {},
  "workflows": {}
}
```
### 非 2XX

```json
{
  "message": "描述请求失败的原因。"
}
```