Extract from many files in one call
Runs one saved extraction action over up to 100 files, creating one ordinary run per file.
A batch is fan-out sugar, not a new object: there is no batch id and nothing to poll for the batch as a whole. You get back a run id per file — read each one with GET /v1/runs/{id}, or list them together with GET /v1/runs using the metadata you attached.
A saved action is required. Inline schema and hints are accepted on POST /v1/extract only — running the same shape over a hundred files is exactly when that shape should be a reviewed, saved asset.
metadata, webhook, ttl and citations are copied onto every run, so one webhook endpoint receives all of them and one flag grounds the whole batch.
Always asynchronous. The response is 202 right away. runs[] has one entry per file, in the order you sent them: {id, statusUrl, file} when the run was created, or {file, error} when that one file could not start — the other runs still stand, and count reports how many were created.
The whole batch costs a single request against your rate limit, however many files it fans out to.
Learn more: Extraction guide
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Request
The saved action every run in the batch uses, by id or slug. Required.
Inline schema and hints are deliberately not accepted here: a batch runs one reviewed, versionable shape over many files.
Whether to ground each extracted value in the source document. Off by default — grounding is an explicit add-on, so send citations: true to ask for it.
When on, output.citations maps every extracted field to where it came from — fileId plus page and bounding box for documents, or a timecode for audio. A field the documents simply do not contain comes back as an entry with notFound: true and no location.
Arbitrary JSON you attach to the run and get back on every read of it.
Use it to carry your own identifiers — an order number, a customer id — so a webhook or a polled run reconciles without a lookup table. Capped at 10 KB serialized.
Where to deliver this run's events, given one of two ways.
{ "url": "…" }— a one-off https endpoint for this run only.{ "id": "whe_…" }— a saved endpoint fromPOST /v1/webhooks. Runs hold the reference, so pausing or re-pointing that endpoint applies to this run too.
Deliveries are at-least-once and signed — dedupe on eventId and verify against GET /v1/webhooks/jwks.json.
How long, in seconds, to keep this run and its files before purging them automatically.
The maximum is 604800 (7 days). The deadline comes back as expiresAt on every read of the run. Call POST /v1/runs/{id}/keep before then to clear the TTL and move the results into a space permanently.
E-signature runs are exempt — an envelope waits for its signers however long that takes.
Response
Accepted — one run per file.