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

StatusWhat it means
pendingWaiting to start.
runningReading the document.
completedDone: the result is there, and the pages are charged.
failedIt could not be finished; the reason is given. Nothing is charged.
cancelledYou 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_id is the document extracted from, or null for a file.
  • usage.credits is what the extraction cost; a credit is $0.01.
  • A failed job has error_message in 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.