按需查阅，不是必读接入步骤。接入路线：[查询取数接入路线](/docs)

# 按需采集新数据

实时采集查询用于请求平台上的新数据。它不是[数据获取](/docs/search)的替代：已有数据应通过检索 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 秒。只读取已经采集的用户资料或用户内容时，使用[用户取数接口](/docs/browse)，无需创建新任务。


```mermaid
sequenceDiagram
  participant App as 应用
  participant API as Whale API
  participant Collector as 采集器
  participant Store as 数据中心
  App->>API: 创建实时查询
  API-->>App: 202 + live_query_id
  API->>Collector: 派生采集任务
  Collector->>Store: 异步入库
  Collector->>API: 完成任务 + document_ids
  App->>API: 轮询状态
  API-->>App: 平台结果
```


## 创建查询

`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](/public-api-reference)。

## 继续当前任务

[返回接入路线](/docs)；查完所需信息后，回到正在执行的步骤。