Skip to main content

Workflow state reader

Workflow state reader helpers inspect the public WorkflowState returned by workflow.getWorkflowRunById(). Use them to recover suspended runs, inspect resume labels, and read step payloads or outputs without parsing raw workflow snapshots.

Usage example
Direct link to Usage example

src/mastra/workflows/recover-run.ts
import { createWorkflowStateReader } from '@mastra/core/workflows'

const state = await workflow.getWorkflowRunById('run-123')

if (state) {
  const reader = createWorkflowStateReader(state)
  const suspendedStep = reader.getSuspendedStep()
  const labels = reader.getResumeLabels()

  console.log(reader.getStatus())
  console.log(reader.getStepOutput('extract-data'))
  console.log(suspendedStep?.path)
  console.log(labels.approve)
}

Functions
Direct link to Functions

createWorkflowStateReader(state)
Direct link to createworkflowstatereaderstate

Creates a reader object with methods bound to one WorkflowState.

const reader = createWorkflowStateReader(state)
const suspendedStep = reader.getSuspendedStep()

getWorkflowStepOutput(state, stepId)
Direct link to getworkflowstepoutputstate-stepid

Returns the output for a step ID, including nested workflow dot paths such as parent.child. For foreach steps, returns one entry per iteration; suspended iterations can have undefined output entries.

const output = getWorkflowStepOutput(state, 'extract-data')

getWorkflowStepPayload(state, stepId)
Direct link to getworkflowsteppayloadstate-stepid

Returns the payload that was passed to a step. For foreach steps, returns one entry per iteration.

const payload = getWorkflowStepPayload(state, 'extract-data')

getWorkflowSuspendedStep(state)
Direct link to getworkflowsuspendedstepstate

Returns the first suspended step from the workflow state. When multiple steps are suspended, ordering follows the order stored in suspendedPaths.

const suspendedStep = getWorkflowSuspendedStep(state)

getWorkflowSuspendedSteps(state)
Direct link to getworkflowsuspendedstepsstate

Returns all suspended steps from the workflow state. Each result includes the top-level step ID, resume path, execution path, suspend payload, suspend output, and matching resume labels.

const suspendedSteps = getWorkflowSuspendedSteps(state)

getWorkflowResumeLabel(state, label)
Direct link to getworkflowresumelabelstate-label

Returns a resume label by name.

const label = getWorkflowResumeLabel(state, 'approve')

getWorkflowResumeLabels(state)
Direct link to getworkflowresumelabelsstate

Returns all resume labels from the workflow state.

const labels = getWorkflowResumeLabels(state)

Reader methods
Direct link to Reader methods

createWorkflowStateReader(state) returns the following methods:

getStatus:

() => WorkflowRunStatus
Returns the workflow run status.

getResult:

() => WorkflowState["result"]
Returns the terminal workflow result when it exists.

getError:

() => WorkflowState["error"]
Returns the terminal workflow error when it exists.

getStepOutput:

(stepId: string) => any | Array<any | undefined> | undefined
Returns the output for a step ID or nested workflow dot path.

getStepPayload:

(stepId: string) => any | Array<any | undefined> | undefined
Returns the payload for a step ID or nested workflow dot path.

getSuspendedStep:

() => { stepId: string; path: string[]; executionPath?: number[]; step?: NonNullable<WorkflowState["steps"]>[string]; payload?: any; suspendPayload?: any; suspendOutput?: any; resumeLabels: Record<string, { stepId: string; foreachIndex?: number }> } | undefined
Returns the first suspended step.

getSuspendedSteps:

() => Array<{ stepId: string; path: string[]; executionPath?: number[]; step?: NonNullable<WorkflowState["steps"]>[string]; payload?: any; suspendPayload?: any; suspendOutput?: any; resumeLabels: Record<string, { stepId: string; foreachIndex?: number }> }>
Returns all suspended steps.

getResumeLabel:

(label: string) => { stepId: string; foreachIndex?: number } | undefined
Returns a resume label by name.

getResumeLabels:

() => Record<string, { stepId: string; foreachIndex?: number }>
Returns all resume labels.

Notes
Direct link to Notes

requestContext and tracingContext are only returned by workflow.getWorkflowRunById() when explicitly requested with fields.

On this page