world.runs

List, filter, and inspect workflow runs with cursor pagination and status filtering.

The world.runs interface provides direct access to workflow run data. Use it to list runs with pagination, filter by status, and inspect individual run metadata.

Import

import { getWorld } from "workflow/runtime";

const world = getWorld();
const runs = world.runs;

Methods

Parameter	Type	Description
`runId`	`string`	The workflow run ID
`params.resolveData`	`'all' \| 'none'`	Whether to hydrate input/output data. Default: `'all'`

list()

List workflow runs with cursor pagination.

const result = await world.runs.list({ 
  pagination: { cursor },
});

Parameters:

Parameter	Type	Description
`params.pagination.cursor`	`string`	Cursor for the next page
`params.resolveData`	`'all' \| 'none'`	Whether to hydrate input/output data

Returns: { data: WorkflowRun[], cursor?: string }

cancel()

Cancel a running workflow. This is a convenience method that creates a run_cancelled event.

const run = await world.runs.cancel(runId);

Parameters:

Parameter	Type	Description
`runId`	`string`	The workflow run ID to cancel

Returns: WorkflowRun

Cancellation works by creating an event with eventType: 'run_cancelled'. See world.events for the full event creation API.

Types

WorkflowRun

Field	Type	Description
`runId`	`string`	Unique run identifier
`status`	`string`	Run status: `'running'`, `'completed'`, `'failed'`, `'cancelled'`
`workflowName`	`string`	Machine-readable workflow identifier
`input`	`any`	Workflow input data (when `resolveData: 'all'`)
`output`	`any`	Workflow output data (when `resolveData: 'all'`)
`error`	`any`	Error data if the run failed
`startedAt`	`string`	ISO timestamp when the run started
`completedAt`	`string \| null`	ISO timestamp when the run completed
`specVersion`	`number`	Workflow spec version

The workflowName field contains a machine-readable identifier like workflow//./src/workflows/order//processOrder. Use parseWorkflowName() from workflow/observability to extract a display-friendly name.

Examples

List Workflow Runs with Cursor Pagination

// app/api/workflow-runs/route.ts
import { getWorld } from "workflow/runtime";

export async function GET(req: Request) {
  const url = new URL(req.url);
  const cursor = url.searchParams.get("cursor") ?? undefined;

  const world = getWorld(); 
  const runs = await world.runs.list({ 
    pagination: { cursor }, 
  }); 

  return Response.json(runs);
}

Get a Single Run with Full Data

Use resolveData: 'all' (the default) to fetch the complete run including input and output:

// app/api/workflow-runs/[runId]/route.ts
import { getWorld } from "workflow/runtime";

export async function GET(req: Request) {
  const url = new URL(req.url);
  const runId = url.searchParams.get("runId");

  if (!runId) {
    return Response.json({ error: "runId required" }, { status: 400 });
  }

  const world = getWorld();
  const run = await world.runs.get(runId, { 
    resolveData: "all", 
  }); 

  return Response.json({
    runId: run.runId,
    status: run.status,
    input: run.input,
    output: run.output,
    startedAt: run.startedAt,
    completedAt: run.completedAt,
  });
}

Get Run without Data for Lightweight Status Checks

Use resolveData: 'none' when you only need status metadata:

import { getWorld } from "workflow/runtime";

const world = getWorld();
const run = await world.runs.get(runId, { 
  resolveData: "none", // Skip input/output for performance
}); 

console.log(run.status); // 'running' | 'completed' | 'failed' | 'cancelled'

Parse Workflow Display Name from Machine-Readable ID

import { getWorld } from "workflow/runtime";
import { parseWorkflowName } from "workflow/observability"; 

const world = getWorld();
const runs = await world.runs.list({});

for (const run of runs.data) {
  const parsed = parseWorkflowName(run.workflowName); 
  console.log(parsed?.shortName); // e.g., "processOrder"
  console.log(parsed?.moduleSpecifier); // e.g., "./src/workflows/order"
}

Cancel a Running Workflow

// app/api/workflow-runs/cancel/route.ts
import { getWorld } from "workflow/runtime";

export async function POST(req: Request) {
  const { runId } = await req.json();

  if (!runId) {
    return Response.json({ error: "runId required" }, { status: 400 });
  }

  const world = getWorld();
  const run = await world.runs.cancel(runId); 

  return Response.json({ status: run.status });
}

world.steps — Inspect individual step execution within a run
world.events — Query the event log for a run
getRun() — Higher-level API for working with individual runs
Observability Utilities — Parse workflow names and hydrate data