Submit many searches in one request. POST /v1/search/batch accepts up to 500 items, where each item is a full search body. Items are admitted independently: a validation failure on one item never blocks the others.
Batch is a convenience for submission, not a different execution model. Each accepted item behaves exactly like a standalone POST /v1/search — it returns a parent job that fans out into one child per surface × region, and each child is billed and completed on its own.

​
Request

​
items
object[]
required
Array of 1–500 search bodies. Each element is validated and admitted independently. Every item supports the full search body — query, surfaces, regions, priority, webhook, and idempotencyKey.
curl https://api.aisearchapi.dev/v1/search/batch \
  -H "Authorization: Bearer $AISEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "query": "best crm for startups",
        "surfaces": ["chatgpt", "perplexity"],
        "regions": [{ "country": "US" }]
      },
      {
        "query": "cheapest ev in europe 2026",
        "surfaces": ["gemini"],
        "regions": [{ "country": "DE", "language": "de" }],
        "idempotencyKey": "ev-de-2026-06-30"
      },
      {
        "query": "",
        "surfaces": ["claude"]
      }
    ]
  }'

​
Response

Returns 200 with an items array that mirrors the request order. Each result carries the original index and is either accepted (with the created job) or rejected (with an error). A rejected item does not affect any other item in the batch.
Response
{
  "items": [
    {
      "index": 0,
      "status": "accepted",
      "job": {
        "id": "job_8t2q",
        "status": "processing",
        "children": ["job_8t2q.chatgpt.us", "job_8t2q.perplexity.us"]
      }
    },
    {
      "index": 1,
      "status": "accepted",
      "job": {
        "id": "job_5k9d",
        "status": "processing",
        "children": ["job_5k9d.gemini.de"]
      }
    },
    {
      "index": 2,
      "status": "rejected",
      "error": {
        "code": "VALIDATION_FAILED",
        "message": "query must be between 1 and 10000 characters",
        "status": 400,
        "details": [{ "path": "query", "message": "must not be empty" }]
      }
    }
  ]
}
​
items
object[]
One result per submitted item, in request order.

​
Fan-out and billing

Each accepted item becomes its own parent job with one child per surface × region. Credits are charged per child on a successful capture — an empty or failed capture costs nothing. In the example above, item 0 (chatgpt + perplexity, one region) creates two children, and item 1 (gemini, one region) creates one child. Item 2 was rejected and created nothing.
Batch is always asynchronous — there is no mode=sync for batch. Every accepted item returns a processing parent. Prefer webhooks over polling when submitting large batches so you are notified as each child reaches a terminal state.
Reuse idempotencyKey per item for safe retries. Resubmitting the same key with the same body replays the original job; the same key with a different body returns 409 IDEMPOTENCY_CONFLICT for that item only.

Search

The single-search endpoint and full request body.

Read a job

Poll a parent or read a child Envelope.

Webhooks

Get notified as each child completes.

Errors

Error codes returned on rejected items.