# 查询录制列表 (/zh-CN/api-reference/meeting/restful/api/query-recording)

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

查询指定房间内的录制列表 API。

每次开启录制都会生成一条记录。你可以通过查询录制列表 API 的 `nextId` 参数分批获取，每批最多 100 条数据。目前仅支持页面录制，单次录制可能因时长或文件大小被拆分成多个录制文件，这些录制文件会在响应的 `recordDetails.url` 字段中体现。

## URL [#url]

`GET /{region}/conference/apps/{appId}/v1/rooms/{roomUuid}/records?nextId={nextId}`

域名详见[保障 REST 服务高可用](/zh-CN/realtime-media/meeting/build/high-availability)。

### 路径参数 [#路径参数]

| 参数 | 类型 | 是否必填 | 描述 |
| --- | --- | --- | --- |
| `region` | String | 必填 | 服务区域，目前仅支持设为 `cn`，代表中国大陆。 |
| `appId` | String | 必填 | 项目 App ID，详见[获取 App ID](/zh-CN/realtime-media/meeting/build/enable-service#获取-app-id)。 |
| `roomUuid` | String | 必填 | [query-recording-restful-html-0-3-3 details](#table-slot-query-recording-restful-html-0-3-3) |

<a id="table-slot-query-recording-restful-html-0-3-3"></a>

**query-recording-restful-html-0-3-3 details**

会议房间 UUID 是会议房间的唯一标识符。一般情况下，长度在 64 字符以内；如果房间需要使用页面录制，长度在 50 字符以内。支持的字符集范围（共 88 个字符，空格不支持）：

- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0-9
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"&lt;"、"="、"."、"&gt;"、"?"、"@"、"["、"]"、"^"、"_"、"&#123;"、"&#125;"、"|"、"~"、","

### 查询参数 [#查询参数]

- `nextId`：String 类型，非必填参数，下一批数据的起始 ID。推荐的填写方式如下：
    - 第一次查询时，不使用 `nextId`，即 URL 里不出现 `?nextId={nextId}`。查询成功后，从响应 Body 中得到一个 `data.list.nextId` 的值。
    - 第二次查询时，用第一次查询得到的 `nextId` 值填写。
    - 第三次查询时，用第二次查询得到的 `nextId` 值填写。
    - 以此类推，直到第 N 次查询得到的 `nextId` 为空，代表没有下一批数据，此时你可以停止查询。

## 请求 [#请求]

本节展示 HTTP 请求内容。

### 请求 Header [#请求-header]

- `Authorization`：用于 HTTP Token 认证的鉴权字段。每次发送 HTTP 请求时，都必须填入 `Authorization` 字段。详见[实现 HTTP Token 认证](/zh-CN/realtime-media/meeting/build/http-token-auth)。

### 请求示例 [#请求示例]

```shell
curl -X GET 'https://api.sd-rtn.com/{region}/conference/apps/{yourAppId}/v1/rooms/{roomUuid}/records' \
-H 'Authorization: agora token={apaasToken}'
```

## 响应 [#响应]

本节展示 HTTP 响应内容。

### 响应 Body [#响应-body]

| 字段 | 类型 | 描述 |
| --- | --- | --- |
| `code` | Integer | [query-recording-restful-html-0-1-2 details](#table-slot-query-recording-restful-html-0-1-2) |
| `msg` | String | 响应的文字信息。 |
| `ts` | Number | 当前服务端的 Unix 时间戳。UTC 时间，单位为毫秒。 |
| `data` | Object | 查询得到的录制文件信息。 |
| `data.count` | Integer | 本批数据的条数。 |
| `data.list` | Array[Object] | 录制文件列表。详见 [data.list](#datalist) 描述。 |
| `data.webRecordUrlQuery` | String | 页面录制请求中的查询参数。 将开启录制 API 的 `rootUrl` 和该字段拼接，可以得到页面录制文件的 URL。使用此 URL 可以本地访问录制文件。本地访问时，请先确保录制已停止，否则你只能看到空页面，并且会把开启录制的用户踢出会议。 |

<a id="table-slot-query-recording-restful-html-0-1-2"></a>

**query-recording-restful-html-0-1-2 details**

响应状态码：

- `0`：请求成功。
- 非 0：请求失败。详见[响应状态码](/zh-CN/realtime-media/meeting/reference/response-code)。

#### data.list [#datalist]

`data.list` 数组由多个对象组成，每个对象包含如下字段：

| 字段                  | 类型            | 描述               |
|-----------------------|-----------------|--------------------|
| `appId`               | String          | 声网项目的 App ID。|
| `roomUuid`            | String          | 会议房间 UUID。    |
| `recordId`            | String          | 一次录制的的唯一标识符。调用设置录制状态 API 开始录制然后结束录制视为一次录制。|
| `startTime`           | Long            | 录制开始时间，Unix 时间戳（毫秒），UTC 时间。录制开始后该字段有值。|
| `endTime`             | Long            | 录制结束时间，Unix 时间戳（毫秒），UTC 时间。录制结束后有该字段。|
| `resourceId`          | String          | 声网云端录制服务的 `resourceId`。|
| `sid`                 | String          | 声网云端录制服务的 `sid`。|
| `recordUid`           | String          | 声网云端录制服务在会议房间内使用的用户 ID。|
| `type`                | Integer         | 录制类型。目前只有 `3`，代表页面录制。|
| `status`              | Integer         | 录制状态。`1` 代表录制中。`2` 代表录制已结束。|
| `recordDetails`       | Array[String]    | 录制详情。         |
| `recordDetails.url`   | String          | 页面录制文件的访问地址。|
| `nextId`              | String          | 下一批数据的起始 ID。用法详见[查询参数](#查询参数)。|
| `total`               | Integer         | 数据总条数。       |
| `unready`             | Boolean         | 页面录制因加载超时而失败时该字段为 `true`，其他情况没有该字段。如果在开启录制时设置了 `retryTimeout` 参数，那么超时未报告 [`ready`](/zh-CN/realtime-media/meeting/reference/webhook-events#页面录制状态变更事件) 而被自动终止的录制任务会被标记 `unready`。|

### 响应示例 [#响应示例]

```json
{
  "code": 0,
  "msg": "Success",
  "ts": 1610450153520,
  "data": {
    "total": 17,
    "list": [
      {
        "recordId": "xxxxxx",
        "appId": "xxxxxx",
        "roomUuid": "jason0",
        "startTime": 1602648426497,
        "endTime": 1602648430262,
        "resourceId": "xxxxxx",
        "sid": "xxxxxx",
        "recordUid": "xxxxxx",
        "type": 3,
        "status": 2,
        "url": "scenario/recording/xxxxxx/xxxxxx/xxxxxx.m3u8",
        "recordDetails": [
          {
            "url": "xxxx/xxxx.mp4"
          }
        ]
      },
      {
        ...
      },
      ...
      {
        ...
      }
    ],
    "count": 17
  }
}
```