Get Extraction

Retrieve an extraction.

Returns the extraction identified by extraction_id, including its source file, schema, output, and consensus details. Responds with 404 if no matching extraction exists.

GET /v1/extractions/{extraction_id}

Python

from retab import Retab

client = Retab()

extraction = client.extractions.get("extr_01G34H8J2K")
print(extraction)

200

{
  "id": "extr_01G34H8J2K",
  "created_at": "2024-03-15T10:30:00Z",
  "file": {
    "id": "file_6dd6eb00688ad8d1",
    "filename": "invoice.pdf"
  },
  "output": {
    "invoice_number": "INV-2024-0042",
    "total_amount": 1234.56,
    "vendor_name": "Acme Corp",
    "line_items": [
      {
        "description": "Widget A",
        "quantity": 10,
        "unit_price": 99.99
      }
    ]
  },
  "json_schema": {
    "type": "object",
    "properties": {
      "invoice_number": { "type": "string" },
      "total_amount": { "type": "number" },
      "vendor_name": { "type": "string" },
      "line_items": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "description": { "type": "string" },
            "quantity": { "type": "integer" },
            "unit_price": { "type": "number" }
          }
        }
      }
    }
  },
  "metadata": {
    "batch_id": "batch_2024_03"
  }
}

Python

from retab import Retab

client = Retab()

extraction = client.extractions.get("extr_01G34H8J2K")
print(extraction)

200

{
  "id": "extr_01G34H8J2K",
  "created_at": "2024-03-15T10:30:00Z",
  "file": {
    "id": "file_6dd6eb00688ad8d1",
    "filename": "invoice.pdf"
  },
  "output": {
    "invoice_number": "INV-2024-0042",
    "total_amount": 1234.56,
    "vendor_name": "Acme Corp",
    "line_items": [
      {
        "description": "Widget A",
        "quantity": 10,
        "unit_price": 99.99
      }
    ]
  },
  "json_schema": {
    "type": "object",
    "properties": {
      "invoice_number": { "type": "string" },
      "total_amount": { "type": "number" },
      "vendor_name": { "type": "string" },
      "line_items": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "description": { "type": "string" },
            "quantity": { "type": "integer" },
            "unit_price": { "type": "number" }
          }
        }
      }
    }
  },
  "metadata": {
    "batch_id": "batch_2024_03"
  }
}

Authorizations

Api-Key · string · header · required

Path Parameters

extraction_id · string · required

Query Parameters

include_output · boolean · default: true

When false, returns a cheap status-only projection (no output), served from cache for in-flight background runs.

Response

200

application/json

Successful Response

A stored extraction record from the Retab API.

id · string · required

Unique identifier of the extraction

file · FileRef · object · required

Information about the extracted file

Show child attributes

model · string · required

Model used for the extraction

json_schema · Json Schema · object · required

JSON schema used for the extraction

output · Output · object · required

The extracted structured data

n_consensus · integer · default: 1

Number of consensus votes used

image_resolution_dpi · integer · default: 192

DPI used to render document images

instructions · string | null

Free-form instructions supplied with the extraction request.

status · enum<string> · default: pending

Lifecycle status. The synchronous path returns 'completed'. Background runs progress pending -> queued -> in_progress -> completed | failed | cancelled.

Available options: pending, queued, in_progress, completed, failed, cancelled

error · PrimitiveError · object

Error details when a background run fails; null otherwise. Always present so consumers can read it without an existence check.

Show child attributes

consensus · ExtractionConsensus · object

Consensus metadata for multi-vote extraction runs

Show child attributes

metadata · Metadata · object

Show child attributes

usage · RetabUsage · object

Usage information for the extraction

Show child attributes

created_at · string<date-time> | null