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.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
configuration | string (form) | Yes | A JSON object. | |
doc_id | string (form) | Yes, or file | A completed document of yours. | |
file | file (form) | Yes, or doc_id | A PDF, read for this job only and not stored as a document. |
configuration holds:
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
data_schema | object | Yes | A JSON Schema (draft 2020-12) for the result. Its top is an object or an array. Up to 1,000,000 bytes. | |
tier | string | No | standard | standard, or pro for the hardest documents. |
cite_sources | boolean | No | false | Give the page each list item came from. |
target_pages | string | No | every page | One page or a range, such as 5 or 3-12, within the document. |
system_prompt | string | No | Instructions 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.
| Status | When |
|---|---|
| 400 | A file that is not a readable PDF, or is encrypted. |
| 402 | insufficient_credits: your balance does not cover the job. |
| 403 | The document is not yours, or a key below WRITE. |
| 404 | The document does not exist. |
| 409 | The document's pages are not ready yet. |
| 422 | Both 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. |
| 503 | The 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.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
job_id | string (path) | Yes | The 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 }
}
status | What it means |
|---|---|
pending | Waiting to start. |
running | Reading the document. |
completed | Done. extract_result and usage are there. |
failed | It could not be finished. error_message says why. |
cancelled | You stopped it. |
extract_metadatais there only withcite_sources. Each key is a list item's path in the result, as a JSON Pointer.usage.creditsis what the job cost, in credits. One credit is one US cent.
| Status | When |
|---|---|
| 404 | The 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.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
limit | integer (query) | No | 20 | Jobs to return, 1 to 100. |
after | string (query) | No | The 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.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
job_id | string (path) | Yes | The 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".
| Status | When |
|---|---|
| 404 | The job does not exist, or is not yours. |
| 409 | The job has ended already. |
SDK: Python cancel_extract().
Delete an extraction
DELETE /extract/{job_id} · WRITE key
Deletes a job and its result.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
job_id | string (path) | Yes | The job's id. |
curl -X DELETE https://api.pageindex.ai/extract/ext_9a1c3e5f7b2d4f6a8c0e1b3d \
-H "api_key: $PAGEINDEX_API_KEY"
{ "id": "ext_9a1c3e5f7b2d4f6a8c0e1b3d", "deleted": true }
| Status | When |
|---|---|
| 404 | The job does not exist, or is not yours. |
SDK: Python delete_extract().