按需采集新数据

实时采集查询用于请求平台上的新数据。它不是数据获取的替代：已有数据应通过检索 API 获取；只有需要触发新的采集时才创建实时查询。Whale 将请求派发给匹配能力的采集器并异步写入数据中心，不会直接转发第三方平台请求，也不承诺单个 HTTP 请求内完成。

使用前提

实时查询默认关闭。应用必须使用有效 Consumer API Key，其订阅和访问策略允许目标数据集与平台，且 Whale 平台已为你的应用开启 rate_limit_policy.live_query_enabled=true。每个目标平台还必须有在线采集器，并已注册 live_query 和对应能力。

v1 支持 content、account、user、channel、video；具体可用能力取决于平台、采集器和订阅授权。单次选择 1-5 个平台，最多 100 条/平台，最长等待 900 秒。只读取已经采集的用户资料或用户内容时，使用用户取数接口，无需创建新任务。

创建查询

Idempotency-Key 必填且须稳定。网络重试必须复用同一值，系统会返回原请求而不是重复创建采集任务。

Bash

live_response="$(curl -sS --fail-with-body -X POST "$WHALE_BASE_URL/v1/live-queries" \
  -H "Authorization: Bearer $WHALE_API_KEY" \
  -H "Idempotency-Key: product-search-20260909-001" \
  -H "Content-Type: application/json" \
  -d '{
    "dataset_id":"social_media_raw",
    "resource_kind":"video",
    "query":"AI agent",
    "source_platforms":["youtube","weibo"],
    "language":"en",
    "max_items":20,
    "deadline_seconds":300
  }')"
printf '%s' "$live_response" | jq .
LIVE_QUERY_ID="$(printf '%s' "$live_response" | jq -er '.live_query.id')"

字段	必填	说明
`dataset_id`	是	已授权的数据集。
`resource_kind`	是	`content`、`account`、`user`、`channel` 或 `video`；并非每个平台都支持所有类型。
`query` / `url` / `external_id`	至少一个	关键词、目标链接或平台资源 ID。
`source_platforms`	是	目标平台，数量 1-5。
`language` / `region`	否	平台适配器支持时用于缩小范围。
`max_items`	否	每平台最大条数，1-100，默认 20。
`deadline_seconds`	否	等待上限，10-900，默认 300。

新请求返回 202，幂等重放返回 200：

JSON

{
  "live_query":{"id":"lq_01K4...","status":"pending","resource_kind":"video"},
  "runs":[{"source_platform":"youtube","collection_task_id":"ctask_01K4...","status":"pending"}]
}

轮询与读取结果

Bash

curl -sS --fail-with-body "$WHALE_BASE_URL/v1/live-queries/$LIVE_QUERY_ID" \
  -H "Authorization: Bearer $WHALE_API_KEY"

从 2 秒间隔开始轮询，并采用指数退避；不要对同一个查询并发轮询。状态可为 pending、collecting、partial、succeeded、failed、canceled。每个 runs[] 对应一个平台，包含任务状态、last_error 和 result。

完成后，推荐使用实时查询结果接口读取经过权限过滤的数据。该接口会继续执行应用的字段权限、数据集/平台授权和用量审计：

Bash

curl -sS "$WHALE_BASE_URL/v1/live-queries/$LIVE_QUERY_ID/results?limit=20" \
  -H "Authorization: Bearer $WHALE_API_KEY"

接口支持 cursor 和 limit（1-100）分页。查询处于 pending 或 collecting 时返回 409 live_query_results_not_ready；查询完成后返回 items、limit 和可选的 next_cursor。next_cursor 是不透明游标，只能用于当前实时查询。 runs[].result.document_ids 仍然保留，适合按平台对账和排障。文档可能在任务结束前已可搜索；视频字幕、指标和分析标签也可能在主内容后异步补齐。

积分、限流和错误

实时查询按每个平台 run 预扣积分，预扣数量为 max_items。任务成功或部分成功后，系统根据实际返回的 document_ids 结算，未使用部分自动退回；任务失败、取消或派发失败时全额退款。同一应用重复使用同一个 Idempotency-Key 不会重复创建任务或重复预扣。

访问策略可以配置以下实时查询限制：

JSON

{
  "live_query_enabled": true,
  "live_query_daily_limit": 1000,
  "live_query_max_items": 100,
  "live_query_max_concurrency": 2
}

live_query_daily_limit 按预扣 item 数量计算，live_query_max_items 限制每个平台 run 的最大条数，live_query_max_concurrency 限制同一应用同时处于活动状态的查询数。组织级和应用级策略同时存在时，应用只能使用两者都允许的更小范围和更低上限。

Bash

curl -sS --fail-with-body -X POST "$WHALE_BASE_URL/v1/live-queries/$LIVE_QUERY_ID/cancel" \
  -H "Authorization: Bearer $WHALE_API_KEY"

未认领任务会立即取消；运行中的采集器会收到取消信号。已入库文档不会删除。创建请求沿用应用实时限流，429 rate_limit_exceeded 包含 Retry-After: 1；应降低并发再重试。访问范围不匹配返回 403，无效请求返回 400 live_query_invalid，非当前应用的请求返回 404 live_query_not_found。

积分余额不足时请求会被拒绝；实时查询的计费明细可以在门户的应用用量和积分明细中查看。完整契约见 OpenAPI。