--- title: "查询账户请求记录" description: "按时间、模型、调用密钥与请求结果筛选 XiuAI 请求记录,并使用游标分页完成同步。" image: "https://docs.xiu.ai/og.png" --- > XiuAI 文档索引 > 完整文档索引:https://docs.xiu.ai/llms.txt > 阅读前先通过索引确认当前可用页面。 # 查询账户请求记录 逐条读取密钥所属账户的模型请求,包括请求结果、Token 用量和费用。需要 `usage:read` 权限;尚未拿到密钥时,先在控制台[获取密钥](/open-api/#获取密钥)。 ```http GET /open/v1/requests ``` 记录按从新到旧的顺序返回。 ## 请求记录参数 参数均为可选的 URL query 参数。 | 参数 | 类型 | 说明 | | --- | --- | --- | | `limit` | integer | 每页条数,范围 `1`–`100`,默认 `50` | | `cursor` | string | 上一页的 `nextCursor`,原样传回;首页不传 | | `startTime` | integer | 开始时间,Unix 秒,包含该秒;不传则不设下界 | | `endTime` | integer | 结束时间,Unix 秒,包含该秒;不传则不设上界 | | `model` | string | 模型名,精确匹配 | | `keyName` | string | 发出模型请求的 API Key 名称,精确匹配 | | `outcome` | string | `succeeded`、`interrupted` 或 `failed` | | `requestId` | string | 请求 ID,支持子串匹配 | ```bash curl --fail-with-body --silent --show-error \ --connect-timeout 5 --max-time 15 --get \ https://api.xiu.ai/open/v1/requests \ -H "Authorization: Bearer $XIU_OPEN_API_KEY" \ --data-urlencode "startTime=1794355200" \ --data-urlencode "endTime=1794441599" \ --data-urlencode "limit=100" ``` ## 请求记录字段 ```json { "items": [ { "id": "18234", "requestId": "20261111091502123456789abcdef", "createdAt": 1794388502, "model": "gpt-5", "keyName": "production", "outcome": "succeeded", "stream": true, "promptTokens": 1200, "completionTokens": 350, "cacheTokens": 1024, "cacheCreationTokens": 0, "cost": "0.004250", "durationSeconds": 3, "firstTokenMs": 850 } ], "nextCursor": "18234", "currency": "USD" } ``` | 字段 | 类型 | 说明 | | --- | --- | --- | | `items` | array | 本页请求记录,从新到旧 | | `nextCursor` | string 或 null | 下一页游标;为 `null` 时已读取完毕 | | `currency` | string | 所有 `cost` 的币种,当前为 `USD` | 每条 `items` 记录包含: | 字段 | 类型 | 说明 | | --- | --- | --- | | `id` | string | 记录 ID,用于去重;按不透明字符串保存,不做算术 | | `requestId` | string | 请求 ID,联系支持时提供 | | `createdAt` | integer | 请求时间,Unix 秒 | | `model` | string | 请求的模型名 | | `keyName` | string | 发出请求的模型调用密钥名 | | `outcome` | string | 请求结果,见下表 | | `stream` | boolean | 是否使用流式响应 | | `promptTokens` | integer | 输入 Token 数;失败请求为 `0` | | `completionTokens` | integer | 输出 Token 数;失败请求为 `0` | | `cacheTokens` | integer | 输入中命中缓存的 Token 数,部分模型按缓存价计费 | | `cacheCreationTokens` | integer | 写入缓存的 Token 数,部分模型单独计费 | | `cost` | string | 此次请求的精确费用,固定六位小数 | | `durationSeconds` | integer | 总耗时,单位为秒 | | `firstTokenMs` | integer 或 null | 首个 Token 的到达耗时,单位为毫秒;非流式、失败或较早记录可能没有该值,返回 `null` | | `outcome` | 含义 | 费用 | | --- | --- | --- | | `succeeded` | 请求成功 | 按实际用量计费 | | `interrupted` | 客户端中途断开 | 已按实际用量计费 | | `failed` | 请求失败 | 不计费 | 失败记录不包含上游错误原文。需要排查时,提供 `requestId` 和请求时间。 ## 分页与增量同步 从不带 `cursor` 的第一页开始,每次把 `nextCursor` 原样传回,直到返回 `null`。不要使用页码或自己计算游标。翻页时保持时间和其他筛选条件不变;更换条件后,从第一页重新读取。新产生的请求不会挤进后面的页。 定期同步时,固定本次查询的 `endTime`,完成全部分页后再更新同步进度。下次将上次读取到的最新请求时间作为 `startTime`,重新从第一页读取。时间边界包含该秒,因此应按 `id` 去重;写入自己的数据库时,可用 `id` 作为唯一键更新或插入。中途失败时不要将这一轮标记为已完成。 [Python 同步示例](/open-api/examples/)包含游标翻页与重试处理。要核对同一时间窗和筛选条件下的总额,可使用[用量与费用汇总](/open-api/summary/)。 源文件:https://docs.xiu.ai/open-api/requests/index.mdx