Async tasks: lifecycle, statuses and retention

Every request becomes a durable task. You submit it, get a task id back at once, and collect the result later by webhook or by polling. There is no synchronous endpoint.

curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "CHATGPT", "payload": { "prompt": "best CRM for a small team", "country": "US" } }'

The submit response is 200 with the task in QUEUED:

{
  "success": true,
  "task": {
    "id": "8f2c1e40-...",
    "taskType": "CHATGPT",
    "status": "QUEUED",
    "priority": 1,
    "createdAt": "2026-10-19T04:12:00.000Z"
  },
  "credits": { "creditsToCharge": 0, "creditsCharged": 0 }
}

Poll it with the id (reference):

curl https://api.querying.ai/v1/async/task/8f2c1e40-... \
  -H "Authorization: Bearer $QUERYING_API_KEY"

Lifecycle

Statuses

Status	Terminal	Meaning
`QUEUED`	No	Accepted and stored. Waiting for a worker.
`PROCESSING`	No	A worker holds the task and is driving the engine.
`COMPLETED`	Yes	`response` carries the engine result.
`FAILED`	Yes	`error` carries a string that starts with a failure code. See task failure codes.

A task that hits a transient failure returns to QUEUED and runs again. It settles in FAILED only after its retries run out, so a PROCESSING → QUEUED step is normal. Polling omits response until the task is terminal. A failed task has a top-level error string instead:

{
  "success": true,
  "task": { "id": "8f2c1e40-...", "taskType": "CHATGPT", "status": "FAILED", "priority": 1, "createdAt": "2026-10-19T04:12:00.000Z" },
  "credits": { "creditsToCharge": 0, "creditsCharged": 0 },
  "error": "ENGINE_TIMEOUT: The engine did not answer before the task deadline."
}

Credits on submit and on poll

Where	`credits` shows
Submit response	Always `0`. A hold for the task’s price is already placed on your balance.
Poll, `QUEUED` or `PROCESSING`	`0`
Poll, `COMPLETED`	The settled charge, for example `1` for `CHATGPT` or `1.25` for `GEMINI`
Poll, `FAILED`	`0`. The hold is released.
Webhook	Same charge as the terminal poll. See Webhooks.

Prices, holds and limits are on Credits and limits.

Priority

priority accepts 1 to 10 and defaults to 1. Values outside that range are clamped, not rejected. The value is echoed in task metadata.

{ "taskType": "GEMINI", "priority": 8, "payload": { "prompt": "best CRM for a small team", "country": "US" } }

Execution order is not guaranteed by priority, submission time or account. For dependent work, wait for the first task to complete before you submit the next one.

Retention

You can poll a terminal task for 24 hours after it completes. After that, GET /v1/async/task/{id} returns 404 RESOURCE_NOT_FOUND, the same response as an unknown id or another account’s task. QUEUED and PROCESSING tasks stay visible however old they are. The 24-hour window also applies to result bodies in GET /v1/batches/{id}/items and grid reads. It limits public polling, not storage: the task record is kept, and its idempotencyKey stays reserved after the window closes (see Idempotency). Automatic webhook retries run on their own schedule, independent of this window.

Webhook or polling

Prefer webhooks. Use polling to recover what you did not receive.

	Webhook	Polling
Latency to result	On completion	Your poll interval
Requests to the API	None	One per poll per task
Needs a public HTTPS endpoint	Yes	No
If your endpoint is down	Five attempts over about 30 minutes	Available for 24 hours after completion

A robust client does both: it takes the webhook as the fast path and polls for any task it has not heard about well inside the 24-hour window.

Get started

Core concepts

Answer engines

Search and web data

Request options

Research

GEO monitoring

Account and data

Async tasks: lifecycle, statuses and retention

Lifecycle

Statuses

Credits on submit and on poll

Priority

Retention

Webhook or polling

Next steps

Webhooks

Batches and grids

​Lifecycle

​Statuses

​Credits on submit and on poll

​Priority

​Retention

​Webhook or polling

​Next steps

Webhooks

Batches and grids

Lifecycle

Statuses

Credits on submit and on poll

Priority

Retention

Webhook or polling

Next steps