Batch search

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 validated 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 an async standalone POST /v1/search — it becomes 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 independently and supports the standard search body: query (or prompt), surfaces, regions, webhook, and a per-item idempotencyKey (see Idempotency below).

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": ["google_ai_overview"],
        "regions": [{ "country": "DE", "language": "de" }]
      },
      {
        "query": "",
        "surfaces": ["claude"]
      }
    ]
  }'

const res = await fetch('https://api.aisearchapi.dev/v1/search/batch', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.AISEARCH_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    items: [
      {
        query: 'best crm for startups',
        surfaces: ['chatgpt', 'perplexity'],
        regions: [{ country: 'US' }],
      },
      {
        query: 'cheapest ev in europe 2026',
        surfaces: ['google_ai_overview'],
        regions: [{ country: 'DE', language: 'de' }],
      },
      { query: '', surfaces: ['claude'] },
    ],
  }),
});

const { items } = await res.json();
for (const item of items) {
  if (item.status === 'accepted') {
    console.log(item.index, '->', item.jobId, item.children);
  } else {
    console.warn(item.index, 'rejected:', item.code, item.error);
  }
}

import os
import requests

res = requests.post(
    "https://api.aisearchapi.dev/v1/search/batch",
    headers={
        "Authorization": f"Bearer {os.environ['AISEARCH_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "items": [
            {
                "query": "best crm for startups",
                "surfaces": ["chatgpt", "perplexity"],
                "regions": [{"country": "US"}],
            },
            {
                "query": "cheapest ev in europe 2026",
                "surfaces": ["google_ai_overview"],
                "regions": [{"country": "DE", "language": "de"}],
            },
            {"query": "", "surfaces": ["claude"]},
        ]
    },
)

for item in res.json()["items"]:
    if item["status"] == "accepted":
        print(item["index"], "->", item["jobId"], item["children"])
    else:
        print(item["index"], "rejected:", item["code"], item["error"])

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 parent jobId and its child ids) or rejected (with the stable error code and message). A rejected item does not affect any other item in the batch.

Response

{
  "items": [
    {
      "index": 0,
      "status": "accepted",
      "jobId": "job_8t2q",
      "children": ["job_8t2q.chatgpt.us", "job_8t2q.perplexity.us"]
    },
    {
      "index": 1,
      "status": "accepted",
      "jobId": "job_5k9d",
      "children": ["job_5k9d.google_ai_overview.de:de"]
    },
    {
      "index": 2,
      "status": "rejected",
      "code": "VALIDATION_FAILED",
      "error": "query is required and must be a non-empty string (alias: prompt)"
    }
  ]
}

items

object[]

One result per submitted item, in request order.

Show item

index

number

Zero-based position of this item in the request items array.

status

string

accepted or rejected.

jobId

string

Present when status is accepted. The created parent job id (on a replay, the existing parent the item’s idempotencyKey already maps to). Poll GET /v1/jobs/:id or use a webhook to read results.

replayed

boolean

Present and true only when this item’s idempotencyKey replayed an existing parent (same key, same body). A replayed item is not re-billed and spawns no new work — its jobId points at the original parent. Omitted otherwise.

children

string[]

Present when status is accepted. One dotted child id per surface × region (job_<id>.<surface>.<regionKey>).

code

string

Present when status is rejected. The stable error code (e.g. VALIDATION_FAILED, UNSUPPORTED_SURFACE, UNSUPPORTED_METHOD_FOR_SURFACE, or IDEMPOTENCY_CONFLICT when an item reuses an idempotencyKey with a different body). See Errors.

error

string

Present when status is rejected. The human-readable message naming the offending field and allowed values.

Batch-level errors

Some conditions reject the whole batch before anything is spawned — as a standard flat error envelope, not per-item results:

Code	Status	When
`VALIDATION_FAILED`	400	`items` is missing, empty, or has more than 500 entries.
`INSUFFICIENT_CREDITS`	402	Your balance can’t cover the batch’s total planned children. The credit reservation is atomic over the whole batch — an insufficient balance rejects everything and nothing is spawned.
`RATE_LIMIT_EXCEEDED`	429	The submit-rate gate fired. Honor `Retry-After`.

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 (google_ai_overview, one region) creates one child. Item 2 was rejected and created nothing.

Batch is always asynchronous — there is no mode=sync for batch. Prefer webhooks over polling when submitting large batches so you are notified as each child reaches a terminal state.

Idempotency

Each batch item is an independent job, so a per-item idempotencyKey behaves exactly like it does on POST /v1/search — applied to that one item. Give each item its own key (a stable id from your side, e.g. a run id) and safely retry the whole batch after an ambiguous failure:

Same key, same body → the item is accepted with replayed: true and its original jobId. It is not re-billed and spawns no new work — poll that jobId for the already-running (or finished) results.
Same key, different body → the item is rejected with IDEMPOTENCY_CONFLICT (a per-item rejection — sibling items are unaffected). Use a fresh key whenever the payload changes.
New key → runs normally as a fresh submission.

Response — item 0 retried (replay), item 1 fresh

{
  "items": [
    {
      "index": 0,
      "status": "accepted",
      "jobId": "job_8t2q",
      "replayed": true,
      "children": ["job_8t2q.chatgpt.us", "job_8t2q.perplexity.us"]
    },
    {
      "index": 1,
      "status": "accepted",
      "jobId": "job_5k9d",
      "children": ["job_5k9d.google_ai_overview.de:de"]
    }
  ]
}

Retrying a whole batch where every item carries a stable idempotencyKey is safe: already-accepted items replay (no double-charge, no duplicate jobs) and only the genuinely-new items run.

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.

Endpoints

Account & discovery

Watches

By surface

Request

Response

Batch-level errors

Fan-out and billing

Idempotency

Search

Read a job

Webhooks

Errors

​Request

​Response

​Batch-level errors

​Fan-out and billing

​Idempotency

​Related

Search

Read a job

Webhooks

Errors

Request

Response

Batch-level errors

Fan-out and billing

Idempotency

Related