# 获取任务列表 (/zh-CN/api-reference/api-ref/speech-to-text/list)

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

获取符合指定条件的实时转录翻译任务列表。

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

## Servers

- https://api.agora.io

## Authorization

This endpoint requires authentication.

- `Basic Auth`

## Parameters

- `appid` (path, required, string) - 你的项目的 App ID，可在[声网控制台](https://console.shengwang.cn/)获取。
- `channel` (query, optional, string) - 查询指定频道名下的任务列表。
- `from_time` (query, optional, integer) - 查询列表开始时间戳（秒），默认为 1 天前。
- `to_time` (query, optional, integer) - 查询列表结束时间戳（秒），默认为当前时刻。
- `state` (query, optional, string) - 指定需要查询任务的状态，单次查询不支持指定多种状态：
- `STARTING` (1)：正在启动的任务。
- `RUNNING` (2)：正在运行的任务。
- `STOPPING` (3)：正在停止的任务。
- `STOPPED` (4)：已完成退出的任务。
- `RECOVERING` (5)：正在恢复的任务。
- `FAILED` (6)：执行失败的任务。
  - Default: `2`
- `limit` (query, optional, integer) - 分页获取单次返回的最大条数。
  - Default: `20`
- `cursor` (query, optional, string) - 分页游标，即分页起始位置的 `agent_id`。

## Request body

No request body.

## Responses

### 200

如果返回的状态码为 `200`，表示请求成功。

- `data` (object)
  - `data.count` (integer) - 本次返回的任务数量。
  - `data.list` (array) - 满足条件的任务列表。
    - `data.list.items` (object)
      - `data.list.items.start_ts` (integer) - 任务创建时间戳。
      - `data.list.items.status` (string) - 任务状态：
- `STARTING`：任务开始启动。
- `RUNNING`：任务进行中。
- `STOPPING`：任务退出中。
- `STOPPED`：任务退出成功。
- `RECOVERING`：任务恢复中。
- `FAILED`：任务退出失败。
      - `data.list.items.agent_id` (string) - 任务 ID。
- `meta` (object) - 返回列表的元信息。
  - `meta.cursor` (string) - 分页游标。
  - `meta.total` (integer) - 满足本次查询条件的任务总数量。
- `status` (string) - 请求状态。
### default

如果返回的状态码不为 `200`，请求失败。请根据响应包体中的字段进行排查。

- `detail` (string) - 请求失败的详细信息。
- `reason` (string) - 请求失败的原因。

## Response examples

### 200

```json
{
  "data": {
    "count": 1,
    "list": [
      {
        "start_ts": 1735035893,
        "status": "RUNNING",
        "agent_id": "1NT29X11GQSxxxxx80BEIN56XF"
      }
    ]
  },
  "meta": {
    "cursor": "",
    "total": 1
  },
  "status": "ok"
}
```
### default

```json
{
  "detail": "请求失败的详细信息。",
  "reason": "请求失败的原因。"
}
```