Async jobs

Some work can’t finish inside a single request — a multi-page document analysis runs for minutes, in a separate worker. Those ops return a job ticket immediately instead of a result. You then poll the job or wait for a webhook; when it’s done, the result is inline on the job or delivered to a baton you named.

The shape

1. Submit. Call the async op (the first is multi-page Textract — POST /v1/doc/analyze-async). It returns a ticket:

   { "ticket": "...", "job_id": "...", "status": "running", "ceiling_micros": 42000 }

2. Wait. Either poll GET /v1/jobs/{id} until the status is terminal, or subscribe to the job.completed webhook and let it push you the finished job. (Polling and the webhook are two ways to learn the same thing — use whichever fits your runtime.)

3. Collect. When the job succeeds, the result is available on the job record — inline, or, if you passed a deliver: { batonId } at submit, written into that baton.

Statuses

GET /v1/jobs/{id} reports one of five statuses:

submitted and running are the in-flight states; succeeded, failed, and expired are terminal — once a job reaches one, it doesn’t change.

Billing, in plain terms

The counted work (for Textract, the page count) is measured at submit, so the ceiling is known up front. How it settles depends on your payment rail:

• x402 (lodestone). The counted ceiling settles at submit — one clean on-chain settle. The compute finishes later; only the result is deferred, not the payment. If the job then fails for an infrastructure reason, the shortfall is made good off-chain.
• Balance / API key. A hold is authorized at submit, and the actual is captured at completion (the result is delivered before the capture). A failed job releases the hold — you’re made whole.

Either way: a job that fails for a reason on our side does not cost you. See Receipts and cost-plus for how the ceiling-vs-charged figures read on the receipt.

First consumer

The first async op is multi-page Textract — POST /v1/doc/analyze-async in Document AI. More long-running ops will join this lane; they all speak the same ticket → poll / webhook → result contract.

Next

Document AI · Webhooks · Receipts and cost-plus · Quickstart · API reference