Task lifecycle

The SERP API is asynchronous. You submit a task and poll for its result — the crawl runs in the background so large batches never block your request.

States

A task moves through these states:

State	Meaning
`queued`	Accepted and waiting for a crawler.
`running`	Being crawled right now.
`done`	Finished — `result` is populated.
`error`	Failed after retries — `error` is populated and the charge is refunded.

queued ──▶ running ──▶ done
                   └──▶ error   (refunded)

A cache hit is created directly as done (see Caching below).

Polling

After POST /serp/tasks, poll GET /serp/tasks/{id} until status is done or error. The response always reflects the current state; result appears only once done, error only once error.

Guidelines:

Results usually land within a few seconds.
Back off between polls (e.g. start at 1–2s, grow with jitter) rather than hammering the endpoint — polling counts against your rate limit.
Reading a task never costs credits; only submitting one does.

Caching

Identical recent crawls are reused. If you submit a task whose keyword, region, device, and depth match a recent completed task, you get that result back immediately as done — no new crawl. Caching keeps latency and load down; it is not a way to avoid billing (cached tasks are still charged — see Credits & billing).

Correlation

Each task has a stable task_id (UUID) you use to poll and to reconcile results with your own records.