Skip to main content

Run.timeTravel()

The .timeTravel() method re-executes a workflow starting from any specific step, using either stored snapshot data or custom context you provide. This is useful for debugging failed workflows, testing individual steps with different inputs, or recovering from errors without re-running the entire workflow.

Usage exampleDirect link to Usage example

const run = await workflow.createRunAsync();

const result = await run.timeTravel({
  step: "step2",
  inputData: { value: 10 },
});

ParametersDirect link to Parameters

step:

Step<string, any, TInputSchema, any, any, any, TEngineType> | [...Step<string, any, any, any, any, any, TEngineType>[], Step<string, any, TInputSchema, any, any, any, TEngineType>] | string | string[]
The target step to start execution from. It can be a Step instance, array of Steps (for nested workflows), step ID string, or array of step ID strings. Use dot notation or arrays for nested workflow steps (e.g., 'nestedWorkflow.step3' or ['nestedWorkflow', 'step3'])

inputData?:

z.infer<TInputSchema>
Input data for the target step. Must match the step's input schema. If not provided, uses data from the workflow snapshot

resumeData?:

any
Resume data to provide if the workflow was previously suspended

initialState?:

z.infer<TState>
Initial state to set for the workflow run. Used to set workflow-level state before execution

context?:

TimeTravelContext<any, any, any, any>
Execution context containing step results for steps before the target step. Each key is a step ID with a StepResult object containing status, payload, output, startedAt, endedAt, suspendPayload, and resumePayload

nestedStepsContext?:

Record<string, TimeTravelContext<any, any, any, any>>
Context for nested workflow steps. Keyed by nested workflow ID, each containing step results for that nested workflow

requestContext?:

RequestContext
Request Context data to use during time travel execution

writableStream?:

WritableStream<ChunkType>
Optional writable stream for streaming workflow output during time travel

tracingContext?:

TracingContext
Tracing context for creating child spans and adding metadata. Automatically injected when using Mastra's tracing system.

currentSpan?:

Span
Current span for creating child spans and adding metadata. Use this to create custom child spans or update span attributes during execution.

tracingOptions?:

TracingOptions
Options for Tracing configuration.

metadata?:

Record<string, any>
Metadata to add to the root trace span. Useful for adding custom attributes like user IDs, session IDs, or feature flags.

requestContextKeys?:

string[]
Additional RequestContext keys to extract as metadata for this trace. Supports dot notation for nested values (e.g., 'user.id').

traceId?:

string
Trace ID to use for this execution (1-32 hexadecimal characters). If provided, this trace will be part of the specified trace.

parentSpanId?:

string
Parent span ID to use for this execution (1-16 hexadecimal characters). If provided, the root span will be created as a child of this span.

tags?:

string[]
Tags to apply to this trace. String labels for categorizing and filtering traces.

outputOptions?:

OutputOptions
Options for output configuration.

includeState?:

boolean
Whether to include the workflow run state in the result.

includeResumeLabels?:

boolean
Whether to include resume labels in the result.

ReturnsDirect link to Returns

result:

Promise<WorkflowResult<TState, TInput, TOutput, TSteps>>
A promise that resolves to the workflow execution result containing step outputs and status

traceId?:

string
The trace ID associated with this execution when Tracing is enabled. Use this to correlate logs and debug execution flow.

Extended usage examplesDirect link to Extended usage examples

Time travel with custom contextDirect link to Time travel with custom context

const result = await run.timeTravel({
  step: "step2",
  context: {
    step1: {
      status: "success",
      payload: { value: 0 },
      output: { step1Result: 2 },
      startedAt: Date.now(),
      endedAt: Date.now(),
    },
  },
});

Time travel to nested workflow stepDirect link to Time travel to nested workflow step

// Using dot notation
const result = await run.timeTravel({
  step: "nestedWorkflow.step3",
  inputData: { value: 10 },
});

// Using array of step IDs
const result = await run.timeTravel({
  step: ["nestedWorkflow", "step3"],
  inputData: { value: 10 },
});

Time travel with initial stateDirect link to Time travel with initial state

const result = await run.timeTravel({
  step: "step2",
  inputData: { value: 10 },
  initialState: {
    counter: 5,
    metadata: { source: "time-travel" },
  },
});

Time travel with nested workflows contextDirect link to Time travel with nested workflows context

const result = await run.timeTravel({
  step: "nestedWorkflow.step3",
  context: {
    step1: {
      status: "success",
      payload: { value: 0 },
      output: { step1Result: 2 },
      startedAt: Date.now(),
      endedAt: Date.now(),
    },
    nestedWorkflow: {
      status: "running",
      payload: { step1Result: 2 },
      startedAt: Date.now(),
    },
  },
  nestedStepsContext: {
    nestedWorkflow: {
      step2: {
        status: "success",
        payload: { step1Result: 2 },
        output: { step2Result: 3 },
        startedAt: Date.now(),
        endedAt: Date.now(),
      },
    },
  },
});

NotesDirect link to Notes

  • Time travel requires storage to be configured since it relies on persisted workflow snapshots
  • When re-executing a workflow, the workflow loads the existing snapshot from storage (if available)
  • Step results before the target step are reconstructed from the snapshot or provided context
  • Execution begins from the specified step with the provided or reconstructed input data
  • The workflow continues to completion from that point forward
  • Time travel can be used on workflows that have not been run yet by providing custom context or input data for the step to start from.