Cut a PDF into child files by page range
Classify decides. Split cuts — it runs no model, has no classes and no configuration.
PDF only. Office, image, audio and video inputs fail the run with unsupported_split_source.
Send exactly one of:
segments— your own ranges, 1-based inclusive, ascending, non-overlapping, at most 100. Gaps are allowed. This path costs no model call at all.classifyRunId— a page-mode classify run on the same file. Itssegments[]are used as-is, withclassIdandconfidenceechoed onto each child.
Each child is a real file with its own fileId, ready for POST /v1/extract; output.documentIds is the same list flattened. Children inherit the parent’s metadata, gain metadata.parentRunId, land in the parent’s space and share the run’s TTL — call keep to move parent and children together.
Send materialize: false to get the ranges back without creating anything: the safe first call on a large packet.
Children are parsed right after the split, so they are immediately usable by any verb. Each child’s parse is billed as a normal parse. usage itemizes it.
Waiting for the result
Sync by default: the call holds open until the run finishes, up to ?wait= seconds (default 60, max 120, 0 returns immediately).
Learn more: Split guide
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Path parameters
Query parameters
How many seconds to hold the request open waiting for the run to finish.
Finishing inside the window returns 200 with the full run; running past it returns 202 with a statusUrl to poll. Send 0 to skip waiting entirely and always get the 202.
Request
An input file, given one of two ways.
{ "url": "…", "name"?: "…", "processing"?: "…" }— fetched over http(s) for this run and purged with it.{ "id": "…" }— a file you already registered withPOST /v1/files, reusable across runs and never re-parsed.
The ranges to cut, 1-based inclusive, ascending and non-overlapping, at most 100. Gaps are allowed — drop a separator page on purpose. Send this or classifyRunId, never both.
A page-mode classify run to take the ranges from. Its output.segments are copied verbatim, classId and confidence included. The run must be on the same file and must not have expired.
Whether to create the child files. false returns the ranges only and creates nothing — the safe first call on a large packet.
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
Where the run is in its life.
The last four are terminal.
Why the run failed. Present whenever status is failed, and only then.
code is the stable, snake_case reason (input_unavailable, parse_failed, …); message is the human-readable detail. Per-file and per-step failures are also reported in files[].error and, for a pipeline, steps[].error.
The children. Present once status is processed.
splits[].fileId is the authoritative id of each child, ready for POST /v1/extract; documentIds[] is the same list flattened. classId and confidence are echoed from whatever you supplied — split has no opinion about what a page is. With materialize: false the ranges come back with no fileId.