Extract from many files in one call | CloudRaker documentation

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 and ttl are copied onto every run, so one webhook endpoint receives all of them.

1 {
2   "action": "invoice-fields",
3   "files": [{ "id": "a04d6597-…" }, { "url": "https://example.com/invoice-2.pdf" }],
4   "metadata": { "batch": "2026-07-25-invoices" }
5 }

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

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` and `ttl` are copied onto every run, so one webhook endpoint receives all of them. ```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.

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

Runs one saved extraction action over up to 100 files, creating one ordinary run per file.

metadata, webhook and ttl are copied onto every run, so one webhook endpoint receives all of them.

1 {
2   "action": "invoice-fields",
3   "files": [{ "id": "a04d6597-…" }, { "url": "https://example.com/invoice-2.pdf" }],
4   "metadata": { "batch": "2026-07-25-invoices" }
5 }

The whole batch costs a single request against your rate limit, however many files it fans out to.

Learn more: Extraction guide

$	curl -X POST https://api.cloudraker.com/v1/extract/batch \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"action": "act_01JQ8ZKMRT4V6WXYZ0ABCDEFGH",
>	"files": [
>	{
>	"url": "string"
>	}
>	]
>	}'

1	{
2	"object": "string",
3	"count": 1.1,
4	"runs": [
5	{
6	"file": {
7	"url": "string",
8	"name": "string",
9	"processing": "auto"
10	},
11	"id": "string",
12	"statusUrl": "string",
13	"error": {
14	"code": "string",
15	"message": "string"
16	}
17	}
18	]
19	}

1	{
2	"action": "invoice-fields",
3	"files": [{ "id": "a04d6597-…" }, { "url": "https://example.com/invoice-2.pdf" }],
4	"metadata": { "batch": "2026-07-25-invoices" }
5	}