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 client.getWorkflows();

Working with a Specific Workflow

Get an instance of a specific workflow:

const workflow = client.getWorkflow("workflow-id");

Workflow Methods

Get Workflow Details

Retrieve detailed information about a workflow:

const details = await workflow.details();

Start workflow run asynchronously

Start a workflow run with triggerData and await full run results:

const {runId} = workflow.createRun()
 
const result = await workflow.startAsync({
  runId,
  triggerData: {
    param1: "value1",
    param2: "value2",
  },
});

Resume Workflow run asynchronously

Resume a suspended workflow step and await full run result:

const {runId} = createRun({runId: prevRunId})
 
const result = await workflow.resumeAsync({
  runId,
  stepId: "step-id",
  contextData: { key: "value" },
});

Watch Workflow

Watch workflow transitions

try{
  // Get workflow instance
  const workflow = client.getWorkflow("workflow-id");
 
  // Create a workflow run
  const {runId} = workflow.createRun()
 
  // Watch workflow run 
     workflow.watch({runId},(record)=>{
       // Every new record is the latest transition state of the workflow run
 
        console.log({
          activePaths: record.activePaths,
          context: record.context,
          timestamp: record.timestamp,
          runId: record.runId
        });
     });
 
  // Start workflow run
     workflow.start({
      runId,
      triggerData: {
        city: 'New York',
      },
    });
}catch(e){
  console.error(e);
}

Resume Workflow

Resume workflow run and watch workflow step transitions

try{
  //To resume a workflow run, when a step is suspended
  const {run} = createRun({runId: prevRunId})
 
  //Watch run
   workflow.watch({runId},(record)=>{
   // Every new record is the latest transition state of the workflow run
 
        console.log({
          activePaths: record.activePaths,
          context: record.context,
          timestamp: record.timestamp,
          runId: record.runId
        });
   })
 
   //resume run
   workflow.resume({
      runId,
      stepId: "step-id",
      contextData: { key: "value" },
    });
}catch(e){
  console.error(e);
}

Workflow run result

A workflow run result yields the following:

Field	Type	Description
`activePaths`	`Array<{ stepId: string; stepPath: string[]; status: 'completed' \| 'suspended' \| 'pending' }>`	Currently active paths in the workflow with their execution status
`context`	`{ steps: Record<string, { status: 'completed' \| 'suspended' \| 'running'; [key: string]: any }> }`	Current workflow context including step statuses and additional step data
`timestamp`	`number`	Unix timestamp of when this transition occurred
`runId`	`string`	Unique identifier for this workflow run instance
`suspendedSteps`	`Record<string, any>`	Map of currently suspended steps and their suspension data

Tools API Vectors API