from retab import Retab
client = Retab()
steps = client.workflows.steps.list(run_id="run_abc123xyz", include_download_urls=True)
for step in steps.data:
print(step.block_id, step.lifecycle.status, step.artifact)
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",
includeDownloadUrls: true,
});
for (const step of steps.data) {
console.log(step.blockId, step.lifecycle.status, step.artifact);
}
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"),
IncludeDownloadURLs: ptr(true),
})
if err != nil {
log.Fatal(err)
}
for _, step := range steps.Data {
fmt.Println(step.BlockID, step.Lifecycle.Status())
}
}
require 'retab'
client = Retab::Client.new(api_key: ENV['RETAB_API_KEY'])
steps = client.workflows.steps.list(run_id: 'run_abc123xyz', include_download_urls: true)
steps.data.each do |step|
puts "#{step.block_id} #{step.lifecycle.status} #{step.artifact}"
end
use retab::resources::workflow_steps::ListParams;
use retab::Retab;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = Retab::new(std::env::var("RETAB_API_KEY")?);
let steps = client
.workflows().steps()
.list(ListParams {
run_id: Some("run_abc123xyz".into()),
include_download_urls: Some(true),
..Default::default()
})
.await?;
for step in &steps.data {
println!("{} {:?} {:?}", step.block_id, step.lifecycle, step.artifact);
}
Ok(())
}
<?php
require 'vendor/autoload.php';
use Retab\Client;
$client = new Client(apiKey: getenv('RETAB_API_KEY'));
$result = $client->workflows()->steps()->list(
runId: 'run_abc123xyz',
includeDownloadUrls: true,
);
print_r($result);
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
{
RunId = "run_abc123xyz",
IncludeDownloadUrls = true,
});
Console.WriteLine(result);
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", null, "block_abc123", "step_abc123", null, null, null, null, 10L, true);
System.out.println(result);
}
}
curl -X 'GET' \
'https://api.retab.com/v1/workflows/steps?run_id=run_abc123xyz&include_download_urls=true' \
-H 'Authorization: Bearer <your-api-key>'
{
"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"
},
"download_url": "https://storage.googleapis.com/retab-documents/org_abc/file/file_456.pdf?X-Goog-Expires=1800&X-Goog-Signature=...",
"expires_at": "2026-03-12T09:30:04Z"
}
},
"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
}
}
{
"detail": "Workflow run not found"
}
Steps
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.
GET
/
v1
/
workflows
/
steps
from retab import Retab
client = Retab()
steps = client.workflows.steps.list(run_id="run_abc123xyz", include_download_urls=True)
for step in steps.data:
print(step.block_id, step.lifecycle.status, step.artifact)
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",
includeDownloadUrls: true,
});
for (const step of steps.data) {
console.log(step.blockId, step.lifecycle.status, step.artifact);
}
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"),
IncludeDownloadURLs: ptr(true),
})
if err != nil {
log.Fatal(err)
}
for _, step := range steps.Data {
fmt.Println(step.BlockID, step.Lifecycle.Status())
}
}
require 'retab'
client = Retab::Client.new(api_key: ENV['RETAB_API_KEY'])
steps = client.workflows.steps.list(run_id: 'run_abc123xyz', include_download_urls: true)
steps.data.each do |step|
puts "#{step.block_id} #{step.lifecycle.status} #{step.artifact}"
end
use retab::resources::workflow_steps::ListParams;
use retab::Retab;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = Retab::new(std::env::var("RETAB_API_KEY")?);
let steps = client
.workflows().steps()
.list(ListParams {
run_id: Some("run_abc123xyz".into()),
include_download_urls: Some(true),
..Default::default()
})
.await?;
for step in &steps.data {
println!("{} {:?} {:?}", step.block_id, step.lifecycle, step.artifact);
}
Ok(())
}
<?php
require 'vendor/autoload.php';
use Retab\Client;
$client = new Client(apiKey: getenv('RETAB_API_KEY'));
$result = $client->workflows()->steps()->list(
runId: 'run_abc123xyz',
includeDownloadUrls: true,
);
print_r($result);
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
{
RunId = "run_abc123xyz",
IncludeDownloadUrls = true,
});
Console.WriteLine(result);
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", null, "block_abc123", "step_abc123", null, null, null, null, 10L, true);
System.out.println(result);
}
}
curl -X 'GET' \
'https://api.retab.com/v1/workflows/steps?run_id=run_abc123xyz&include_download_urls=true' \
-H 'Authorization: Bearer <your-api-key>'
{
"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"
},
"download_url": "https://storage.googleapis.com/retab-documents/org_abc/file/file_456.pdf?X-Goog-Expires=1800&X-Goog-Signature=...",
"expires_at": "2026-03-12T09:30:04Z"
}
},
"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
}
}
{
"detail": "Workflow run not found"
}
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. Steps are sorted by started_at with step_id as the tiebreaker; pass the after cursor from list_metadata for the next page (or before for the previous one). limit defaults to 20 and accepts up to 1000. When run_id is omitted, the response is organization-scoped.
Pass include_download_urls=true to get the documents a run produced: every
file payload in handle_outputs — each PDF a Split block emitted, an Edit
block’s filled document — then also carries a signed download_url (valid 30
minutes) and its expires_at. See
Download the documents a run produced.
Steps include an artifact ref when the block produced a persisted record.
Use List Artifacts with step_id to
dereference one ref, or with run_id to fetch all artifact records for the run.
from retab import Retab
client = Retab()
steps = client.workflows.steps.list(run_id="run_abc123xyz", include_download_urls=True)
for step in steps.data:
print(step.block_id, step.lifecycle.status, step.artifact)
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",
includeDownloadUrls: true,
});
for (const step of steps.data) {
console.log(step.blockId, step.lifecycle.status, step.artifact);
}
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"),
IncludeDownloadURLs: ptr(true),
})
if err != nil {
log.Fatal(err)
}
for _, step := range steps.Data {
fmt.Println(step.BlockID, step.Lifecycle.Status())
}
}
require 'retab'
client = Retab::Client.new(api_key: ENV['RETAB_API_KEY'])
steps = client.workflows.steps.list(run_id: 'run_abc123xyz', include_download_urls: true)
steps.data.each do |step|
puts "#{step.block_id} #{step.lifecycle.status} #{step.artifact}"
end
use retab::resources::workflow_steps::ListParams;
use retab::Retab;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = Retab::new(std::env::var("RETAB_API_KEY")?);
let steps = client
.workflows().steps()
.list(ListParams {
run_id: Some("run_abc123xyz".into()),
include_download_urls: Some(true),
..Default::default()
})
.await?;
for step in &steps.data {
println!("{} {:?} {:?}", step.block_id, step.lifecycle, step.artifact);
}
Ok(())
}
<?php
require 'vendor/autoload.php';
use Retab\Client;
$client = new Client(apiKey: getenv('RETAB_API_KEY'));
$result = $client->workflows()->steps()->list(
runId: 'run_abc123xyz',
includeDownloadUrls: true,
);
print_r($result);
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
{
RunId = "run_abc123xyz",
IncludeDownloadUrls = true,
});
Console.WriteLine(result);
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", null, "block_abc123", "step_abc123", null, null, null, null, 10L, true);
System.out.println(result);
}
}
curl -X 'GET' \
'https://api.retab.com/v1/workflows/steps?run_id=run_abc123xyz&include_download_urls=true' \
-H 'Authorization: Bearer <your-api-key>'
{
"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"
},
"download_url": "https://storage.googleapis.com/retab-documents/org_abc/file/file_456.pdf?X-Goog-Expires=1800&X-Goog-Signature=...",
"expires_at": "2026-03-12T09:30:04Z"
}
},
"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
}
}
{
"detail": "Workflow run not found"
}
Authorizations
Query Parameters
Response
Successful Response
A page of WorkflowStep resources. data holds the items and list_metadata carries the before/after cursors; pass after to fetch the next page.