Skip to main content
There is no synchronous endpoint. Querying an AI engine takes seconds to minutes, so every request becomes a durable queued task that you collect later.

​
Lifecycle

​
Statuses

​
status
Accepted and durable. Waiting for a worker.
​
status
A worker holds a lease on the task and is driving the engine.
​
status
Terminal. The response field is populated.
​
status
Terminal. The error field carries the reason.
A task that hits a transient failure (engine timeout, transient error) returns to QUEUED and is retried. Only once retries are exhausted does it settle in FAILED, so PROCESSING → QUEUED transitions are normal and not something to alarm on.

​
Priority

priority accepts 1 through 10, higher wins. Values outside that range are clamped rather than rejected. Defaults to 1.
Priority orders the queue; it does not reserve capacity. A high-priority task still waits behind whatever is already PROCESSING.

​
Retention

Terminal tasks are available through public polling for 24 hours after completion. After that, GET /v1/async/task/{id} returns 404 NOT_FOUND — the same response as an id that never existed. The underlying record is retained permanently; expiry limits public polling and manual webhook replay, not storage. Automatic webhook retries continue independently. If you rely on polling rather than webhooks, collect results well inside that window.

​
Choosing webhook or polling

Prefer webhooks. Polling is the recovery path. A robust client does both: take the webhook as the fast path, and reconcile anything you never heard about by polling before the retention window closes.