Options and jobs
Every option has a default; set only those you need. Each extraction then runs in the background as a job.
Tier
standard ($0.03 a page, the default) suits most documents. pro ($0.05 a page) uses a stronger model, for the hardest: values worked out across many pages, diagrams, dense charts and long single-sheet drawings.
job = client.extract("report.pdf", schema, tier="pro")
Some pages only
Extract from one page or a range of pages; only they are read, and only they are charged. All pages when left out.
job = client.extract("report.pdf", schema, pages="30-60") # or (30, 60), or 30 for one page
print(job["usage"]["pages"]) # 31: only these are charged
The page each row came from
With cite_sources, the result also gives the page each list item is on, keyed by the item's path in the result (a JSON Pointer), to check a value against the page it came from.
job = client.extract("report.pdf", schema, cite_sources=True)
print(job["extract_metadata"]["field_metadata"]) # {"/segments/0": {"page": 34}, "/segments/1": {"page": 34}, ...}
Instructions
Anything to know about the whole document, not one field: the units it uses, which of two versions of a table to take, what to leave out. Up to 4,000 characters. What is about one field belongs in that field's description (see Writing a schema).
job = client.extract("report.pdf", schema,
system_prompt="Amounts are in thousands of dollars. Ignore the restated 2023 figures.")
A document you have uploaded
Pass a document's id in place of a file's path. A document still being processed is waited for first.
doc_id = client.submit_document("report.pdf")["doc_id"]
job = client.extract(doc_id, schema)
Jobs
Most extractions finish in a minute or less; long, hard documents take several minutes.
Status
| Status | What it means |
|---|---|
pending | Waiting to start. |
running | Reading the document. |
completed | Done: the result is there, and the pages are charged. |
failed | It could not be finished; the reason is given. Nothing is charged. |
cancelled | You stopped it. Nothing is charged. |
A job, once completed:
{
"id": "ext_7b56d419dd0a4d7eafa68e4c",
"status": "completed",
"doc_id": null,
"configuration": {"data_schema": {…}, "tier": "standard", "cite_sources": true},
"created_at": "2026-11-15T17:29:15.485000",
"updated_at": "2026-11-15T17:31:02.891000",
"extract_result": {"company": "Acme Industries plc", "segments": […]},
"extract_metadata": {"field_metadata": {"/segments/0": {"page": 34}, …}},
"usage": {"pages": 93, "credits": 279.0}
}
doc_idis the document extracted from, ornullfor a file.usage.creditsis what the extraction cost; a credit is $0.01.- A failed job has
error_messagein place of the result.extract()raises for a job that failed or was cancelled. - Times are UTC.
Start now, get the result later
extract() waits for the result by default, up to an hour (timeout, in seconds). To start an extraction and come back for it, keep its id and wait, or get it, later.
job = client.extract("report.pdf", schema, wait=False) # returns at once, pending
print(job["id"])
# later, or in another process
job = client.wait_extract(job["id"]) # completed; raises if it failed, was cancelled or timed out
print(job["extract_result"])
List, cancel and delete
page = client.list_extracts(limit=20) # newest first, without results; up to 100 a page
for job in page["jobs"]:
print(job["id"], job["status"])
# the ones after: client.list_extracts(after=page["next"]), until next is None
client.get_extract("ext_7b56d419dd0a4d7eafa68e4c") # one, with its result once completed
client.cancel_extract("ext_7b56d419dd0a4d7eafa68e4c") # stop it; nothing is charged
client.delete_extract("ext_7b56d419dd0a4d7eafa68e4c") # delete it and its result
Deleting a job that is still running stops it first.