Skip to main content
POST
/
v1
/
extractions
/
stream
from retab import MIMEData, Retab

client = Retab()

document = MIMEData(
    filename="Invoice.pdf",
    url="https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf",
)
schema = {
    "type": "object",
    "properties": {
        "invoice_number": {"type": "string"},
        "total": {"type": "number"},
    },
    "required": ["invoice_number", "total"],
}

result = client.extractions.create_stream(
    document=document,
    json_schema=schema,
    model="retab-small",
)
print(result)

{
  "id": "extr_01G34H8J2K",
  "file": {
    "id": "file_6dd6eb00688ad8d1",
    "filename": "Invoice.pdf",
    "mime_type": "application/pdf"
  },
  "model": "retab-small",
  "output": {
    "invoice_number": "INV-2024-0042",
    "total": 1234.56
  },
  "created_at": "2024-03-15T10:30:00Z"
}
Run a structured extraction on a document and stream partial results as they are produced, instead of waiting for the full Extraction to be persisted. The request body is identical to POST /v1/extractions; the response is a stream of application/stream+json chunks, each carrying the latest partial output as the model fills the schema. 
from retab import MIMEData, Retab

client = Retab()

document = MIMEData(
    filename="Invoice.pdf",
    url="https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf",
)
schema = {
    "type": "object",
    "properties": {
        "invoice_number": {"type": "string"},
        "total": {"type": "number"},
    },
    "required": ["invoice_number", "total"],
}

result = client.extractions.create_stream(
    document=document,
    json_schema=schema,
    model="retab-small",
)
print(result)

{
  "id": "extr_01G34H8J2K",
  "file": {
    "id": "file_6dd6eb00688ad8d1",
    "filename": "Invoice.pdf",
    "mime_type": "application/pdf"
  },
  "model": "retab-small",
  "output": {
    "invoice_number": "INV-2024-0042",
    "total": 1234.56
  },
  "created_at": "2024-03-15T10:30:00Z"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request to run a structured extraction on a single document.

Extends the base extraction request with the document to process (either inline content or a reference to a previously uploaded file) and a stream flag that controls whether results are returned incrementally.

​
document
MIMEData · object
required

A file represented by its filename and a base64 data url.

​
json_schema
Json Schema · object
required

JSON schema describing the structured output

​
model
string
default:retab-small

The model to use for the extraction

​
image_resolution_dpi
integer
default:192

Resolution of the image sent to the LLM

​
instructions
string | null

Free-form instructions appended to the system prompt to steer the extraction.

​
n_consensus
integer
default:1

Number of consensus extraction runs to perform. Uses deterministic single-pass when set to 1.

​
metadata
Metadata · object

User-defined metadata to associate with this extraction

​
additional_messages
Additional Messages · object[] | null

Additional chat messages forwarded to the extraction model.

​
bust_cache
boolean
default:false

If true, skip the LLM cache and force a fresh completion

​
stream
boolean
default:false
​
background
boolean
default:false

If true, run asynchronously: returns immediately with status 'queued' and an empty output. Poll GET /v1//{id} until status is terminal. Mutually exclusive with stream.

​
chunking_keys
Chunking Keys · object

Response

Streaming extraction chunks