> This page is for version v2025-04-21.
> For other versions, use one of these documentation indexes:
> - v2026-02-09 (default): https://docs.extend.ai/2026-02-09/llms.txt
> - v2025-04-21: https://docs.extend.ai/2025-04-21/llms.txt
> - v2024-12-23: https://docs.extend.ai/2024-12-23/llms.txt

> ## 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.

# Extractor output type

> Understanding the output type for extractors.

Extraction outputs follow a standardized format that you'll encounter when working with evaluation sets, webhooks, and API responses.

## Extraction output type

The output structure for JSON Schema processors is composed of two properties: `value` and `metadata`.

The `value` object is the actual data extracted from the document which conforms to the JSON Schema defined in the processor config.

The `metadata` object holds details like confidence scores and citations for the extracted data. It uses keys that represent the path to the corresponding data within the value object. Crucially, the keys in the `metadata` object mirror the structure of the `value` object using a path-like notation (e.g., `line_items[0].description`), allowing you to precisely pinpoint metadata for any specific field, including those nested within objects or arrays. For instance, if your data has value.line_items\[0].name, the metadata specifically for that name field will be found using the key 'line_items\[0].name' within the metadata object.

> **Note**
>
> The `extraction_light` base processor does not support logprobs. For JSON Schema processors, this means metadata entries will have `logprobsConfidence` set to `null`.

### Type definition

**`TypeScript Types`**

```typescript TypeScript Types
type ExtractionOutput = {
  value: ExtractionValue;
  metadata: ExtractionMetadata;
};

type ExtractionValue = Record<string, any>; // Conforms to the schema defined in the processor config
type ExtractionMetadata = {
  [key: string]: ExtractionMetadataEntry | undefined;
};

type ExtractionMetadataEntry {
  ocrConfidence?: number | null;
  logprobsConfidence: number | null;
  reviewAgentScore?: number | null;
  citations?: Citation[];
  insights?: OutputInsight[];
}

type Citation = {
  page?: number;
  referenceText?: string | null;
  polygon?: Point[];
  cellRange?: string;
};

type Point = {
  x: number;
  y: number;
};

type OutputInsight =
  | { type: "reasoning"; content: string }
  | { type: "issue"; content: string }
  | { type: "review_summary"; content: string };
```

> **Note**
>
> The `insights` array is a shared channel. It can include `reasoning` (when model reasoning insights are enabled)
> and `issue`/`review_summary` (when the Review Agent is enabled). See [Review Agent](/2025-04-21/product/extraction/review-agent).

### Accessing Metadata

To access the metadata for a specific field, especially nested ones like items in an array, you use a path-like key string. For example, to get the metadata for the `description` of the first item in a `line_items` array, the key would be `line_items[0].description`.

Here are examples in Python and TypeScript:

**`TypeScript Example`**

```typescript TypeScript Example
const output = {
  value: {
    invoice_number: "INV-123",
    line_items: [
      { description: "Item A", quantity: 2, price: 10.0 },
      { description: "Item B", quantity: 1, price: 25.5 },
    ],
  },
  metadata: {
    invoice_number: {
      logprobsConfidence: 1,
      ocrConfidence: 0.99,
      citations: [
        {
          referenceText: "Invoice #: INV-123",
          page: 1,
          polygon: [
            { x: 296.73359999999997, y: 40.888799999999996 },
            { x: 386.4168, y: 40.464000000000006 },
            { x: 386.4744, y: 52.1712 },
            { x: 296.7912, y: 52.596000000000004 },
          ],
        },
      ],
    },
    line_items: {
      logprobsConfidence: 0.98,
      ocrConfidence: 0.98,
    },
    "line_items[0]": {
      logprobsConfidence: 0.98,
      ocrConfidence: 0.98,
      citations: [{ page: 1 }],
    },
    "line_items[0].description": { logprobsConfidence: 1, ocrConfidence: 0.95 },
    "line_items[0].quantity": { logprobsConfidence: 1, ocrConfidence: 0.98 },
    "line_items[0].price": { logprobsConfidence: 1, ocrConfidence: 0.98 },
    "line_items[1].description": { logprobsConfidence: 1, ocrConfidence: 0.96 },
    // Other metadata entries...
  },
};

// Traversing the output object and accessing metadata
const invoiceNumber = output.value.invoice_number;
const invoiceNumberMetadata = output.metadata.invoice_number;

// Access metadata for the line_items array itself
const lineItemsMetadata = output.metadata.line_items;

// Loop through line items array
for (let i = 0; i < output.value.line_items.length; i++) {
  const lineItemPath = `line_items[${i}]`;

  // Access the line item object and its metadata
  const lineItem = output.value.line_items[i];
  const lineItemMetadata = output.metadata[lineItemPath];

  // Access properties within the line item and their metadata
  const lineItemDescription = lineItem.description;
  const lineItemDescriptionMetadata =
    output.metadata[`${lineItemPath}.description`];
  const lineItemQuantity = lineItem.quantity;
  const lineItemQuantityMetadata = output.metadata[`${lineItemPath}.quantity`];
  const lineItemPrice = lineItem.price;
  const lineItemPriceMetadata = output.metadata[`${lineItemPath}.price`];
}
```

**`Python Example`**

