# 接口与字段参考


## 数据拉取

`GET https://api.humanbased.ai/v1/live/pull`

使用 `Authorization: Bearer <API_KEY>`。Key 需要覆盖目标订阅、有数据访问权限且未过期。

| 参数 | 说明 |
| --- | --- |
| `subscription_id` | 必填；目标数据订阅 |
| `limit` | 1–200，默认 50 |
| `from=beginning` | 从头分页读取本订阅可读范围 |
| `cursor` | 重读分页使用原样返回的 next_cursor |
| `task_ids`、`campaign_ids` | 重读时以逗号分隔 ID 缩小范围；不能扩大授权 |

增量与从头读取的进度、范围不同，见[请求步骤](/versions/2026-10-08/api/api-data)。

## 返回结构

外层包含 `success`、`errorCode`、`errorMessage` 和 `data`。成功时查看 `data`：

| 字段 | 含义 |
| --- | --- |
| `items` | 本次返回的数据条目 |
| `count` | 本次条目数量 |
| `has_more`、`next_cursor` | 后续页及返回的分页标记 |
| `receipt` | 本次计量回执；无收费记录时可能为空，历史重读为空 |

每条记录的 `data` 是交付内容。配置 ETL 后按约定输出字段读取，不一定与 Reviews 原表单字段同名；未映射字段也不一定对外输出。

## 用量

`GET https://api.humanbased.ai/v1/live/usage?limit=50`

使用相同的 Bearer Key，返回所属组织的计量回执，不按请求中的 Subscription ID 筛选。

核对费用时结合实际回执和 **Billing** 的数据使用记录。条目单价不是扣款凭证；历史重读空回执也不代表所有 API 或订阅免费。

名称包含 `task/template` 的接口用于任务模板，不能用作交付数据拉取。