Async status

GET /v1/async/status returns a live snapshot of everything currently in flight for your API key: how deep your admission queue is versus its capacity, how much of your sync concurrency budget is in use, and your inflight children grouped by region. It takes no parameters — it always reports the current state of the key making the request. Use it as a pacing signal. Before you fire a large batch of captures, read this endpoint to see how much headroom you have, then throttle your submissions to stay under your limits instead of discovering them through 429 responses.

This is a read-only snapshot and never counts against your credits. It reflects state at the moment of the request and can change immediately as work is admitted and completed.

Request

curl https://api.aisearchapi.dev/v1/async/status \
  -H "Authorization: Bearer $AISEARCH_API_KEY"

const res = await fetch('https://api.aisearchapi.dev/v1/async/status', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.AISEARCH_API_KEY}`,
  },
});

const status = await res.json();

import os, requests

res = requests.get(
    "https://api.aisearchapi.dev/v1/async/status",
    headers={"Authorization": f"Bearer {os.environ['AISEARCH_API_KEY']}"},
)

status = res.json()

Response

200 OK

{
  "queue": {
    "depth": 12,
    "capacity": 200
  },
  "concurrency": {
    "limit": 8,
    "running": 3,
    "queued": 12
  },
  "inflight": {
    "byRegion": {
      "us": 18,
      "gb": 6,
      "GLOBAL": 3
    }
  }
}

queue

object

The async admission queue for your key. New async submissions wait here before their children begin processing.

Show queue

depth

integer

Number of submissions currently waiting in the admission queue.

capacity

integer

Maximum the queue can hold. When depth reaches capacity, new submissions are rejected with 429 QUEUE_CAPACITY_EXCEEDED.

concurrency

object

Your synchronous concurrency budget — the number of sync captures (the single-surface default, ?mode=sync, or Prefer: wait=30) that can run at the same time.

Show concurrency

limit

integer

Maximum sync captures that may run concurrently for your key.

running

integer

Sync captures running right now. When running reaches limit, further sync requests return 429 CONCURRENCY_LIMIT_EXCEEDED.

queued

integer

Async work currently waiting in the admission queue (mirrors queue.depth).

inflight

object

Your children currently active (queued or running), counted in one owner-scoped pass.

Show inflight

byRegion

object

Inflight child counts keyed by canonical region key (lowercased country[:city][:language], or GLOBAL for untargeted). Regions with nothing in flight are omitted.

Pace submissions to avoid 429s

Every 429 your key can receive maps to a field in this snapshot, so you can preflight against it:

You want to avoid	Watch	Headroom formula
`QUEUE_CAPACITY_EXCEEDED`	`queue`	`capacity - depth`
`CONCURRENCY_LIMIT_EXCEEDED`	`concurrency`	`limit - running`
`RATE_LIMIT_EXCEEDED`	request rate (see `X-RateLimit-*` headers)	—

Read the snapshot before a batch

Poll GET /v1/async/status right before submitting a large set of captures.

Compute your headroom

For async work, keep submissions under queue.capacity - queue.depth. For sync work, keep concurrent calls under concurrency.limit - concurrency.running.

Throttle, then submit

Submit up to your headroom, let some children drain, and re-read the snapshot before the next wave rather than retrying blindly.

Prefer async submission for large batches. A single POST /v1/search fans out into one child per surface × region and only occupies the admission queue, leaving your sync concurrency budget free for latency-sensitive, one-surface calls.

This snapshot is advisory, not a reservation. Between reading it and submitting, other requests on the same key can consume headroom. Always still handle 429 responses by honoring the Retry-After header.

Concurrency & limits

How the rate limit, sync concurrency budget, and admission queue fit together — and how to back off cleanly.

Asynchronous captures

Submit a parent job, fan out across surfaces and regions, and poll children as they complete.

Endpoints

Account & discovery

Watches

By surface

Request

Response

Pace submissions to avoid 429s

Concurrency & limits

Asynchronous captures

​Request

​Response

​Pace submissions to avoid 429s

​Related

Concurrency & limits

Asynchronous captures

Request

Response

Pace submissions to avoid 429s

Related