```python Python Example
output = {
  "value": {
    "invoice_number": "INV-123",
    "line_items": [
      { "description": "Item A", "quantity": 2, "price": 10.0 },
      { "description": "Item B", "quantity": 1, "price": 25.5 },
    ],
  },
  "metadata": {
    "invoice_number": {
      "logprobsConfidence": 1,
      "ocrConfidence": 0.99,
      "citations": [{ "referenceText": "Invoice #: INV-123" }],
    },
    "line_items": {
      "logprobsConfidence": 0.98, # Metadata for the array itself
      "ocrConfidence": 0.98,
    },
    "line_items[0]": {
      "logprobsConfidence": 0.98, # Metadata for the first object in the array
      "ocrConfidence": 0.98,
      "citations": [{ "page": 1 }],
    },
    "line_items[0].description": { "logprobsConfidence": 1, "ocrConfidence": 0.95 },
    "line_items[0].quantity": { "logprobsConfidence": 1, "ocrConfidence": 0.98 },
    "line_items[0].price": { "logprobsConfidence": 1, "ocrConfidence": 0.98 },
    "line_items[1].description": { "logprobsConfidence": 1, "ocrConfidence": 0.96 },
    # Other metadata entries...
  },
}

# Traversing the output object and accessing metadata
# Use .get() for safe access in case keys are missing

# Access root level value and its metadata
invoice_number = output.get("value", {}).get("invoice_number")
invoice_number_metadata = output.get("metadata", {}).get("invoice_number")

# Access metadata for the line_items array itself
line_items_metadata = output.get("metadata", {}).get("line_items")

# Loop through line items array
line_items = output.get("value", {}).get("line_items", [])
for i, line_item in enumerate(line_items):
    line_item_path = f"line_items[{i}]"

    # Access the line item object and its metadata
    item_metadata = output.get("metadata", {}).get(line_item_path)

    # Access properties within the line item and their metadata
    description = line_item.get("description")
    description_metadata = output.get("metadata", {}).get(f"{line_item_path}.description")
    quantity = line_item.get("quantity")
    quantity_metadata = output.get("metadata", {}).get(f"{line_item_path}.quantity")
    price = line_item.get("price")
    price_metadata = output.get("metadata", {}).get(f"{line_item_path}.price")
```

### Examples

#### Basic Field Types

```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 both the table summary and the bottom right of the document. The currency symbol '$' and the US address indicate the currency is USD. The value is numeric and matches the required format."
        }
      ],
      "citations": [
        {
          "page": 1,
          "polygon": [
            {
              "x": 430.164,
              "y": 722.772
            },
            {
              "x": 467.27279999999996,
              "y": 722.8296
            },
            {
              "x": 467.2584,
              "y": 731.6351999999999
            },
            {
              "x": 430.1496,
              "y": 731.5776
            }
          ],
          "referenceText": "TOTAL  $15,735.1"
        }
      ],
      "ocrConfidence": 0.992,
      "logprobsConfidence": 1
    },
    "invoice_number": {
      "insights": [
        {
          "type": "reasoning",
          "content": "The invoice number is clearly labeled as 'Invoice #36995' at the top right of the document, making it straightforward to extract."
        }
      ],
      "citations": [
        {
          "page": 1,
          "polygon": [
            {
              "x": 296.73359999999997,
              "y": 40.888799999999996
            },
            {
              "x": 386.4168,
              "y": 40.464000000000006
            },
            {
              "x": 386.4744,
              "y": 52.1712
            },
            {
              "x": 296.7912,
              "y": 52.596000000000004
            }
          ],
          "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",
      "signature_date": "2024-03-15",
      "is_signed": true,
      "title_or_role": "Purchasing Manager"
    }
  },
  "metadata": {
    "line_items": {
      "logprobsConfidence": 0.96 // Minimum confidence for the values in the array
    },
    "line_items[0]": {
      "logprobsConfidence": 0.96, // Minimum confidence for the values in the item
      "page": 1
    },
    "line_items[0].item": {
      "logprobsConfidence": 0.99
    },
    "line_items[0].quantity": {
      "logprobsConfidence": 1.0
    },
    "line_items[0].price.amount": {
      "logprobsConfidence": 0.98
    },
    "line_items[0].price.iso_4217_currency_code": {
      "logprobsConfidence": 0.96
    },
    "line_items[1]": {
      "logprobsConfidence": 0.96,
      "page": 1
    },
    "line_items[1].item": {
      "logprobsConfidence": 0.98
    },
    "line_items[1].quantity": {
      "logprobsConfidence": 1.0
    },
    "line_items[1].price.amount": {
      "logprobsConfidence": 0.97
    },
    "line_items[1].price.iso_4217_currency_code": {
      "logprobsConfidence": 0.96
    },
    "signature_block": {
      "logprobsConfidence": 0.99, // Confidence for the overall object
      "citations": [
        {
          "page": 1,
          "referenceText": "John Smith",
          "polygon": [
            /* points omitted */
          ]
        }
      ]
    }
  }
}
```

## Shared Types

Certain types are shared across different processor outputs. These provide additional context and information about the processor's decisions.

### Type Definition

```typescript
type Insight = {
  type: "reasoning" | "issue" | "review_summary";
  content: string;
};
```

### Example

```json
{
  "insights": [
    {
      "type": "reasoning",
      "content": "This was classified as an invoice because it contains standard invoice elements including an invoice number, billing details, and itemized charges."
    }
  ]
}
```

Insights can appear in both Extraction and Classification outputs to provide transparency into the model's decision-making process. They are particularly useful when debugging or validating processor results.