# 通过 API 获取数据


在 API Keys 页的 **Pull data with your API key** 区域，使用 **Pull from** 确认数据源和 Subscription ID。这里只有一个源时不一定显示下拉框；显示 **No subscription yet** 时，先按[凭证与订阅创建步骤](/versions/2026-10-08/api/api-auth)处理。

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

## 准备请求

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

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

## 增量读取

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

```sh
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`，不会推进增量读取位置：

```sh
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 两侧引号：

```sh
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`。

响应结构与用量见[接口与字段](/versions/2026-10-08/api/api-fields)；请求失败见[错误处理](/versions/2026-10-08/api/api-errors)。