批量搜索

POST https://api.serphubapi.com/v1/batch

一次往返跑最多 5 条搜索——同一个词搜多个来源，或者一个来源搜多个词。每一条都是普通的搜索请求，规则完全一样：路由与兜底、缓存、计费（失败、空结果、命中缓存不扣费）。一条失败不会影响其他条。

请求参数

参数	类型	说明
queries	array	必填。 1–5 条。每条的字段与 POST /v1/search 相同：q、engine、type、gl、hl、num、page、time_range、mode、include_content。

返回始终是 JSON，每条里的 format 会被忽略。

curl https://api.serphubapi.com/v1/batch \
  -H "X-API-Key: shapi_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"queries": [
    {"q": "wireless earbuds", "engine": "google", "gl": "us"},
    {"q": "wireless earbuds", "engine": "amazon", "type": "products"},
    {"q": "无线耳机", "engine": "xiaohongshu", "type": "notes"}
  ]}'

返回结果

只要请求本身合法就返回 200，每条的结果要分别看。返回顺序与请求顺序一致。

{
  "results": [
    {
      "query": { "q": "wireless earbuds", "engine": "google", "type": "web" },
      "results": { "organic": [ { "position": 1, "title": "...", "link": "https://..." } ] },
      "meta": { "id": "sch_01J9Z3KQ8W", "status": "success", "service": "google/web", "credits_charged": 10, "cached": false, "time_ms": 812 }
    },
    {
      "query": { "q": "wireless earbuds", "engine": "amazon", "type": "products" },
      "results": { "products": [ { "position": 1, "title": "...", "price": "$29.99" } ] },
      "meta": { "id": "sch_01J9Z3KR2A", "status": "success", "service": "amazon/products", "credits_charged": 10, "cached": false, "time_ms": 1530 }
    },
    {
      "query": { "q": "无线耳机", "engine": "xiaohongshu", "type": "notes" },
      "error": { "code": "insufficient_balance", "message": "..." },
      "meta": { "status": "failed", "credits_charged": 0 }
    }
  ],
  "meta": { "calls": 3, "total_credits_charged": 20 }
}

字段	说明
results[].query	该条的 q、engine、type，用来把结果和请求对上。
results[].results	与搜索返回中的 results 相同，成功时出现。
results[].content	该条设置了 include_content 时的网页正文。
results[].meta	该条自己的 meta，与搜索返回相同。每条成功的结果都有自己的 id，可用 GET /v1/searches/{id} 回看。
results[].error	失败时的 code 和 message，错误码同错误码。该条不扣费。
meta.total_credits_charged	所有条目实际扣费之和。

使用须知

• 各条依次执行，整批耗时约等于各条耗时之和。量大时，在限流范围内并行发多个批次。
• 每条执行时单独检查余额和 Key 限额。中途余额不足，后面的条目返回 insufficient_balance，不扣费。
• AI 来源也可以通过 engine 放进批量（如 "engine": "deepseek"），但每条都是同步等待。ChatGPT 这类要几分钟的来源可能超时，请改用 POST /v1/ai-search，它会返回异步任务。

错误

只有请求本身不合法时，整个请求才会失败：

HTTP	错误码	场景
400	validation_error	缺少 queries、为空或超过 5 条，或某一条参数不合法
401	invalid_api_key	Key 缺失、无效或已停用
429	rate_limited	触发限流