> ## Documentation Index
> Fetch the complete documentation index at: https://docs.retab.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List Steps
> List steps with status and artifact summaries.
Sorted by `started_at` ascending with `step_id` as the tiebreaker
(the same compound key the underlying index uses). Pass `after` for
the next page, `before` for the previous page — mutually exclusive.
`run_id` is optional; when omitted the list is scoped to the caller's
organization.
Retrieve persisted workflow step documents. Pass `run_id` when you want the complete set of steps for one run, or combine filters such as `block_id`, `step_id`, `block_type`, and `status` to inspect a narrower set.
Returns the canonical `{ "data": [...], "list_metadata": { "before": null, "after": null } }` pagination envelope shared with all Retab list endpoints. Cursor pagination is not yet implemented for this endpoint — `list_metadata` is always `{ before: null, after: null }`. When `run_id` is omitted, the response is organization-scoped and bounded by `limit` with a default of 200 rows.
Steps include an `artifact` ref when the block produced a persisted record.
Use [List Artifacts](/api-reference/workflows/artifacts/list) with `step_id` to
dereference one ref, or with `run_id` to fetch all artifact records for the run.
```python Python theme={null}
from retab import Retab
client = Retab()
steps = client.workflows.steps.list("run_abc123xyz")
for step in steps.data:
print(step.block_id, step.lifecycle.status, step.artifact)
```
```typescript TypeScript theme={null}
import { Retab } from "@retab/node";
const client = new Retab({ apiKey: process.env.RETAB_API_KEY });
const steps = await client.workflows.steps.list({ runId: "run_abc123xyz" });
for (const step of steps.data) {
console.log(step.blockId, step.lifecycle.status, step.artifact);
}
```
```go Go theme={null}
package main
import (
"context"
"fmt"
"log"
retab "github.com/retab-dev/retab/clients/go"
)
func ptr[T any](v T) *T { return &v }
func main() {
ctx := context.Background()
client, err := retab.NewClient("")
if err != nil {
log.Fatal(err)
}
steps, err := client.Workflows.Steps.List(ctx, &retab.WorkflowStepsListParams{
RunID: ptr("run_abc123xyz"),
})
if err != nil {
log.Fatal(err)
}
for _, step := range steps.Data {
fmt.Println(step.BlockID, step.Lifecycle.Status())
}
}
```
```ruby Ruby theme={null}
require 'retab'
client = Retab::Client.new(api_key: ENV['RETAB_API_KEY'])
steps = client.workflows.steps.list(run_id: 'run_abc123xyz')
steps.data.each do |step|
puts "#{step.block_id} #{step.lifecycle.status} #{step.artifact}"
end
```
```rust Rust theme={null}
use retab::resources::workflow_steps::ListParams;
use retab::Retab;
#[tokio::main]
async fn main() -> Result<(), Box> {
let client = Retab::new(std::env::var("RETAB_API_KEY")?);
let steps = client
.workflows().steps()
.list(ListParams {
run_id: Some("run_abc123xyz".into()),
..Default::default()
})
.await?;
for step in &steps.data {
println!("{} {:?} {:?}", step.block_id, step.lifecycle, step.artifact);
}
Ok(())
}
```
```php PHP theme={null}
workflows()->steps()->list();
print_r($result);
```
```csharp C# theme={null}
using Retab;
using RetabClient = Retab.Retab;
var apiKey = Environment.GetEnvironmentVariable("RETAB_API_KEY")!;
var client = new RetabClient(apiKey);
var result = await client.Workflows.Steps.ListAsync(new WorkflowStepsListOptions());
Console.WriteLine(result);
```
```java Java theme={null}
import com.retab.RetabClient;
public final class Example {
public static void main(String[] args) throws Exception {
RetabClient client = new RetabClient(System.getenv("RETAB_API_KEY"));
var result = client.workflows().steps().list("run_abc123", "block_abc123", "step_abc123", null, null, null, null, 10L);
System.out.println(result);
}
}
```
```curl cURL theme={null}
curl -X 'GET' \
'https://api.retab.com/v1/workflows/steps?run_id=run_abc123xyz' \
-H 'Authorization: Bearer '
```
```json 200 theme={null}
{
"data": [
{
"run_id": "run_abc123xyz",
"block_id": "extract-block-1",
"step_id": "extract-block-1",
"block_type": "extract",
"block_label": "Extract Invoice",
"lifecycle": { "status": "completed" },
"artifact": { "operation": "extraction", "id": "ext_abc123" },
"started_at": "2026-03-12T09:00:00Z",
"completed_at": "2026-03-12T09:00:03Z",
"handle_outputs": {
"output-json-0": {
"type": "json",
"data": {
"invoice_number": "INV-2024-001",
"total_amount": 1234.56
}
}
},
"handle_inputs": {
"input-file-0": {
"type": "file",
"document": {
"id": "file_123",
"filename": "invoice.pdf",
"mime_type": "application/pdf"
}
}
},
"created_at": "2026-03-12T09:00:00Z"
},
{
"run_id": "run_abc123xyz",
"block_id": "split-block-1",
"step_id": "split-block-1",
"block_type": "split",
"block_label": "Split Documents",
"lifecycle": { "status": "completed" },
"artifact": { "operation": "split", "id": "spl_def456" },
"started_at": "2026-03-12T09:00:03Z",
"completed_at": "2026-03-12T09:00:04Z",
"handle_outputs": {
"output-file-invoice": {
"type": "file",
"document": {
"id": "file_456",
"filename": "invoice_page_1.pdf",
"mime_type": "application/pdf"
}
}
},
"handle_inputs": {
"input-file-0": {
"type": "file",
"document": {
"id": "file_123",
"filename": "invoice.pdf",
"mime_type": "application/pdf"
}
}
},
"created_at": "2026-03-12T09:00:03Z"
}
],
"list_metadata": {
"before": null,
"after": null
}
}
```
```json 404 theme={null}
{
"detail": "Workflow run not found"
}
```
## OpenAPI
````yaml GET /v1/workflows/steps
openapi: 3.1.0
info:
title: FastAPI
version: 0.1.0
servers:
- url: https://api.retab.com
security: []
paths:
/v1/workflows/steps:
get:
tags:
- Workflows
- Workflow Run Steps
summary: List Workflow Run Steps
description: |-
List steps with status and artifact summaries.
Sorted by `started_at` ascending with `step_id` as the tiebreaker
(the same compound key the underlying index uses). Pass `after` for
the next page, `before` for the previous page — mutually exclusive.
`run_id` is optional; when omitted the list is scoped to the caller's
organization.
operationId: list_workflow_run_steps
parameters:
- in: query
name: run_id
schema:
anyOf:
- type: string
- type: 'null'
description: Optional workflow run ID filter.
title: Run Id
required: false
description: Optional workflow run ID filter.
- in: query
name: block_id
schema:
anyOf:
- type: string
- type: 'null'
description: Optional logical block ID filter.
title: Block Id
required: false
description: Optional logical block ID filter.
- in: query
name: step_id
schema:
anyOf:
- type: string
- type: 'null'
description: Optional step ID filter.
title: Step Id
required: false
description: Optional step ID filter.
- in: query
name: block_type
schema:
anyOf:
- items:
type: string
type: array
- type: 'null'
description: >-
Optional block type filter. Repeat the query parameter for
multiple values.
title: Block Type
required: false
description: >-
Optional block type filter. Repeat the query parameter for multiple
values.
- in: query
name: status
schema:
anyOf:
- items:
type: string
type: array
- type: 'null'
description: >-
Optional step lifecycle status filter. Repeat the query parameter
for multiple values.
title: Status
required: false
description: >-
Optional step lifecycle status filter. Repeat the query parameter
for multiple values.
- in: query
name: before
schema:
anyOf:
- type: string
- type: 'null'
description: >-
Step id cursor: return the page before this id (mutually exclusive
with `after`).
title: Before
required: false
description: >-
Step id cursor: return the page before this id (mutually exclusive
with `after`).
- in: query
name: after
schema:
anyOf:
- type: string
- type: 'null'
description: >-
Step id cursor: return the page after this id (mutually exclusive
with `before`).
title: After
required: false
description: >-
Step id cursor: return the page after this id (mutually exclusive
with `before`).
- in: query
name: limit
schema:
type: integer
maximum: 1000
minimum: 1
description: >-
Maximum number of steps to return per page (1-1000). Each step
hydrates its handle payloads from the artifact store, so raise it
deliberately for larger pages and use cursor pagination for the
rest.
default: 20
title: Limit
required: false
description: >-
Maximum number of steps to return per page (1-1000). Each step
hydrates its handle payloads from the artifact store, so raise it
deliberately for larger pages and use cursor pagination for the
rest.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/WorkflowStepList'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
components:
schemas:
WorkflowStepList:
description: >-
A page of `WorkflowStep` resources. `data` holds the items and
`list_metadata` carries the `before`/`after` cursors; pass `after` to
fetch the next page.
properties:
data:
items:
$ref: '#/components/schemas/WorkflowStep'
type: array
title: Data
list_metadata:
$ref: '#/components/schemas/ListMetadata'
type: object
required:
- data
- list_metadata
title: WorkflowStepList
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
default: []
type: object
title: HTTPValidationError
WorkflowStep:
properties:
block_id:
type: string
title: Block Id
description: Logical ID of the block
step_id:
type: string
title: Step Id
description: >-
Full step ID with iteration context. Assigned ONCE at creation,
never recomputed.
block_type:
type: string
enum:
- start_document
- start_json
- note
- parse
- edit
- extract
- split
- classifier
- conditional
- api_call
- function
- while_loop
- for_each
- merge_dicts
- while_loop_sentinel_start
- while_loop_sentinel_end
- for_each_sentinel_start
- for_each_sentinel_end
title: Block Type
description: Type of the block
block_label:
type: string
title: Block Label
description: Label of the block
lifecycle:
oneOf:
- $ref: '#/components/schemas/PendingStepLifecycle'
- $ref: '#/components/schemas/QueuedStepLifecycle'
- $ref: '#/components/schemas/RunningStepLifecycle'
- $ref: '#/components/schemas/CompletedStepLifecycle'
- $ref: '#/components/schemas/AwaitingReviewStepLifecycle'
- $ref: '#/components/schemas/ErrorStepLifecycle'
- $ref: '#/components/schemas/SkippedStepLifecycle'
- $ref: '#/components/schemas/CancelledStepLifecycle'
title: Lifecycle
description: Current step lifecycle
discriminator:
propertyName: status
mapping:
awaiting_review:
$ref: '#/components/schemas/AwaitingReviewStepLifecycle'
cancelled:
$ref: '#/components/schemas/CancelledStepLifecycle'
completed:
$ref: '#/components/schemas/CompletedStepLifecycle'
error:
$ref: '#/components/schemas/ErrorStepLifecycle'
pending:
$ref: '#/components/schemas/PendingStepLifecycle'
queued:
$ref: '#/components/schemas/QueuedStepLifecycle'
running:
$ref: '#/components/schemas/RunningStepLifecycle'
skipped:
$ref: '#/components/schemas/SkippedStepLifecycle'
started_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Started At
description: When the step started executing
completed_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Completed At
description: When the step finished executing
model:
anyOf:
- type: string
- type: 'null'
title: Model
description: LLM model used by this step, when applicable
loop_containers:
items:
$ref: '#/components/schemas/ContainerContextData'
type: array
title: Loop Containers
description: >-
Container hierarchy from outermost to innermost. Empty when not
inside any container.
default: []
run_id:
type: string
title: Run Id
description: Parent workflow run ID
created_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Created At
description: When the step was created
handle_inputs:
additionalProperties:
$ref: '#/components/schemas/PublicHandlePayload'
type: object
title: Handle Inputs
description: Handle input payloads consumed by this step
default: {}
handle_outputs:
additionalProperties:
$ref: '#/components/schemas/PublicHandlePayload'
type: object
title: Handle Outputs
description: Handle output payloads produced by this step
default: {}
artifact:
anyOf:
- $ref: '#/components/schemas/StepArtifactRef'
- type: 'null'
description: Reference to the result produced by this step, if any.
retry_count:
type: integer
title: Retry Count
description: Number of retry attempts
default: 0
type: object
required:
- block_id
- block_label
- block_type
- lifecycle
- run_id
- step_id
title: WorkflowStep
description: Public step status object.
ListMetadata:
properties:
before:
anyOf:
- type: string
- type: 'null'
title: Before
after:
anyOf:
- type: string
- type: 'null'
title: After
type: object
required:
- after
- before
title: ListMetadata
description: Boundary resource IDs for page navigation.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
default: null
ctx:
type: object
title: Context
default: {}
type: object
required:
- loc
- msg
- type
title: ValidationError
PendingStepLifecycle:
properties:
status:
type: string
const: pending
title: Status
default: pending
type: object
title: PendingStepLifecycle
description: The step has been created but execution has not started.
QueuedStepLifecycle:
properties:
status:
type: string
const: queued
title: Status
default: queued
type: object
title: QueuedStepLifecycle
description: The step is queued for execution.
RunningStepLifecycle:
properties:
status:
type: string
const: running
title: Status
default: running
type: object
title: RunningStepLifecycle
description: The step is currently executing.
CompletedStepLifecycle:
properties:
status:
type: string
const: completed
title: Status
default: completed
type: object
title: CompletedStepLifecycle
description: The step finished successfully.
AwaitingReviewStepLifecycle:
properties:
status:
type: string
const: awaiting_review
title: Status
default: awaiting_review
type: object
title: AwaitingReviewStepLifecycle
description: The step is paused on a human review decision.
ErrorStepLifecycle:
properties:
status:
type: string
const: error
title: Status
default: error
message:
type: string
title: Message
description: Human-readable error message
stage:
anyOf:
- type: string
enum:
- input_collection
- registry_lookup
- document_fetch
- execution
- output_storage
- routing
- history_payload
- type: 'null'
title: Stage
category:
anyOf:
- type: string
enum:
- transient
- permanent
- quota
- type: 'null'
title: Category
details:
anyOf:
- $ref: '#/components/schemas/ErrorDetails'
- type: 'null'
type: object
required:
- message
title: ErrorStepLifecycle
description: The step failed. Error details are bundled into lifecycle.
SkippedStepLifecycle:
properties:
status:
type: string
const: skipped
title: Status
default: skipped
reason:
type: string
title: Reason
description: Reason the step was skipped
type: object
required:
- reason
title: SkippedStepLifecycle
description: The step was skipped.
CancelledStepLifecycle:
properties:
status:
type: string
const: cancelled
title: Status
default: cancelled
reason:
type: string
title: Reason
description: Reason the step was cancelled
type: object
required:
- reason
title: CancelledStepLifecycle
description: The step was cancelled.
ContainerContextData:
properties:
container_id:
type: string
title: Container Id
description: Container ID (e.g., 'while_loop-abc')
iteration:
type: integer
title: Iteration
description: Iteration index (0-based)
is_parallel:
type: boolean
title: Is Parallel
description: Whether this container represents a parallel item
default: false
parallel_item_index:
anyOf:
- type: integer
- type: 'null'
title: Parallel Item Index
description: Parallel item index if is_parallel
type: object
required:
- container_id
- iteration
title: ContainerContextData
description: Structured context for a single container in the hierarchy.
PublicHandlePayload:
properties:
type:
type: string
enum:
- file
- json
title: Type
description: Type of payload
document:
anyOf:
- $ref: '#/components/schemas/FileRef'
- type: 'null'
description: 'For file handles: document reference'
data:
title: Data
description: 'For JSON handles: structured data'
default: null
type: object
required:
- type
title: PublicHandlePayload
description: Public handle payload exposed by workflow step APIs.
StepArtifactRef:
properties:
operation:
type: string
enum:
- extraction
- split
- classification
- parse
- edit
- partition
- conditional_evaluation
- review_trigger_evaluation
- while_loop_termination
- api_call_invocation
- function_invocation
title: Operation
description: The kind of resource this artifact references
id:
type: string
title: Id
description: Resource identifier
type: object
required:
- id
- operation
title: StepArtifactRef
description: >-
A resource produced by a workflow step.
An `(operation, id)` reference. The artifact itself carries no payload —
consumers dispatch on `operation` and fetch the referenced record by
`id`.
ErrorDetails:
properties:
message:
anyOf:
- type: string
- type: 'null'
title: Message
description: >-
Human-readable error message. Free-text; the structured fields below
are the machine-readable counterpart.
stack_trace:
anyOf:
- type: string
- type: 'null'
title: Stack Trace
description: Full stack trace
block_id:
anyOf:
- type: string
- type: 'null'
title: Block Id
description: ID of the block that failed
block_name:
anyOf:
- type: string
- type: 'null'
title: Block Name
description: Name/label of the block that failed
error_code:
anyOf:
- type: string
- type: 'null'
title: Error Code
description: Error code if available
context:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Context
description: Additional context about the error
type: object
title: ErrorDetails
description: |-
Detailed error information for debugging.
Captures stack traces and context about where and why an error occurred.
FileRef:
properties:
id:
type: string
title: Id
description: ID of the file
filename:
type: string
title: Filename
description: Filename of the file
mime_type:
type: string
title: Mime Type
description: MIME type of the file
type: object
required:
- filename
- id
- mime_type
title: FileRef
description: Public/shared file reference used across SDK and customer-facing APIs.
securitySchemes:
HTTPBearer:
type: http
scheme: bearer
````