一个批次可容纳 1 万个任务

一个批次最多存放 1 万个任务，并按套餐上限逐步执行，所有付费套餐的并发任务数也同步提高。

获得的结果

• POST /v1/batches 最多接收 1 万项（32 MiB），每项有自己的 taskType 和 payload，返回 202 和批次。
• GET /v1/batches/:id 以等待、排队、处理中、已完成、失败、被拒绝的数量报告进度。
• GET /v1/batches/:id/items 按提交顺序列出各项，加上 include=response 会附带已完成的结果。
• 各套餐的并发任务数现为 Basic 25、Pro 150、Scale 500、Max 1,000（原为 10、25、50、100），Free 为 2。
• GET /v1/capabilities 列出每个引擎的输入字段、积分价格和国家策略，无需 API 密钥。

工作原理

批次会保存各项，并在套餐并发上限内把它们作为任务启动。需要等待的项保持待处理并自动启动，因此批次只需发送一次。

每一项在提交时按与单个任务相同的规则校验。只要有一项无效，整个批次就返回 400，列出最多 50 个项编号，并且不保存任何内容。重复使用同一个 idempotencyKey 会返回第一个批次。设置 webhook.url 后，每个任务的结果都会推送，批次结束时还会推送一次带签名的 batch.completed 事件。

应用场景

• 用一次提交，把一整天的问题发给所有引擎并持续追踪。
• 导入数千条关键词，按页读取结果。
• 用 /v1/capabilities 构建引擎和国家的选择列表。

发送请求

发送 items 数组。customId 是你给每一项起的标签，会随结果一并返回。

curl -X POST https://api.querying.ai/v1/batches \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "customId": "crm-chatgpt",
        "taskType": "CHATGPT",
        "payload": { "prompt": "best CRM for startups", "country": "US" }
      },
      {
        "customId": "crm-gemini",
        "taskType": "GEMINI",
        "payload": { "prompt": "best CRM for startups", "country": "US" }
      },
      {
        "customId": "crm-perplexity",
        "taskType": "PERPLEXITY",
        "payload": { "prompt": "best CRM for startups", "country": "US" }
      }
    ],
    "idempotencyKey": "daily-2026-10-09"
  }'

响应

调用返回 202 和批次。随着各项发出和完成，数量会随之变化。

{
  "success": true,
  "batch": {
    "id": "…",
    "status": "OPEN",
    "total": 3,
    "counts": {
      "pending": 3,
      "queued": 0,
      "processing": 0,
      "completed": 0,
      "failed": 0,
      "rejected": 0
    },
    "idempotencyKey": "daily-2026-10-09",
    "createdAt": "…"
  }
}

结果按提交顺序分页读取。每一项包含状态和任务 ID，加上 include=response 还会附带结果。

curl "https://api.querying.ai/v1/batches/$BATCH_ID/items?include=response&limit=20" \
  -H "Authorization: Bearer $QUERYING_API_KEY"

错误

因 PLAN_CONCURRENCY_LIMIT、QUEUE_BACKPRESSURE 或 KEY_DAILY_CREDIT_LIMIT 被拒绝的项保持待处理，批次会再次尝试。其他拒绝会让该项以 rejected 结束，并把代码写入 error。

VALIDATION_ERRORHTTP 400

缺少字段或取值超出范围。details 会指明该字段。

PAYLOAD_TOO_LARGEHTTP 413

请求体超过 1 MiB，批量请求超过 8 MiB。

KEY_SCOPE_DENIEDHTTP 403

该引擎在密钥的“允许的引擎”之外。换用其他密钥，或在“管理密钥”中添加该引擎。

INSUFFICIENT_CREDITSHTTP 402

余额低于任务价格。充值积分或升级套餐后再发送。

价格

每一项消耗的积分与该引擎单个任务相同。各套餐的上限见 https://querying.ai/pricing 。