Page Extract API

Extract fields and tables from a document as JSON that fits your JSON Schema. Each extraction runs in the background as a job: start it, then read it until it is done.

For writing schemas and choosing options, see the Page Extract quick start.

Start an extraction

POST /extract · WRITE key

Starts a job on one of your documents and answers 202 at once. Upload the document first, as in Upload a document to search.

NameTypeRequiredDefaultDescription
configurationstring (form)YesA JSON object.
doc_idstring (form)Yes, or fileA completed document of yours.
filefile (form)Yes, or doc_idA PDF, read for this job only and not stored as a document.

configuration holds:

NameTypeRequiredDefaultDescription
data_schemaobjectYesA JSON Schema (draft 2020-12) for the result. Its top is an object or an array. Up to 1,000,000 bytes.
tierstringNostandardstandard, or pro for the hardest documents.
cite_sourcesbooleanNofalseGive the page each list item came from.
target_pagesstringNoevery pageOne page or a range, such as 5 or 3-12, within the document.
system_promptstringNoInstructions about the whole document, up to 4,000 characters.
curl https://api.pageindex.ai/extract \
  -H "api_key: $PAGEINDEX_API_KEY" \
  -F "doc_id=pi-cm3k9x2qv0001l50856dh4a2f" \
  -F 'configuration={"data_schema": {"type": "object", "properties": {"total": {"type": "number", "description": "Invoice total, in euros"}}}, "tier": "standard"}'
{
  "id": "ext_9a1c3e5f7b2d4f6a8c0e1b3d",
  "status": "pending",
  "doc_id": "pi-cm3k9x2qv0001l50856dh4a2f",
  "configuration": {
    "data_schema": {
      "type": "object",
      "properties": {
        "total": { "type": "number", "description": "Invoice total, in euros" }
      }
    },
    "tier": "standard",
    "cite_sources": false
  },
  "created_at": "2026-11-18T09:40:05",
  "updated_at": "2026-11-18T09:40:05"
}

With file, the job's doc_id is null, and nothing is charged as a document.

The price is $0.03 a page with standard, and $0.05 a page with pro, for the pages extracted. It is held when the job starts and charged when it completes. A job that fails or is cancelled is not charged for its pages. Each page search the job makes is charged on its own, as a page search, even if the job then fails. See Pricing.

StatusWhen
400A file that is not a readable PDF, or is encrypted.
402insufficient_credits: your balance does not cover the job.
403The document is not yours, or a key below WRITE.
404The document does not exist.
409The document's pages are not ready yet.
422Both doc_id and file, or neither. A configuration that is not valid. A schema that is too large, is not valid JSON Schema, or does not have an object or array at its top. A target_pages that is not valid.
503The job could not be queued. Try again.

SDK: Python PageExtractClient.extract().

Get an extraction

GET /extract/{job_id} · READ key

Returns a job, with its result once it is completed.

NameTypeRequiredDefaultDescription
job_idstring (path)YesThe job's id.
curl https://api.pageindex.ai/extract/ext_9a1c3e5f7b2d4f6a8c0e1b3d \
  -H "api_key: $PAGEINDEX_API_KEY"
{
  "id": "ext_9a1c3e5f7b2d4f6a8c0e1b3d",
  "status": "completed",
  "doc_id": "pi-cm3k9x2qv0001l50856dh4a2f",
  "configuration": {
    "data_schema": { "type": "object", "properties": { "segments": { "type": "array" } } },
    "tier": "standard",
    "cite_sources": true
  },
  "created_at": "2026-11-18T09:40:05",
  "updated_at": "2026-11-18T09:41:12",
  "extract_result": {
    "segments": [
      { "name": "Cloud", "revenue": 4200 },
      { "name": "Devices", "revenue": 1850 }
    ]
  },
  "extract_metadata": {
    "field_metadata": {
      "/segments/0": { "page": 34 },
      "/segments/1": { "page": 34 }
    }
  },
  "usage": { "pages": 64, "credits": 192 }
}
statusWhat it means
pendingWaiting to start.
runningReading the document.
completedDone. extract_result and usage are there.
failedIt could not be finished. error_message says why.
cancelledYou stopped it.
  • extract_metadata is there only with cite_sources. Each key is a list item's path in the result, as a JSON Pointer.
  • usage.credits is what the job cost, in credits. One credit is one US cent.
StatusWhen
404The job does not exist, or is not yours.

SDK: Python get_extract(), or wait_extract() to wait for it.

List extractions

GET /extracts · READ key

Lists your jobs, newest first, without their results.

NameTypeRequiredDefaultDescription
limitinteger (query)No20Jobs to return, 1 to 100.
afterstring (query)NoThe next of the page before, for the page after it.
curl "https://api.pageindex.ai/extracts?limit=2" \
  -H "api_key: $PAGEINDEX_API_KEY"
{
  "jobs": [
    {
      "id": "ext_9a1c3e5f7b2d4f6a8c0e1b3d",
      "status": "completed",
      "doc_id": "pi-cm3k9x2qv0001l50856dh4a2f",
      "configuration": { "data_schema": { "type": "object" }, "tier": "standard", "cite_sources": true },
      "created_at": "2026-11-18T09:40:05",
      "updated_at": "2026-11-18T09:41:12",
      "usage": { "pages": 64, "credits": 192 }
    },
    {
      "id": "ext_3b5d7f9a1c2e4f6a8b0d2c4e",
      "status": "running",
      "doc_id": "pi-cm3ka3c9s0004l508t2v4x6z8",
      "configuration": { "data_schema": { "type": "array" }, "tier": "pro", "cite_sources": false },
      "created_at": "2026-11-18T09:38:51",
      "updated_at": "2026-11-18T09:38:53"
    }
  ],
  "next": "ext_3b5d7f9a1c2e4f6a8b0d2c4e"
}

next is set whenever a page is full, so the page after it may be empty. It is null on a page that is not full.

SDK: Python list_extracts().

Cancel an extraction

POST /extract/{job_id}/cancel · WRITE key

Stops a job that is pending or running.

NameTypeRequiredDefaultDescription
job_idstring (path)YesThe job's id.
curl -X POST https://api.pageindex.ai/extract/ext_3b5d7f9a1c2e4f6a8b0d2c4e/cancel \
  -H "api_key: $PAGEINDEX_API_KEY"

The answer is the job, with "status": "cancelled".

StatusWhen
404The job does not exist, or is not yours.
409The job has ended already.

SDK: Python cancel_extract().

Delete an extraction

DELETE /extract/{job_id} · WRITE key

Deletes a job and its result.

NameTypeRequiredDefaultDescription
job_idstring (path)YesThe job's id.
curl -X DELETE https://api.pageindex.ai/extract/ext_9a1c3e5f7b2d4f6a8c0e1b3d \
  -H "api_key: $PAGEINDEX_API_KEY"
{ "id": "ext_9a1c3e5f7b2d4f6a8c0e1b3d", "deleted": true }
StatusWhen
404The job does not exist, or is not yours.

SDK: Python delete_extract().