Get Partition

Retrieve a partition.

Fetches a single partition by its partition_id within the authenticated environment and returns the full Partition including its output chunks. Responds with 404 if no partition with that id exists.

GET /v1/partitions/{partition_id}

Python

from retab import Retab

client = Retab()

partition = client.partitions.get("part_01G34H8J2K")
for chunk in partition.output:
    print(chunk.key, chunk.pages)

200

{
  "id": "part_01G34H8J2K",
  "file": {
    "id": "file_6dd6eb00688ad8d1",
    "filename": "invoice_batch.pdf",
    "mime_type": "application/pdf"
  },
  "model": "retab-small",
  "key": "invoice_number",
  "instructions": "Return one chunk per invoice number and keep all pages for the same invoice together.",
  "n_consensus": 3,
  "allow_overlap": true,
  "output": [
    { "key": "INV-001", "pages": [1, 2] },
    { "key": "INV-002", "pages": [3, 4] }
  ],
  "consensus": {
    "likelihoods": [
      { "key": 0.99, "pages": [0.99, 0.98] },
      { "key": 0.96, "pages": [0.95, 0.95] }
    ],
    "choices": [
      [
        { "key": "INV-001", "pages": [1, 2] },
        { "key": "INV-002", "pages": [3, 4] }
      ]
    ]
  },
  "usage": {
    "credits": 3.0
  },
  "created_at": "2024-03-15T10:30:00Z"
}

Retrieve a single persisted partition by ID.

Python

from retab import Retab

client = Retab()

partition = client.partitions.get("part_01G34H8J2K")
for chunk in partition.output:
    print(chunk.key, chunk.pages)

200

{
  "id": "part_01G34H8J2K",
  "file": {
    "id": "file_6dd6eb00688ad8d1",
    "filename": "invoice_batch.pdf",
    "mime_type": "application/pdf"
  },
  "model": "retab-small",
  "key": "invoice_number",
  "instructions": "Return one chunk per invoice number and keep all pages for the same invoice together.",
  "n_consensus": 3,
  "allow_overlap": true,
  "output": [
    { "key": "INV-001", "pages": [1, 2] },
    { "key": "INV-002", "pages": [3, 4] }
  ],
  "consensus": {
    "likelihoods": [
      { "key": 0.99, "pages": [0.99, 0.98] },
      { "key": 0.96, "pages": [0.95, 0.95] }
    ],
    "choices": [
      [
        { "key": "INV-001", "pages": [1, 2] },
        { "key": "INV-002", "pages": [3, 4] }
      ]
    ]
  },
  "usage": {
    "credits": 3.0
  },
  "created_at": "2024-03-15T10:30:00Z"
}

Authorizations

Api-Key · string · header · required

Path Parameters

partition_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 partition result: a document segmented into chunks along the requested key.

id · string · required

Unique identifier of the partition

file · FileRef · object · required

Information about the partitioned file

Show child attributes

model · string · required

Model used for the partition operation

key · string · required

Partition key used for the run

instructions · string | null

Free-form instructions supplied with the partition request

n_consensus · integer · default: 1

Number of consensus votes used

allow_overlap · boolean · default: true

Whether pages were allowed to appear in more than one partition chunk

output · PartitionChunk · object[]

The list of partition chunks with their assigned pages. Empty [] until status == 'completed'.

Show child attributes

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 · PartitionConsensus · object

Consensus metadata for multi-vote partition runs

Show child attributes

usage · RetabUsage · object

Usage information for the partition operation

Show child attributes

created_at · string<date-time> | null