Skip to main content
A mode decides whether POST /documents waits for the finished document or answers at once. Both make the same document at the same price; only the response changes. This is useful for:
  • Direct: scripts, agent tools and short documents, where one call should return the file.
  • Background: queues, web requests that must answer fast, and batches of many documents.

How it works

In both modes the document keeps being made after the response, even if your client disconnects. Follow a 202 with GET /documents/{id}, GET /documents/{id}/events or webhooks. A direct 200 doesn’t mean the document worked: check status. A document that failed comes back as 200 with status: "failed" and its error.code (see when a document fails).
standard and best often take longer than 120 s, so a direct request at those levels usually gets a 202. For a finished document in under 120 s, use quality: "fast".

In the SDKs

documents.create() always returns a finished document: when the API answers 202, the SDK follows the document’s events until it finishes. documents.create_in_background() (Python) and documents.createInBackground() (TypeScript) return the 202 document at once.
wait() returns once the document is ready, failed or canceled, and reconnects on its own if the connection drops.

When to use each

Use direct when the caller can wait up to 120 s per request. Use background when it can’t, or when you start many documents at once: you can make up to 120 documents per minute per organization (see pricing).

Next steps

Follow the events

Show progress while a document is being made.

Receive webhooks

Get notified when a document finishes.