首次获取已授权数据 — Humanbased Docs

保存一小页交付记录，检查返回字段，并了解如何继续读取。

你可以从已有订阅开始，不需要先创建活动。本指南使用正式环境的 HTTP API，先从头读取最多五条记录。这次请求不会推进组织共享的增量读取位置。

开始前

准备安装了 curl 和 Python 3 的终端，以及：

目标订阅所属 Organization（组织）中的账户。
有效的 Subscription ID（订阅 ID）和覆盖该订阅的完整组织 API Key（接口密钥）。
允许你按预定目的获取和使用数据的适用条款。
至少一条符合条件的已交付记录。收费订阅只能重读此前已取得的范围。

Subscription ID 指定数据，API Key 证明组织和访问范围。Campaign ID 不能代替 Subscription ID。在网页看到数据，也不等于已经取得下载、转发或训练用途的授权；发送请求前，请与你的组织确认适用条款。

1. 找到订阅

打开正式环境 Developer 端的 API Keys 页面，先确认左下角的组织名称。然后在 Pull data with your API key（用你的 API 密钥拉取数据）区域找到 Pull from（拉取来源），选择目标来源并复制 subscription_id。只有一个来源时，页面可能直接显示名称，不出现下拉框。

如果显示 No subscription yet（尚无订阅），先不要执行示例命令。本组织自己的活动可由组织成员在创建 Key 时选择符合条件的活动，系统会建立或复用订阅。外部数据则需要先取得相应订阅和使用条件。创建 Key 本身不会购买访问权。

2. 取得适用的 Key

组织内任何成员都可以在该页面创建 Key。撤销时，创建者可以撤销自己创建的 Key，Owner 或 Admin 可以撤销组织内所有 Key。已有完整 Key 时，核对列表中的 Scope（范围）、Status（状态）和 Expires（有效期）；Active 状态不覆盖已过的到期日。

需要创建时：

选择 Create API Key（创建 API 密钥），填写能辨认用途的 Name（名称）。
选择 Expires，并在 Permissions → Data（权限中的数据访问）开启数据读取。不选择具体来源时，这把 Key 可读取组织目前及以后拥有的全部订阅。
要缩小范围，展开 Limit this key to specific subscriptions or campaigns，在 Subscription access（订阅访问权限）中选择目标来源；读取自有活动时也可在 Campaign access（活动访问权限）中选择符合条件的活动。
确认组织和范围，按页面要求完成协议步骤，再选择 Create key。
在 Your new API key（你的新 API 密钥）弹窗中复制完整 Key，存入组织认可的密钥保管位置。完整值只显示这一次。

活动标记为 partial（部分）时，新 Key 会复用现有订阅的较窄范围，不会自动扩权。范围不符时，请组织管理员检查订阅条件。

3. 准备小范围请求

在 bash 或 zsh 中执行以下命令。Key 在输入时不回显，也不会以明文直接出现在命令历史中。不要把它贴进智能体对话、截图、源码或浏览器地址。设置从 unset HB_API_KEY 开始：如果该变量此前已被导出，read 不会清除它的导出属性，Key 仍会传给你之后在这个终端启动的所有进程。

export HB_API_URL='https://api.humanbased.ai'
unset HB_API_KEY
printf 'API Key: '
read -rs HB_API_KEY
printf '\nSubscription ID: '
read -r HB_SUBSCRIPTION_ID

API 地址、订阅和凭证必须属于同一环境。测试环境使用 https://api.staging.humanbased.ai 及该环境签发的凭证。

4. 保存第一页

这次请求最多取五条记录，把响应保存到新的本地目录，并打印 HTTP 状态。请妥善保管输出目录中的数据。

HB_DOWNLOAD_DIR="$(mktemp -d)"
printf 'Response directory: %s\n' "$HB_DOWNLOAD_DIR"
curl --silent --show-error --get "$HB_API_URL/v1/live/pull" \
  --header "Authorization: Bearer $HB_API_KEY" \
  --data-urlencode "subscription_id=$HB_SUBSCRIPTION_ID" \
  --data-urlencode 'from=beginning' \
  --data-urlencode 'limit=5' \
  --output "$HB_DOWNLOAD_DIR/first-page.json" \
  --write-out 'HTTP %{http_code}\n'

