Asynchronous requests

Every search you submit becomes a job. A request that spans multiple AI surfaces or carries a webhook runs asynchronously: you get an immediate acknowledgment, and the actual captures run durably in the background. (A single-surface request with no webhook runs synchronously by default — add ?mode=async to force the durable path for it too.)

The async model

An async POST /v1/search returns 202 Accepted right away with a parent job. The parent fans out into one child per surface × region — that’s the unit of work that actually runs a capture and produces an Envelope.

curl -X POST https://api.aisearchapi.dev/v1/search \
  -H "Authorization: Bearer $AISEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "best crm for startups",
    "surfaces": ["chatgpt", "perplexity"],
    "regions": [{ "country": "US" }, { "country": "GB" }]
  }'

const res = await fetch('https://api.aisearchapi.dev/v1/search', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.AISEARCH_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: 'best crm for startups',
    surfaces: ['chatgpt', 'perplexity'],
    regions: [{ country: 'US' }, { country: 'GB' }],
  }),
});
const job = await res.json();

import os, requests

res = requests.post(
    "https://api.aisearchapi.dev/v1/search",
    headers={
        "Authorization": f"Bearer {os.environ['AISEARCH_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "query": "best crm for startups",
        "surfaces": ["chatgpt", "perplexity"],
        "regions": [{"country": "US"}, {"country": "GB"}],
    },
)
job = res.json()

The 202 response names the parent and lists its children — here, 2 surfaces × 2 regions = 4 children:

{
  "jobId": "job_8t2q",
  "status": "processing",
  "children": [
    "job_8t2q.chatgpt.us",
    "job_8t2q.chatgpt.gb",
    "job_8t2q.perplexity.us",
    "job_8t2q.perplexity.gb"
  ]
}

The response also carries X-Request-Id, X-AISearch-Version, and the live X-RateLimit-* / X-Concurrency-* admission headers. For a single surface where you’d rather block and get the result inline, that’s the sync default (or force it with ?mode=sync / Prefer: wait=30).

Parent vs child ids

The shape of a job id tells you what you’ll get back when you read it.

Parent id

no dots — e.g. job_8t2q

Resolves to the fan-out summary: { job, children[] }. Use it to see overall status and enumerate children.

Child id

dotted — e.g. job_8t2q.chatgpt.us

Shaped job_<id>.<surface>.<regionKey>: three segments, the surface and the lowercased region key (country[:city][:language], or GLOBAL when untargeted). Resolves to the canonical Envelope, the answer and its provenance, for exactly one surface in one region.

Both are read through the same endpoint, GET /v1/jobs/:id. The id you pass decides which shape comes back. Never construct child ids by hand — use the ids the API returns.

Lifecycle states

State	Kind	Meaning
`queued`	Active	Accepted, waiting to run.
`running`	Active	A child’s capture is in progress.
`processing`	Active	Parent only — children are still in flight.
`completed`	Terminal	Finished successfully.
`partial`	Terminal	Parent only — some children completed, some failed.
`failed`	Terminal	Did not produce a result.
`canceled`	Terminal	Stopped before completion.
`expired`	Terminal	Aged out before running.

A polling loop must stop on any terminal state — not just completed. Treat completed, partial, failed, canceled, and expired as “done.”

Parent rollup rules

A parent’s status is derived from its children:

completed — every child completed.
failed — every child failed.
partial — a mix of completed and failed children.

While any child is still in flight, the parent stays processing.

A child can complete even when the surface returned nothing. In that case the Envelope has provenance.surfacePresent: false, an empty answer, and a surface_absent warning — the job is still completed, and an empty capture is not charged. See The Envelope.

How to read results

You have two ways to collect results after the 202.

Poll the parent for status

GET /v1/jobs/job_8t2q returns the current parent status and every child’s status. Stop as soon as the parent reaches a terminal state.

Read each child Envelope

For every child that reached completed (or partial’s completed children), GET /v1/jobs/job_8t2q.chatgpt.us to fetch its full Envelope.

A parent GET looks like this:

{
  "job": {
    "id": "job_8t2q",
    "status": "processing",
    "children": [
      "job_8t2q.chatgpt.us",
      "job_8t2q.chatgpt.gb",
      "job_8t2q.perplexity.us",
      "job_8t2q.perplexity.gb"
    ]
  },
  "children": [
    {
      "id": "job_8t2q.chatgpt.us",
      "surface": "chatgpt",
      "region": "us",
      "status": "completed"
    },
    {
      "id": "job_8t2q.chatgpt.gb",
      "surface": "chatgpt",
      "region": "gb",
      "status": "completed"
    },
    {
      "id": "job_8t2q.perplexity.us",
      "surface": "perplexity",
      "region": "us",
      "status": "completed"
    },
    {
      "id": "job_8t2q.perplexity.gb",
      "surface": "perplexity",
      "region": "gb",
      "status": "running"
    }
  ]
}

Then read a finished child:

curl https://api.aisearchapi.dev/v1/jobs/job_8t2q.chatgpt.us \
  -H "Authorization: Bearer $AISEARCH_API_KEY"

const res = await fetch(
  'https://api.aisearchapi.dev/v1/jobs/job_8t2q.chatgpt.us',
  { headers: { Authorization: `Bearer ${process.env.AISEARCH_API_KEY}` } },
);
const envelope = await res.json();

import os, requests

res = requests.get(
    "https://api.aisearchapi.dev/v1/jobs/job_8t2q.chatgpt.us",
    headers={"Authorization": f"Bearer {os.environ['AISEARCH_API_KEY']}"},
)
envelope = res.json()

A minimal poll loop

Node

async function waitForJob(parentId) {
  const terminal = ['completed', 'partial', 'failed', 'canceled', 'expired'];
  while (true) {
    const res = await fetch(`https://api.aisearchapi.dev/v1/jobs/${parentId}`, {
      headers: { Authorization: `Bearer ${process.env.AISEARCH_API_KEY}` },
    });
    const { job, children } = await res.json();
    if (terminal.includes(job.status)) return children;
    await new Promise((r) => setTimeout(r, 2000));
  }
}

For fan-out — many surfaces, many regions — prefer webhooks over polling. Register webhook: { url, secret } on the search and you’ll receive an HMAC-signed POST as each child reaches its terminal state, with the full Envelope in the payload. It’s fewer requests and lower latency than a poll loop. See Webhooks.

The Envelope

The canonical shape a child job resolves to.

Webhooks

Get pushed each child’s result instead of polling.

Introduction

Guides

The async model

Parent vs child ids

Lifecycle states

Parent rollup rules

How to read results

A minimal poll loop

The Envelope

Webhooks

​The async model

​Parent vs child ids

​Lifecycle states

​Parent rollup rules

​How to read results

​A minimal poll loop

The Envelope

Webhooks

The async model

Parent vs child ids

Lifecycle states

Parent rollup rules

How to read results

A minimal poll loop