跳转到正文
Docs
下载 Markdown
历史内容快照: 2026-10-08. 文档版本与平台发布版本分别记录。阅读当前文档
文章目录

通过 API 获取数据

执行增量或从头读取,检查返回内容与分页。

下载 Markdown

在 API Keys 页的 Pull data with your API key 区域,使用 Pull from 确认数据源和 Subscription ID。这里只有一个源时不一定显示下拉框;显示 No subscription yet 时,先按凭证与订阅创建步骤处理。

Campaign 来源的提交需要被接受并完成奖励授予,才能进入可读取范围;实际返回还受交付、订阅和筛选条件影响。网页里的 Copy 只复制命令,不执行请求或下载文件。

准备请求

由负责接入的人员在自己的终端或服务端程序中执行。以下适用于 macOS zsh 或 bash;交互输入避免把完整 Key 直接写进命令历史:

printf 'API Key: '
read -rs HB_API_KEY
printf '\nSubscription ID: '
read -r HB_SUBSCRIPTION_ID

增量读取

默认增量请求会推进订阅的读取位置,并可能按订阅价格计费:

curl --get 'https://api.humanbased.ai/v1/live/pull' \
  --header "Authorization: Bearer $HB_API_KEY" \
  --data-urlencode "subscription_id=$HB_SUBSCRIPTION_ID" \
  --data-urlencode 'limit=50'

检查 success 和 data.items。返回 has_more=true 时,重复增量请求读取下一页。

读取位置按订阅共享,不按 Key 隔离。 同事或其他程序读取同一订阅,也会影响进度。需要保留返回内容时,先保存到自己的系统;再次增量请求不会自动重发上一页。

从头分页读取

使用 from=beginning,不会推进增量读取位置:

curl --get 'https://api.humanbased.ai/v1/live/pull' \
  --header "Authorization: Bearer $HB_API_KEY" \
  --data-urlencode "subscription_id=$HB_SUBSCRIPTION_ID" \
  --data-urlencode 'limit=50' \
  --data-urlencode 'from=beginning'

若 has_more=true,复制刚返回的 next_cursor 字符串,不含 JSON 两侧引号:

printf 'Next cursor: '
read -r HB_CURSOR
curl --get 'https://api.humanbased.ai/v1/live/pull' \
  --header "Authorization: Bearer $HB_API_KEY" \
  --data-urlencode "subscription_id=$HB_SUBSCRIPTION_ID" \
  --data-urlencode 'limit=50' \
  --data-urlencode 'from=beginning' \
  --data-urlencode "cursor=$HB_CURSOR"

每页使用最新返回的游标,直到 has_more=false。第一页如有 task_ids 或 campaign_ids 筛选,后续页保留相同筛选;这些筛选不能用于默认增量请求。

零价订阅的从头读取覆盖其范围内已交付的记录,包括增量尚未取过的记录。收费订阅仍限于该订阅已经取得的范围,不能绕过计费读取新数据。两者都不扩大订阅授权。

检查结果

空 items 不等于取得了完整数据集,也不能证明从未有提交。依次检查订阅范围、交付状态、读取模式和筛选。

记录中的 created_at 是原提交时间,返回顺序按交付记录内部顺序分页。需要去重时核对 submission_id。

响应结构与用量见接口与字段;请求失败见错误处理。