# 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

```typescript
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

### `createWorkflowStateReader(state)`

Creates a reader object with methods bound to one `WorkflowState`.

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

### `getWorkflowStepOutput(state, 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.

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

### `getWorkflowStepPayload(state, stepId)`

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

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

### `getWorkflowSuspendedStep(state)`

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

```typescript
const suspendedStep = getWorkflowSuspendedStep(state)
```

### `getWorkflowSuspendedSteps(state)`

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.

```typescript
const suspendedSteps = getWorkflowSuspendedSteps(state)
```

### `getWorkflowResumeLabel(state, label)`

Returns a resume label by name.

```typescript
const label = getWorkflowResumeLabel(state, 'approve')
```

### `getWorkflowResumeLabels(state)`

Returns all resume labels from the workflow state.

```typescript
const labels = getWorkflowResumeLabels(state)
```

## 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

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

## Related

- [Suspend & resume](https://mastra.ai/docs/workflows/suspend-and-resume)
- [Snapshots](https://mastra.ai/docs/workflows/snapshots)
- [Workflow class](https://mastra.ai/reference/workflows/workflow)