> ## Documentation Index > Fetch the complete documentation index at: https://docs.extend.ai/llms.txt > Use this file to discover all available pages before exploring further. > > ## API version > The current API version is `2026-02-09`, served at the site root (no version prefix in URLs). > If this page URL contains `/2025-04-21/` or `/2024-12-23/`, you are reading an older API version. > Prefer the current docs at https://docs.extend.ai/llms.txt unless the user explicitly needs that older version. > Do not treat older-version pages as the source of truth for new integrations. # Extraction Response Format > Understand the Extract response: top-level fields, the value and metadata objects, confidence scores, and source citations with page references and bounding boxes. Extract turns documents into structured, machine-readable data you can trust and trace. Every run gives you the values your schema defined, plus per-field confidence scores and citations that point back to the exact spot on the page. This page explains every field in the response. --- ## Response structure A completed extract run looks like this (truncated to a few fields for brevity). The extracted data lives in `output.value`; the per-field details live in `output.metadata`, keyed by the same field paths. ```json { "object": "extract_run", "id": "exr_3f1j6I1gsw5k96xFiCnkM", "file": { "object": "file", "id": "file_GzKUy0VDhHscv7tweODYb", "name": "bill_of_lading.pdf" }, "status": "PROCESSED", "output": { "value": { "load_number": "ABC-10025521", "shipper_name": "Acme Manufacturing Co.", "ship_date": "2026-03-14" }, "metadata": { "load_number": { "logprobsConfidence": 1, "ocrConfidence": 0.99, "citations": [ { "fileId": "file_GzKUy0VDhHscv7tweODYb", "page": { "number": 1, "width": 612, "height": 792 }, "polygon": [ { "x": 56.8, "y": 35.2 }, { "x": 162.2, "y": 35.2 }, { "x": 162.2, "y": 48.1 }, { "x": 56.8, "y": 48.1 } ], "referenceText": "Load No. ABC-10025521" } ] }, "shipper_name": { "logprobsConfidence": 0.98, "ocrConfidence": 0.97, "citations": [ /* ... */ ] }, "ship_date": { "logprobsConfidence": 0.99, "ocrConfidence": 0.98, "citations": [ /* ... */ ] } } }, "reviewed": false, "edited": false, "usage": { "credits": 2 } } ``` ### Top-level fields | Field | Type | Description | | ---------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `object` | string | Always `"extract_run"`. | | `id` | string | Unique identifier for the run (e.g. `exr_...`). Use it to [fetch results](/api-reference/endpoints/extract/get-extract-run) later. | | `file` | object | The processed file (`id`, `name`). Reusable as input to other endpoints. | | `status` | string | `PENDING`, `PROCESSING`, `PROCESSED`, or `FAILED`. | | `output` | object \| null | The extracted data. Present when `status` is `PROCESSED`. Contains `value` and `metadata`. | | `reviewed` / `edited` | boolean | Whether a human reviewed the run, and whether they changed any values. When `reviewed` is `true`, `initialOutput` and `reviewedOutput` are also populated. | | `config` | object | The full configuration used, including defaults that were applied. | | `parseRunId` | string \| null | The ID of the parse run used for this extract run. | | `usage` | object | Credits consumed (`usage.credits`). | | `dashboardUrl` | string | Link to view the run in the Extend dashboard. | | `failureReason` / `failureMessage` | string \| null | Machine-readable code and human-readable message. Present when `status` is `FAILED`. | --- ## Output: value and metadata `output` has two halves that share the same field paths: * **`value`** — the data extracted from the document, conforming to the JSON Schema you defined in the [config](/extraction/schema). * **`metadata`** — per-field details: confidence scores, citations, and insights. The `metadata` object uses keys that mirror the structure of `value` with a path-like notation, so you can pinpoint the details for any field — including those nested in objects or arrays. If `value.line_items[0].description` exists, its metadata lives under the key `"line_items[0].description"` in `metadata`. ```json { "value": { "invoice_number": "INV-123", "line_items": [{ "description": "Item A", "quantity": 2 }] }, "metadata": { "invoice_number": { "logprobsConfidence": 1, "ocrConfidence": 0.99 }, "line_items": { "logprobsConfidence": 0.98, "ocrConfidence": 0.98 }, "line_items[0]": { "logprobsConfidence": 0.98, "ocrConfidence": 0.98 }, "line_items[0].description": { "logprobsConfidence": 1, "ocrConfidence": 0.95 }, "line_items[0].quantity": { "logprobsConfidence": 1, "ocrConfidence": 0.98 } } } ``` ### Metadata entry fields Each entry in `metadata` describes one field path: | Field | Type | Description | | -------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `logprobsConfidence` | number \| null | Model confidence from token probabilities (0–1). Being phased out — `null` on `extraction_light` and on `extraction_performance` `4.6.0`+. See [Confidence scores](#confidence-scores). | | `ocrConfidence` | number \| null | OCR confidence for the underlying text (0–1). Only included when [`citationsEnabled`](/extraction/configuration#advancedoptionscitationsenabled) is `true`; otherwise absent, or `null` when word-level confidence is unavailable. | | `reviewAgentScore` | integer \| null | A 1–5 score from the [Review Agent](/extraction/review-agent) when it is enabled (5 = high confidence, 1 = significant problems). `null` otherwise. | | `citations` | array | Bounding-box references back to the source document. Present when `citationsEnabled` is on. See [Citations](#citations). | | `insights` | array | Model reasoning and review notes. See [Insights](#insights). | ### Accessing fields and metadata Read your data straight off `value`, and look up the matching `metadata` entry by its path-like key. #### Python ```python value = output["value"] metadata = output["metadata"] # Root-level field and its metadata invoice_number = value.get("invoice_number") invoice_number_meta = metadata.get("invoice_number") # Loop through an array and read per-item metadata for i, line_item in enumerate(value.get("line_items", [])): item_meta = metadata.get(f"line_items[{i}]") description_meta = metadata.get(f"line_items[{i}].description") ``` #### TypeScript ```typescript const { value, metadata } = output; // Root-level field and its metadata const invoiceNumber = value.invoice_number; const invoiceNumberMeta = metadata.invoice_number; // Loop through an array and read per-item metadata value.line_items.forEach((lineItem, i) => { const itemMeta = metadata[`line_items[${i}]`]; const descriptionMeta = metadata[`line_items[${i}].description`]; }); ``` #### Java ```java Map value = output.getValue(); var metadata = output.getMetadata(); // Root-level field and its metadata Object invoiceNumber = value.get("invoice_number"); var invoiceNumberMeta = metadata.get("invoice_number"); // Loop through an array and read per-item metadata List lineItems = (List) value.get("line_items"); for (int i = 0; i < lineItems.size(); i++) { var itemMeta = metadata.get("line_items[" + i + "]"); var descriptionMeta = metadata.get("line_items[" + i + "].description"); } ``` #### Go ```go value := output.Value metadata := output.Metadata // Root-level field and its metadata invoiceNumber := value["invoice_number"] invoiceNumberMeta := metadata["invoice_number"] // Loop through an array and read per-item metadata lineItems, _ := value["line_items"].([]any) for i := range lineItems { itemMeta := metadata[fmt.Sprintf("line_items[%d]", i)] descriptionMeta := metadata[fmt.Sprintf("line_items[%d].description", i)] _, _ = itemMeta, descriptionMeta } ``` --- ## Confidence scores A confidence score tells you how confident the model is in an extracted value, as a number between 0 and 1 (closer to 1 is more confident). Each metadata entry can carry two scores: | Field | Description | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `logprobsConfidence` | From the language model, based on token probabilities during generation. | | `ocrConfidence` | From the OCR system, about how reliably the underlying text was recognized. Only included when [`citationsEnabled`](/extraction/configuration#advancedoptionscitationsenabled) is `true`. | Each metadata entry holds the scores for its field, keyed by the field's path: ```json { "metadata": { "invoice_number": { "ocrConfidence": 0.99, "logprobsConfidence": 1.0 } } } ``` For arrays, confidence is reported at every level — the array as a whole (`line_items`), each item (`line_items[0]`), and each property within an item (`line_items[0].description`): ```json { "metadata": { "line_items": { "ocrConfidence": 0.98 }, "line_items[0]": { "ocrConfidence": 0.98 }, "line_items[0].description": { "ocrConfidence": 0.95 }, "line_items[1].description": { "ocrConfidence": 0.92 } } } ``` `logprobsConfidence` is being phased out: `extraction_light` has never returned it, and `extraction_performance` version `4.6.0` and later return `null`. Prefer `ocrConfidence` and the [Review Agent](/extraction/review-agent) scoring system. See [Extraction Performance versions](/model-versioning/extraction/extraction-performance). For routing on confidence in [Workflows](/workflows/overview), threshold and review patterns, and accuracy best practices, see [Confidence Scores](/extraction/confidence-scores). --- ## Citations Source citations give you a page reference, a bounding box, and the source text for each extracted field, so you can highlight exactly where a value came from on the original document. Enable them by setting `citationsEnabled: true` in the extraction config. Generating robust citations uses an additional citation-focused model, which adds a moderate increase in latency. Citations are returned inside each field's `metadata` entry: ```json { "value": { "invoice_number": "US-001" }, "metadata": { "invoice_number": { "citations": [ { "fileId": "file_GzKUy0VDhHscv7tweODYb", "page": { "number": 1, "width": 612, "height": 792 }, "polygon": [ { "x": 612, "y": 231 }, { "x": 706, "y": 231 }, { "x": 706, "y": 259 }, { "x": 612, "y": 259 } ], "referenceText": "US-001" } ], "ocrConfidence": 0.988, "logprobsConfidence": 1 } } } ``` ### Citation fields | Field | Type | Description | | ---------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `fileId` | string | ID of the file the citation was found in. On single-file runs it equals the run's `file.id`; on [multifile runs](/extraction/multifile) it identifies which entry in the run's `files` array the citation refers to. | | `page.number` | number | Page the citation was found on (starts at 1). Page numbers are relative to the cited file (`fileId`), not the corpus. | | `page.width` / `page.height` | number | Page dimensions, in points. Use them to normalize `polygon` coordinates. | | `polygon` | array | Outline of the cited region as `{ x, y }` points. Present only when `citationsEnabled` is on. | | `referenceText` | string \| null | The source text that backs the value. Present only when `citationsEnabled` is on. | ### Coordinate system `polygon` points share the page's coordinate space, with the origin at the **top-left** of the page: `x` increases to the right and `y` increases downward, both measured in points. Each citation reports the page's own dimensions at `page.width` and `page.height`, so you can divide by them to express any position as a fraction of the page. ``` (0, 0) (pageWidth, 0) ┌────────────────────────────────────────────┐ │ (left, top) │ │ ●───────────────────────┐ │ │ │ │ │ │ │ citation │ │ │ │ │ │ │ └───────────────────────● │ │ (right, bottom) │ │ │ └────────────────────────────────────────────┘ (0, pageHeight) (pageWidth, pageHeight) ``` ### Rendering citations in PDF viewers Reduce the `polygon` to its bounding extent and normalize against the page dimensions to produce a highlight in your viewer's coordinate system. Here's an example that produces a percentage-based highlight area for `react-pdf-viewer` or a similar library: #### Python ```python def citation_to_highlight(citation): polygon = citation.get("polygon") if not polygon: raise ValueError("Citation does not have a polygon") page = citation["page"] xs = [p["x"] for p in polygon] ys = [p["y"] for p in polygon] left, right = min(xs), max(xs) top, bottom = min(ys), max(ys) return { # Normalized to percentages of the page "left": (left / page["width"]) * 100, "top": (top / page["height"]) * 100, "width": ((right - left) / page["width"]) * 100, "height": ((bottom - top) / page["height"]) * 100, "page_index": page["number"] - 1, # 1-based to 0-based } ``` #### TypeScript ```typescript import { Extend } from "extend-ai"; function citationToHighlight(citation: Extend.Citation) { if (!citation.polygon) throw new Error("Citation does not have a polygon"); const { width, height, number } = citation.page; const box = citation.polygon.reduce( (acc, p) => ({ left: Math.min(acc.left, p.x), top: Math.min(acc.top, p.y), right: Math.max(acc.right, p.x), bottom: Math.max(acc.bottom, p.y), }), { left: Infinity, top: Infinity, right: 0, bottom: 0 } ); return { // Normalized to percentages of the page left: (box.left / width) * 100, top: (box.top / height) * 100, width: ((box.right - box.left) / width) * 100, height: ((box.bottom - box.top) / height) * 100, pageIndex: number - 1, // 1-based to 0-based }; } ``` #### Java ```java Map citationToHighlight(Citation citation) { if (citation.getPolygon().isEmpty()) { throw new IllegalArgumentException("Citation does not have a polygon"); } double left = Double.MAX_VALUE, top = Double.MAX_VALUE, right = 0, bottom = 0; for (Point p : citation.getPolygon().get()) { left = Math.min(left, p.getX()); top = Math.min(top, p.getY()); right = Math.max(right, p.getX()); bottom = Math.max(bottom, p.getY()); } double width = citation.getPage().getWidth().get(); double height = citation.getPage().getHeight().get(); Map highlight = new HashMap<>(); // Normalized to percentages of the page highlight.put("left", (left / width) * 100); highlight.put("top", (top / height) * 100); highlight.put("width", ((right - left) / width) * 100); highlight.put("height", ((bottom - top) / height) * 100); highlight.put("pageIndex", citation.getPage().getNumber() - 1); // 1-based to 0-based return highlight; } ``` #### Go ```go type Highlight struct { Left, Top, Width, Height float64 PageIndex int } func citationToHighlight(citation *extend.Citation) (Highlight, error) { if len(citation.Polygon) == 0 { return Highlight{}, fmt.Errorf("citation does not have a polygon") } left, top := math.Inf(1), math.Inf(1) right, bottom := 0.0, 0.0 for _, p := range citation.Polygon { left, top = math.Min(left, p.X), math.Min(top, p.Y) right, bottom = math.Max(right, p.X), math.Max(bottom, p.Y) } page := citation.Page return Highlight{ // Normalized to percentages of the page Left: (left / page.Width) * 100, Top: (top / page.Height) * 100, Width: ((right - left) / page.Width) * 100, Height: ((bottom - top) / page.Height) * 100, PageIndex: page.Number - 1, // 1-based to 0-based }, nil } ``` --- ## Insights The `insights` array is a shared channel that explains the model's decisions. It carries `reasoning` entries when reasoning insights are enabled, and the [Review Agent](/extraction/review-agent) can add notes when it is enabled. ```json { "metadata": { "amount": { "insights": [ { "type": "reasoning", "content": "The total is shown as '$15,735.10' in the table summary and bottom right. The '$' and US address indicate USD." } ] } } } ``` Each insight has a `type` and a `content` string. --- ## Output Examples ### Basic fields ```json { "value": { "amount": { "amount": 15735.1, "iso_4217_currency_code": "USD" }, "invoice_number": "36995" }, "metadata": { "amount": { "insights": [ { "type": "reasoning", "content": "The total amount is shown as '$15,735.1' in the table summary and the bottom right. The '$' and the US address indicate USD." } ], "citations": [ { "fileId": "file_xK9mLPqRtN3vS8wF5hB2cQ", "page": { "number": 1, "width": 612, "height": 792 }, "polygon": [ { "x": 430.164, "y": 722.772 }, { "x": 467.272, "y": 722.829 }, { "x": 467.258, "y": 731.635 }, { "x": 430.149, "y": 731.577 } ], "referenceText": "TOTAL $15,735.1" } ], "ocrConfidence": 0.992, "logprobsConfidence": 1 }, "invoice_number": { "citations": [ { "fileId": "file_xK9mLPqRtN3vS8wF5hB2cQ", "page": { "number": 1, "width": 612, "height": 792 }, "polygon": [ { "x": 459.8, "y": 88.4 }, { "x": 545.2, "y": 88.4 }, { "x": 545.2, "y": 101.6 }, { "x": 459.8, "y": 101.6 } ], "referenceText": "Invoice #36995" } ], "ocrConfidence": 0.986, "logprobsConfidence": 1 } } } ``` ### Nested structures ```json { "value": { "line_items": [ { "item": "Widget A", "quantity": 5, "price": { "amount": 10.0, "iso_4217_currency_code": "USD" } }, { "item": "Widget B", "quantity": 2, "price": { "amount": 15.0, "iso_4217_currency_code": "USD" } } ], "signature_block": { "printed_name": "John Smith", "is_signed": true } }, "metadata": { "line_items": { "logprobsConfidence": 0.96 }, "line_items[0]": { "logprobsConfidence": 0.96, "citations": [ { "fileId": "file_xK9mLPqRtN3vS8wF5hB2cQ", "page": { "number": 1, "width": 612, "height": 792 }, "polygon": [ { "x": 61.2, "y": 318.7 }, { "x": 550.8, "y": 318.7 }, { "x": 550.8, "y": 336.1 }, { "x": 61.2, "y": 336.1 } ], "referenceText": "Widget A 5 $10.00" } ] }, "line_items[0].item": { "logprobsConfidence": 0.99 }, "line_items[0].price.amount": { "logprobsConfidence": 0.98 }, "signature_block": { "logprobsConfidence": 0.99, "citations": [ { "fileId": "file_xK9mLPqRtN3vS8wF5hB2cQ", "page": { "number": 1, "width": 612, "height": 792 }, "polygon": [ { "x": 72.4, "y": 690.5 }, { "x": 198.6, "y": 690.5 }, { "x": 198.6, "y": 712.9 }, { "x": 72.4, "y": 712.9 } ], "referenceText": "John Smith" } ] } } } ```