Workflows API

The Workflows API provides methods to interact with and execute automated workflows in Mastra.

Getting All Workflows

Retrieve a list of all available workflows:

const workflows = await mastraClient.listWorkflows();

Working with a Specific Workflow

Get an instance of a specific workflow by its ID:

src/mastra/workflows/test-workflow.ts

export const testWorkflow = createWorkflow({
  id: "city-workflow",
});

const workflow = mastraClient.getWorkflow("city-workflow");

Workflow Methods

details()

Retrieve detailed information about a workflow:

const details = await workflow.details();

createRun()

Create a new workflow run instance:

const run = await workflow.createRun();

// Or with an existing runId
const run = await workflow.createRun({ runId: "existing-run-id" });

startAsync()

Start a workflow run and await the full result:

const run = await workflow.createRun();

const result = await run.startAsync({
  inputData: {
    city: "New York",
  },
});

You can also pass initialState to set the starting values for the workflow's state:

const result = await run.startAsync({
  inputData: {
    city: "New York",
  },
  initialState: {
    count: 0,
    items: [],
  },
});

The initialState object should match the structure defined in the workflow's stateSchema. See Workflow State for more details.

start()

Start a workflow run without waiting for completion:

const run = await workflow.createRun();

await run.start({
  inputData: {
    city: "New York",
  },
});

// Poll for results later
const result = await workflow.runExecutionResult(run.runId);

This is useful for long-running workflows where you want to start execution and check results later.

resumeAsync()

Resume a suspended workflow step and await the full result:

const run = await workflow.createRun({ runId: prevRunId });

const result = await run.resumeAsync({
  step: "step-id",
  resumeData: { key: "value" },
});

resume()

Resume a suspended workflow step without waiting for completion:

const run = await workflow.createRun({ runId: prevRunId });

await run.resume({
  step: "step-id",
  resumeData: { key: "value" },
});

stream()

Stream workflow execution for real-time updates:

const run = await workflow.createRun();

const stream = await run.stream({
  inputData: {
    city: "New York",
  },
});

for await (const chunk of stream) {
  console.log(JSON.stringify(chunk, null, 2));
}

runExecutionResult()

Get the execution result for a workflow run:

const result = await workflow.runExecutionResult(runId);

Run result format

A workflow run result yields the following:

runId:

string

Unique identifier for this workflow run instance

eventTimestamp:

Date

The timestamp of the event

payload:

object

Contains currentStep (id, status, output, payload) and workflowState (status, steps record)