A run is a sequence of steps, and there are two things you usually want from one: what each step did and where the time went. The Run Timeline puts both behind a tab toggle over the same run.
- Steps — a vertical list (block icon, label, status, duration) beside a detail panel showing the selected step's inspector. Click a step to inspect it; the panel swaps in whatever view that block provides.
- Timing — a Step Waterfall of the same steps, so you can see the run's latency profile at a glance.
This is the connective view for the rest of the Workflows section: the sample run
above wires the API Call,
Function and If / Else
inspectors into individual steps, and includes a failed step so you can see the
error state. Each step carries its own inspector node, so any block-type view
composes here.
Usage
Pass a run with an ordered list of steps. Each step supplies its presentation
(block type, label, status, duration) and an optional inspector to render when
selected.
import { RunTimeline } from "@/registry/new-york-v4/blocks/run-timeline-block"
import { ApiCallInspector } from "@/registry/new-york-v4/blocks/api-call-block"
export function Example() {
return (
<div className="h-[560px] overflow-hidden rounded-xl border">
<RunTimeline
run={{
defaultStepId: "fetch",
steps: [
{
id: "upload",
blockType: "start_document",
label: "Upload invoice",
status: "completed",
durationMs: 8,
detail: "invoice_8842.pdf",
},
{
id: "fetch",
blockType: "api_call",
label: "Extract fields",
status: "completed",
durationMs: 1842,
inspector: <ApiCallInspector call={/* ... */} />,
},
],
}}
/>
</div>
)
}Block types
The blockType drives the step's icon and color. Recognized values mirror
Retab's workflow blocks — start_document, start_json, parse, edit,
extract, split, classifier, merge_dicts, conditional, api_call,
function, while_loop, for_each. Any other value falls back to a generic
icon and label.
API
WorkflowRun
| Field | Type | Description |
|---|---|---|
steps | RunStep[] | The steps, in execution order. |
defaultStepId | string | Step selected on mount; falls back to the first step. |
RunStep
| Field | Type | Description |
|---|---|---|
id | string | Stable identifier used for selection. |
blockType | string | Drives the icon and color (see Block types). |
label | string | The step's name. |
status | "completed" | "running" | "error" | "skipped" | "pending" | "awaiting_review" | Drives the status icon and color. |
durationMs | number | null | Execution time, shown on the row and in the header (auto ms/s), and the bar length in the Timing tab. |
startOffsetMs | number | null | Offset from the start of the run, used to place the bar in the Timing tab. Defaults to a sequential layout (each step starts where the previous ended). |
detail | string | Secondary line — error message, skip reason, filename, model, etc. |
inspector | React.ReactNode | Rendered in the detail panel when the step is selected. Falls back to a generic status view. |
Components
| Export | Props | Description |
|---|---|---|
RunTimeline | { run: WorkflowRun } | The tabbed run view — Steps (list + inspector) and Timing (waterfall). |
RunTimelineBlock | { run?: WorkflowRun } | The run view preloaded with a sample run; pass run to override. |