# 查询录制列表 (/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) |
**query-recording-restful-html-0-3-3 details**
会议房间 UUID 是会议房间的唯一标识符。一般情况下,长度在 64 字符以内;如果房间需要使用页面录制,长度在 50 字符以内。支持的字符集范围(共 88 个字符,空格不支持):
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0-9
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
### 查询参数 [#查询参数]
- `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 可以本地访问录制文件。本地访问时,请先确保录制已停止,否则你只能看到空页面,并且会把开启录制的用户踢出会议。 |
**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
}
}
```