@mastra/core 1.6.0 → 1.7.0

package/dist/docs/references/reference-workflows-run-methods-startAsync.md

@@ -1,67 +0,0 @@
-# Run.startAsync()
-
-The `.startAsync()` method starts a workflow run without waiting for completion. It returns immediately with the `runId`, allowing the workflow to execute in the background. This is useful for long-running workflows, scheduled tasks, or when you want to avoid blocking on workflow completion.
-
-## Usage example
-
-```typescript
-const run = await workflow.createRun();
-
-// Fire-and-forget - returns immediately
-const { runId } = await run.startAsync({
-  inputData: {
-    value: "initial data",
-  },
-});
-
-// Optionally poll for completion later
-const result = await workflow.getWorkflowRunExecutionResult(runId);
-```
-
-## Parameters
-
-**inputData?:** (`z.infer<TInput>`): Input data that matches the workflow's input schema
-
-**requestContext?:** (`RequestContext`): Request Context data to use during workflow execution
-
-**initialState?:** (`z.infer<TState>`): Initial state to use for the workflow execution
-
-**tracingOptions?:** (`TracingOptions`): 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.traceId?:stringTrace ID to use for this execution (1-32 hexadecimal characters). If provided, this trace will be part of the specified trace.
-
-**outputOptions?:** (`OutputOptions`): includeState?:booleanWhether to include the workflow run state in the result.
-
-## Returns
-
-**runId:** (`string`): The unique identifier for this workflow run. Use this to check status or retrieve results later.
-
-## When to use startAsync()
-
-Use `startAsync()` instead of `start()` when:
-
-- **Long-running workflows**: The workflow may take minutes or hours to complete
-- **Scheduled/cron triggers**: You want to trigger a workflow without blocking the scheduler
-- **Avoiding polling failures**: With Inngest workflows, `start()` polls for completion which can fail and cause retries. `startAsync()` avoids this issue
-- **Background processing**: You want to queue work and handle results asynchronously
-
-## Checking workflow status
-
-After calling `startAsync()`, you can check the workflow status using:
-
-```typescript
-// Get the execution result (including step outputs)
-const result = await workflow.getWorkflowRunExecutionResult(runId);
-
-if (result?.status === 'success') {
-  console.log('Workflow completed:', result.steps);
-} else if (result?.status === 'failed') {
-  console.log('Workflow failed:', result.error);
-} else if (result?.status === 'running') {
-  console.log('Workflow still running...');
-}
-```
-
-## Related
-
-- [Run.start()](https://mastra.ai/reference/workflows/run-methods/start) - Start a workflow and wait for completion
-- [Workflows overview](https://mastra.ai/docs/workflows/overview)
-- [Workflow.createRun()](https://mastra.ai/reference/workflows/workflow-methods/create-run)

package/dist/docs/references/reference-workflows-run-methods-timeTravel.md

@@ -1,142 +0,0 @@
-# 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 example
-
-```typescript
-const run = await workflow.createRun();
-
-const result = await run.timeTravel({
-  step: "step2",
-  inputData: { value: 10 },
-});
-```
-
-## 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
-
-**outputWriter?:** (`(chunk: TOutput) => Promise<void>`): Optional asynchronous function to handle output chunks as they are produced
-
-**tracingContext?:** (`TracingContext`): currentSpan?:SpanCurrent span for creating child spans and adding metadata. Use this to create custom child spans or update span attributes during execution.
-
-**tracingOptions?:** (`TracingOptions`): 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?:stringTrace ID to use for this execution (1-32 hexadecimal characters). If provided, this trace will be part of the specified trace.parentSpanId?:stringParent 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`): includeState?:booleanWhether to include the workflow run state in the result.includeResumeLabels?:booleanWhether to include resume labels in the result.
-
-## 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 examples
-
-### Time travel with custom context
-
-```typescript
-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 step
-
-```typescript
-// 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 state
-
-```typescript
-const result = await run.timeTravel({
-  step: "step2",
-  inputData: { value: 10 },
-  initialState: {
-    counter: 5,
-    metadata: { source: "time-travel" },
-  },
-});
-```
-
-### Time travel with nested workflows context
-
-```typescript
-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(),
-      },
-    },
-  },
-});
-```
-
-## 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.
-
-## Related
-
-- [Time Travel](https://mastra.ai/docs/workflows/time-travel)
-- [Workflows overview](https://mastra.ai/docs/workflows/overview)
-- [Workflow.createRun()](https://mastra.ai/reference/workflows/workflow-methods/create-run)
-- [Snapshots](https://mastra.ai/docs/workflows/snapshots)
-- [Suspend & Resume](https://mastra.ai/docs/workflows/suspend-and-resume)

package/dist/docs/references/reference-workflows-run.md

@@ -1,59 +0,0 @@
-# Run Class
-
-The `Run` class represents a workflow execution instance, providing methods to start, resume, stream, and monitor workflow execution.
-
-## Usage example
-
-```typescript
-const run = await workflow.createRun();
-
-const result = await run.start({
-  inputData: { value: "initial data" },
-});
-
-if (result.status === "suspended") {
-  const resumedResult = await run.resume({
-    resumeData: { value: "resume data" },
-  });
-}
-```
-
-## Run Methods
-
-**start:** (`(options?: StartOptions) => Promise<WorkflowResult>`): Starts workflow execution with input data
-
-**resume:** (`(options?: ResumeOptions) => Promise<WorkflowResult>`): Resumes a suspended workflow from a specific step
-
-**stream:** (`(options?: StreamOptions) => MastraWorkflowStream`): Monitors workflow execution as a stream of events with enhanced streaming features
-
-**resumeStream:** (`(options?: ResumeStreamOptions) => MastraWorkflowStream`): Resumes a suspended workflow with streaming support
-
-**cancel:** (`() => Promise<{ message: string }>`): Cancels the workflow execution, stopping any running steps and preventing subsequent steps from executing
-
-**restart:** (`(options?: RestartOptions) => Promise<WorkflowResult>`): Restarts the workflow execution from last active step
-
-**timeTravel:** (`(options?: TimeTravelOptions) => Promise<WorkflowResult>`): Re-executes a workflow starting from any specific step, using either stored snapshot data or custom context you provide.
-
-**timeTravelStream:** (`(options?: TimeTravelOptions) => MastraWorkflowStream`): Time travels a workflow execution with streaming support
-
-## Run Status
-
-A workflow run's `status` indicates its current execution state. The possible values are:
-
-**success:** (`string`): All steps finished executing successfully, with a valid result output
-
-**failed:** (`string`): Workflow execution encountered an error during execution, with error details available
-
-**suspended:** (`string`): Workflow execution is paused waiting for resume, with suspended step information
-
-**canceled:** (`string`): Workflow execution was canceled via the cancel() method, stopping any running steps and preventing subsequent steps from executing
-
-## Related
-
-- [Run.start()](https://mastra.ai/reference/workflows/run-methods/start)
-- [Run.resume()](https://mastra.ai/reference/workflows/run-methods/resume)
-- [Run.cancel()](https://mastra.ai/reference/workflows/run-methods/cancel)
-- [Run.restart()](https://mastra.ai/reference/workflows/run-methods/restart)
-- [Run.timeTravel()](https://mastra.ai/reference/workflows/run-methods/timeTravel)
-- [Run.stream()](https://mastra.ai/docs/streaming/workflow-streaming)
-- [Run.timeTravelStream()](https://mastra.ai/reference/streaming/workflows/timeTravelStream)

package/dist/docs/references/reference-workflows-step.md

@@ -1,119 +0,0 @@
-# Step Class
-
-The Step class defines individual units of work within a workflow, encapsulating execution logic, data validation, and input/output handling. It can take either a tool or an agent as a parameter to automatically create a step from them.
-
-## Usage example
-
-```typescript
-import { createWorkflow, createStep } from "@mastra/core/workflows";
-import { z } from "zod";
-
-const step1 = createStep({
-  id: "step-1",
-  description: "passes value from input to output",
-  inputSchema: z.object({
-    value: z.number(),
-  }),
-  outputSchema: z.object({
-    value: z.number(),
-  }),
-  execute: async ({ inputData }) => {
-    const { value } = inputData;
-    return {
-      value,
-    };
-  },
-});
-```
-
-## Creating steps from agents
-
-You can create a step directly from an agent. The step will use the agent's name as its ID.
-
-### Basic agent step
-
-```typescript
-import { testAgent } from "../agents/test-agent";
-
-const agentStep = createStep(testAgent);
-// inputSchema: { prompt: string }
-// outputSchema: { text: string }
-```
-
-### Agent step with structured output
-
-Pass `structuredOutput` to have the agent return typed structured data:
-
-```typescript
-const articleSchema = z.object({
-  title: z.string(),
-  summary: z.string(),
-  tags: z.array(z.string()),
-});
-
-const agentStep = createStep(testAgent, {
-  structuredOutput: { schema: articleSchema },
-});
-// inputSchema: { prompt: string }
-// outputSchema: { title: string, summary: string, tags: string[] }
-```
-
-### Agent step options
-
-**structuredOutput:** (`{ schema: z.ZodType<any> }`): When provided, the agent returns structured data matching this schema instead of plain text. The step's outputSchema is set to the provided schema.
-
-**onFinish:** (`(result: AgentResult) => void`): Callback invoked when the agent completes generation.
-
-## Constructor Parameters
-
-**id:** (`string`): Unique identifier for the step
-
-**description:** (`string`): Optional description of what the step does
-
-**inputSchema:** (`z.ZodType<any>`): Zod schema defining the input structure
-
-**outputSchema:** (`z.ZodType<any>`): Zod schema defining the output structure
-
-**resumeSchema:** (`z.ZodType<any>`): Optional Zod schema for resuming the step
-
-**suspendSchema:** (`z.ZodType<any>`): Optional Zod schema for suspending the step
-
-**stateSchema:** (`z.ZodObject<any>`): Optional Zod schema for the step state. Automatically injected when using Mastra's state system. The stateSchema must be a subset of the workflow's stateSchema. If not specified, type is 'any'.
-
-**requestContextSchema:** (`z.ZodType<any>`): Zod schema for validating request context values. When provided, the context is validated before the step's execute() runs, failing the step if validation fails.
-
-**execute:** (`(params: ExecuteParams) => Promise<any>`): Async function containing step logic
-
-**metadata:** (`Record<string, any>`): Optional key-value pairs for storing additional step information. Values must be serializable (no functions, circular references, etc.).
-
-### ExecuteParams
-
-**inputData:** (`z.infer<TStepInput>`): The input data matching the inputSchema
-
-**resumeData:** (`z.infer<TResumeSchema>`): The resume data matching the resumeSchema, when resuming the step from a suspended state. Only exists if the step is being resumed.
-
-**suspendData:** (`z.infer<TSuspendSchema>`): The suspend data that was originally passed to suspend() when the step was suspended. Only exists if the step is being resumed and was previously suspended with data.
-
-**mastra:** (`Mastra`): Access to Mastra services (agents, tools, etc.)
-
-**getStepResult:** (`(step: Step | string) => any`): Function to access results from other steps
-
-**getInitData:** (`() => any`): Function to access the initial input data of the workflow in any step
-
-**suspend:** (`(suspendPayload: any, suspendOptions?: { resumeLabel?: string }) => Promise<void>`): Function to pause workflow execution
-
-**state:** (`z.infer<TState>`): The current workflow state. Contains shared values that persist across all steps and suspend/resume cycles. The structure is defined by the step's stateSchema.
-
-**setState:** (`(state: z.infer<TState>) => void`): Function to set the state of the workflow. Inject via reducer-like pattern, such as 'setState({ ...state, ...newState })'
-
-**runId:** (`string`): Current run id
-
-**requestContext?:** (`RequestContext`): Request Context for dependency injection and contextual information.
-
-**retryCount?:** (`number`): The retry count for this specific step, it automatically increases each time the step is retried
-
-## Related
-
-- [Workflow state](https://mastra.ai/docs/workflows/workflow-state)
-- [Control flow](https://mastra.ai/docs/workflows/control-flow)
-- [Using agents and tools](https://mastra.ai/docs/workflows/agents-and-tools)

package/dist/docs/references/reference-workflows-workflow-methods-branch.md

@@ -1,25 +0,0 @@
-# Workflow\.branch()
-
-The `.branch()` method creates conditional branches between workflow steps, allowing for different paths to be taken based on the result of a previous step.
-
-## Usage example
-
-```typescript
-workflow.branch([
-  [async ({ context }) => true, step1],
-  [async ({ context }) => false, step2],
-]);
-```
-
-## Parameters
-
-**steps:** (`[() => boolean, Step]`): An array of tuples, each containing a condition function and a step to execute if the condition is true
-
-## Returns
-
-**workflow:** (`NewWorkflow`): The workflow instance for method chaining
-
-## Related
-
-- [Conditional Branching Logic](https://mastra.ai/docs/workflows/control-flow)
-- [Control Flow](https://mastra.ai/docs/workflows/control-flow)

package/dist/docs/references/reference-workflows-workflow-methods-commit.md

@@ -1,17 +0,0 @@
-# Workflow\.commit()
-
-The `.commit()` method finalizes the workflow and returns the final result.
-
-## Usage example
-
-```typescript
-workflow.then(step1).commit();
-```
-
-## Returns
-
-**workflow:** (`Workflow`): The workflow instance for method chaining
-
-## Related
-
-- [Control Flow](https://mastra.ai/docs/workflows/control-flow)

package/dist/docs/references/reference-workflows-workflow-methods-create-run.md

@@ -1,63 +0,0 @@
-# Workflow\.createRun()
-
-The `.createRun()` method creates a new workflow run instance, allowing you to execute the workflow with specific input data. This is the current API that returns a `Run` instance.
-
-## Usage example
-
-```typescript
-await workflow.createRun();
-```
-
-## Parameters
-
-**runId?:** (`string`): Optional custom identifier for the workflow run
-
-**resourceId?:** (`string`): Optional identifier to associate the workflow run with a specific resource (e.g., user ID, tenant ID). This value is persisted with the workflow run and can be used for filtering and querying runs.
-
-**disableScorers?:** (`boolean`): Optional flag to disable scorers for this workflow run
-
-## Returns
-
-**run:** (`Run`): A new workflow run instance that can be used to execute the workflow
-
-## Extended usage example
-
-```typescript
-const workflow = mastra.getWorkflow("workflow");
-
-const run = await workflow.createRun();
-
-const result = await run.start({
-  inputData: {
-    value: 10,
-  },
-});
-```
-
-## Using resourceId
-
-The `resourceId` parameter associates a workflow run with a specific resource, such as a user or tenant. This is useful for multi-tenant applications or when you need to track which user initiated a workflow.
-
-```typescript
-const workflow = mastra.getWorkflow("workflow");
-
-// Create a run associated with a specific user
-const run = await workflow.createRun({
-  resourceId: "user-123",
-});
-
-const result = await run.start({
-  inputData: {
-    value: 10,
-  },
-});
-
-// Later, retrieve the run and access the resourceId
-const storedRun = await workflow.getWorkflowRunById(run.runId);
-console.log(storedRun.resourceId); // "user-123"
-```
-
-## Related
-
-- [Run Class](https://mastra.ai/reference/workflows/run)
-- [Workflows overview](https://mastra.ai/docs/workflows/overview)

package/dist/docs/references/reference-workflows-workflow-methods-dountil.md

@@ -1,25 +0,0 @@
-# Workflow\.dountil()
-
-The `.dountil()` method executes a step until a condition is met. It always runs the step at least once before evaluating the condition. The first time the condition is evaluated, `iterationCount` is `1`.
-
-## Usage example
-
-```typescript
-workflow.dountil(step1, async ({ inputData }) => true);
-```
-
-## Parameters
-
-**step:** (`Step`): The step instance to execute in the loop
-
-**condition:** (`(params : ExecuteParams & { iterationCount: number }) => Promise<boolean>`): A function that returns a boolean indicating whether to continue the loop. The function receives the execution parameters and the iteration count.
-
-## Returns
-
-**workflow:** (`Workflow`): The workflow instance for method chaining
-
-## Related
-
-- [Control Flow](https://mastra.ai/docs/workflows/control-flow)
-
-- [ExecuteParams](https://mastra.ai/reference/workflows/step)

package/dist/docs/references/reference-workflows-workflow-methods-dowhile.md

@@ -1,25 +0,0 @@
-# Workflow\.dowhile()
-
-The `.dowhile()` method executes a step while a condition is met. It always runs the step at least once before evaluating the condition. The first time the condition is evaluated, `iterationCount` is `1`.
-
-## Usage example
-
-```typescript
-workflow.dowhile(step1, async ({ inputData }) => true);
-```
-
-## Parameters
-
-**step:** (`Step`): The step instance to execute in the loop
-
-**condition:** (`(params : ExecuteParams & { iterationCount: number }) => Promise<boolean>`): A function that returns a boolean indicating whether to continue the loop. The function receives the execution parameters and the iteration count.
-
-## Returns
-
-**workflow:** (`Workflow`): The workflow instance for method chaining
-
-## Related
-
-- [Control Flow](https://mastra.ai/docs/workflows/control-flow)
-
-- [ExecuteParams](https://mastra.ai/reference/workflows/step)

package/dist/docs/references/reference-workflows-workflow-methods-foreach.md

@@ -1,118 +0,0 @@
-# Workflow\.foreach()
-
-The `.foreach()` method creates a loop that executes a step for each item in an array. It always returns an array containing the output from each iteration, preserving the original order.
-
-## Usage example
-
-```typescript
-workflow.foreach(step1, { concurrency: 2 });
-```
-
-## Parameters
-
-**step:** (`Step`): The step instance to execute in the loop. The previous step must return an array type.
-
-**opts?:** (`object`): number
-
-## Returns
-
-**workflow:** (`Workflow`): The workflow instance for method chaining. The output type is an array of the step's output type.
-
-## Behavior
-
-### Execution and waiting
-
-The `.foreach()` method processes all items before the next step executes. The step following `.foreach()` only runs after every iteration has completed, regardless of concurrency settings. With `concurrency: 1` (default), items process sequentially. With higher concurrency, items process in parallel batches, but the next step still waits for all batches to finish.
-
-If you need to run multiple operations per item, use a nested workflow as the step. This keeps all operations for each item together and is cleaner than chaining multiple `.foreach()` calls. See [Nested workflows inside foreach](https://mastra.ai/docs/workflows/control-flow) for examples.
-
-### Output structure
-
-`.foreach()` always outputs an array. Each element in the output array corresponds to the result of processing the element at the same index in the input array.
-
-```typescript
-// Input: [{ value: 1 }, { value: 2 }, { value: 3 }]
-// Step adds 10 to each value
-// Output: [{ value: 11 }, { value: 12 }, { value: 13 }]
-```
-
-### Using `.then()` after `.foreach()`
-
-When you chain `.then()` after `.foreach()`, the next step receives the entire output array as its input. This allows you to aggregate or process all results together.
-
-```typescript
-workflow
-  .foreach(processItemStep)    // Output: array of processed items
-  .then(aggregateStep)         // Input: the entire array
-  .commit();
-```
-
-### Using `.map()` after `.foreach()`
-
-Use `.map()` to transform the array output before passing it to the next step:
-
-```typescript
-workflow
-  .foreach(processItemStep)
-  .map(async ({ inputData }) => ({
-    total: inputData.reduce((sum, item) => sum + item.value, 0),
-    count: inputData.length
-  }))
-  .then(nextStep)
-  .commit();
-```
-
-### Chaining multiple `.foreach()` calls
-
-When you chain `.foreach()` calls, each operates on the array from the previous step:
-
-```typescript
-workflow
-  .foreach(stepA)    // If input is [a, b, c], output is [A, B, C]
-  .foreach(stepB)    // Operates on [A, B, C], output is [A', B', C']
-  .commit();
-```
-
-If a step inside `.foreach()` returns an array, the output becomes an array of arrays. Use `.map()` with `.flat()` to flatten:
-
-```typescript
-workflow
-  .foreach(chunkStep)           // Output: [[chunk1, chunk2], [chunk3, chunk4]]
-  .map(async ({ inputData }) => inputData.flat())  // Output: [chunk1, chunk2, chunk3, chunk4]
-  .foreach(embedStep)
-  .commit();
-```
-
-### Progress events during streaming
-
-When using `run.stream()`, foreach steps emit a `workflow-step-progress` event after each iteration completes. This lets you track real-time progress without waiting for the entire foreach to finish.
-
-```typescript
-const run = await workflow.createRun();
-const stream = run.stream({ inputData });
-
-for await (const chunk of stream) {
-  if (chunk.type === 'workflow-step-progress') {
-    console.log(`${chunk.payload.completedCount}/${chunk.payload.totalCount}`);
-    // e.g. "1/3", "2/3", "3/3"
-  }
-}
-```
-
-Each progress event payload contains:
-
-**id:** (`string`): The step ID of the foreach step
-
-**completedCount:** (`number`): Number of iterations completed so far
-
-**totalCount:** (`number`): Total number of iterations
-
-**currentIndex:** (`number`): Index of the iteration that just completed
-
-**iterationStatus:** (`'success' | 'failed' | 'suspended'`): Status of the iteration that just completed
-
-**iterationOutput?:** (`Record<string, any>`): Output of the iteration (present when iterationStatus is 'success')
-
-## Related
-
-- [Looping with foreach](https://mastra.ai/docs/workflows/control-flow)