Skip to main content
GET
/
v1
/
workflows
/
runs
/
{run_id}
/
steps
/
{block_id}
from retab import Retab

client = Retab()

step = client.workflows.runs.steps.get("run_abc123xyz", "extract-block-1")

print(step.status)
print(step.extracted_data)

# Jump to the underlying typed resource produced by this step:
if step.artifact:
    extraction = client.extractions.get(step.artifact.id)
    print(extraction.choices)

# Or inspect raw handle payloads:
if step.handle_outputs:
    payload = step.handle_outputs["output-json-0"]
    print(payload.type)
    print(payload.data)
{
  "block_id": "extract-block-1",
  "block_type": "extract",
  "block_label": "Extract Data",
  "status": "completed",
  "error": null,
  "artifact": {
    "operation": "extraction",
    "id": "ext_abc123"
  },
  "handle_outputs": {
    "output-json-0": {
      "type": "json",
      "data": {
        "invoice_number": "INV-2024-001",
        "total_amount": 1234.56,
        "vendor_name": "Acme Corp"
      }
    }
  },
  "handle_inputs": {
    "input-file-0": {
      "type": "file",
      "document": {
        "id": "file_123",
        "filename": "invoice.pdf",
        "mime_type": "application/pdf"
      }
    }
  }
}
Get step status and handle data for a specific step in a workflow run. Use this to inspect the normalized inputs and outputs for a particular block after or during execution.
from retab import Retab

client = Retab()

step = client.workflows.runs.steps.get("run_abc123xyz", "extract-block-1")

print(step.status)
print(step.extracted_data)

# Jump to the underlying typed resource produced by this step:
if step.artifact:
    extraction = client.extractions.get(step.artifact.id)
    print(extraction.choices)

# Or inspect raw handle payloads:
if step.handle_outputs:
    payload = step.handle_outputs["output-json-0"]
    print(payload.type)
    print(payload.data)
{
  "block_id": "extract-block-1",
  "block_type": "extract",
  "block_label": "Extract Data",
  "status": "completed",
  "error": null,
  "artifact": {
    "operation": "extraction",
    "id": "ext_abc123"
  },
  "handle_outputs": {
    "output-json-0": {
      "type": "json",
      "data": {
        "invoice_number": "INV-2024-001",
        "total_amount": 1234.56,
        "vendor_name": "Acme Corp"
      }
    }
  },
  "handle_inputs": {
    "input-file-0": {
      "type": "file",
      "document": {
        "id": "file_123",
        "filename": "invoice.pdf",
        "mime_type": "application/pdf"
      }
    }
  }
}

Authorizations

Api-Key
string
header
required

Path Parameters

run_id
string
required
block_id
string
required

Query Parameters

access_token
string | null

Response

Successful Response

Public response containing step status and handle data.

block_id
string
required

ID of the block

block_type
string
required

Type of the block

block_label
string
required

Label of the block

status
string
required

Step status

error
string | null

Error message if the step failed

artifact
StepArtifactRef · object

Canonical persisted resource produced by this step, if any

handle_outputs
Handle Outputs · object

Handle outputs keyed by handle ID

handle_inputs
Handle Inputs · object

Handle inputs keyed by handle ID (what this block received)