保留 from=beginning。去掉它会切换为增量读取：增量位置由同一订阅的所有消费者共享，且可能产生费用。不要为了让空结果变成非空而直接切换模式。

5. 检查实际返回

在本地打开保存的 JSON：

python3 -m json.tool "$HB_DOWNLOAD_DIR/first-page.json"

成功响应的 success 为 true，errorCode 为 0；本页记录在 data.items，data.count 是本页数量。

字段	检查什么
`submission_id`、`task_id`、`campaign_id`	来源记录和任务；保留字符串形式的 ID。
`template_id`	交付内容对应的模板；空值表示未知。
`data`	已按交付结构提供的 JSON 内容，不必再次按 JSON 字符串解析。
`quality_grade`、`quality_score`	记录的等级及映射分数；不能据此证明模型性能提升。
`created_at`	原提交时间，不是本次请求完成时间。

交付字段可能来自对原提交的映射。按约定的输出结构读取，不要假定审核表单与 data 使用相同字段名。

一次请求只是一页。data.has_more=true 表示还有下一页；最后一页也仅完成当前订阅可读范围的遍历，不代表取得活动全部提交或一个永不变化的数据快照。

6. 需要更多时继续分页

复制最近一页 data.next_cursor 的字符串值，不带 JSON 引号。保持相同订阅、读取模式和筛选条件。

printf 'Next cursor: '
read -r HB_CURSOR
HB_NEXT_PAGE="$(mktemp "$HB_DOWNLOAD_DIR/page.XXXXXX")"
printf 'Response file: %s\n' "$HB_NEXT_PAGE"
curl --silent --show-error --get "$HB_API_URL/v1/live/pull" \
  --header "Authorization: Bearer $HB_API_KEY" \
  --data-urlencode "subscription_id=$HB_SUBSCRIPTION_ID" \
  --data-urlencode 'from=beginning' \
  --data-urlencode 'limit=5' \
  --data-urlencode "cursor=$HB_CURSOR" \
  --output "$HB_NEXT_PAGE" \
  --write-out 'HTTP %{http_code}\n'

每页保存成功后再继续，直到 has_more=false。游标是不透明的返回值，不能用 Submission ID 或自己生成的数字替代。如果显示还有下一页却没有 next_cursor，停止并保留响应以便排查。

需要用 hb CLI 一次导出某个活动的全部交付记录时，见导出全部交付记录。

没有取到记录时

结果	下一步
`401`	核对完整 Key、有效期、撤销状态和 `Bearer` 前缀。
`403`	核对 Key 的数据交付权限和订阅范围；不要改用其他组织的 Key 绕过权限。
`404` 或找不到订阅	请管理员核对订阅、组织和环境；Campaign ID 不能代填。
`success: true`，但 `items: []`	检查交付状态、筛选条件，以及收费订阅此前已取得的范围。已接受的工作可能仍待奖励授予或交付。
`400` 或 `422`	对照接口参考检查参数、页大小和模式。
`503` 或网络中断	稍后重试这次从头读取；只保留完整的成功响应作为有效页。

零价订阅可从头读取符合条件、已交付而增量尚未读取的记录；收费订阅只能重读已经取得的范围。重读时 receipt 为空，不表示底层数据免费或没有使用限制。

需要支持时，向 hello@humanbased.ai 提供环境、请求时间、HTTP 状态和脱敏错误，不要发送完整 Key 或私有数据内容。

完成标准

完成本指南时，你应已保存至少一条成功返回的记录，能识别它的来源和交付字段，并确认预定用途的条款。空的成功响应只说明请求成功，至少有一条记录才算取得了数据。

把读取时间、订阅、适用条款和来源标识与本地副本一起记录，并按数据要求妥善保存。响应本身不包含完整许可，也不固定某个数据集版本；订阅只说明你按哪个范围取得数据。数据集的 Snapshot & license（快照与授权）目前尚未开放，见数据使用范围。

下一步可读接口参考了解增量读取，或让智能体执行限定范围的读取。