CloudRaker APICapabilities

Extract from many files in one call

View as Markdown
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}](https://docs.cloudraker.com/api/cloud-raker-api/runs/get-run), or list them together with [GET /v1/runs](https://docs.cloudraker.com/api/cloud-raker-api/runs/list-runs) using the `metadata` you attached. **A saved `action` is required.** Inline `schema` and `hints` are accepted on [POST /v1/extract](https://docs.cloudraker.com/api/cloud-raker-api/capabilities/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. ```json { "action": "invoice-fields", "files": [{ "id": "a04d6597-…" }, { "url": "https://example.com/invoice-2.pdf" }], "metadata": { "batch": "2026-07-25-invoices" } } ``` **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. <Note> The whole batch costs a single request against your rate limit, however many files it fans out to. </Note> **Learn more:** [Extraction guide](https://docs.cloudraker.com/capabilities/extract)

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
actionstringRequired>=1 character

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.

fileslist of objectsRequired
The input files, up to 100. Each one becomes its own run.
citationsbooleanOptional

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.

metadatamap from strings to anyOptional

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.

webhookobjectOptional

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 from POST /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.

ttlintegerOptional1-604800

How long, in seconds, to keep this run and its files before purging them automatically.

Defaults to 24 hours; 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.

object"extract_batch"
countdouble
runslist of objects

Errors

400
Bad Request Error
422
Unprocessable Entity Error
429
Too Many Requests Error