游标分页

请求参数

limit 默认 100，最大 1000。第一次请求不传 cursor；后续请求原样传回上一次响应的 next_cursor。游标是服务端位置，不是业务 ID，不要解析、拼接、修改或跨不同筛选条件复用。

curl --get https://api.zhimahang.com/v1/runs \
  -H "Authorization: Bearer $YINJEN_API_KEY" \
  --data-urlencode "limit=100" \
  --data-urlencode "cursor=eyJzdCI6MTcyNC4uLiwiaWQiOjEyMzQ1fQ"

响应包络

{
  "data": [],
  "has_more": true,
  "next_cursor": "eyJzdCI6MTcyNC4uLiwiaWQiOjEyMzQ0fQ",
  "meta": {
    "retention_start_ms": 1780339200000,
    "retention_days": 90
  }
}

has_more=false 表示当前筛选条件已到末页；此时 next_cursor 为空或省略，调用方必须停止。不要用「本页少于 limit」自行判断，因为服务端过滤可能让一页变短。

上例的 meta 是运行、引用等受 90 天保留期约束的明细响应。提示词分页不受该保留期约束，因此不返回 retention 元数据；请按各端点契约读取可选字段。

稳定顺序与 offset

运行明细以 (started_at DESC, id DESC) 稳定排序。数据在翻页期间仍会写入；offset 会让新行把旧行推向下一页，造成重复或遗漏，因此 /v1 不提供 offset。

分页也计调用量

拉取 100 页就是 100 次 API 调用，不是一次查询。批量同步优先使用可接受的最大 limit，并保存最后成功处理的 cursor；失败后从该 cursor 重试，不要从头扫描。