Workflows (vNext) API

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

Initialize Mastra Client


import { MastraClient } from "@mastra/client-js";
 
const client = new MastraClient();

Getting All vNext Workflows

Retrieve a list of all available vNext workflows:


const workflows = await client.getVNextWorkflows();

Working with a Specific vNext Workflow

Get an instance of a specific vNext workflow:


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

vNext Workflow Methods

Get vNext Workflow Details

Retrieve detailed information about a vNext workflow:


const details = await workflow.details();

Start vNext workflow run asynchronously

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


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

Resume vNext Workflow run asynchronously

Resume a suspended vNext workflow step and await full run result:


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

Watch vNext Workflow

Watch vNext workflow transitions


try {
  // Get workflow instance
  const workflow = client.getVNextWorkflow("workflow-id");
 
  // Create a workflow run
  const run = workflow.createRun();
 
  // Watch workflow run
  run.watch({ runId: run.runId }, (record) => {
    // Every new record is the latest transition state of the workflow run
 
    console.log({
      currentStep: record.payload.currentStep,
      workflowState: record.payload.workflowState,
      eventTimestamp: record.eventTimestamp,
      runId: record.runId,
    });
  });
 
  // Start workflow run
  run.start({
    runId: run.runId,
    inputData: {
      city: "New York",
    },
  });
} catch (e) {
  console.error(e);
}

Resume vNext Workflow

Resume vNext workflow run and watch vNext workflow step transitions


try {
  // Get workflow instance
  const workflow = client.getVNextWorkflow("workflow-id");
 
  //To resume a workflow run, when a step is suspended
  const run = workflow.createRun({ runId: prevRunId });
 
  //Watch run
  run.watch({ runId: run.runId }, (record) => {
    // Every new record is the latest transition state of the workflow run
 
    console.log({
      currentStep: record.payload.currentStep,
      workflowState: record.payload.workflowState,
      eventTimestamp: record.eventTimestamp,
      runId: record.runId,
    });
  });
 
  //resume run
  run.resume({
    runId: run.runId,
    step: "step-id",
    resumeData: { key: "value" },
  });
} catch (e) {
  console.error(e);
}

Note: don’t destructure the run instance i.e. don’t do


const { start, resume, ... } = workflow.createRun();
 
// NOR
 
const run = workflow.createRun();
const { start, resume, ... } = run;

it will break the connection to the workflow and prevent it from running

vNext Workflow run result

A vNext workflow run result yields the following:

Field	Type	Description
`payload`	`{currentStep?: {id: string, status: string, output?: Record<string, any>, payload?: Record<string, any>}, workflowState: {status: string, steps: Record<string, {status: string, output?: Record<string, any>, payload?: Record<string, any>}>}}`	The current step and workflow state of the run
`eventTimestamp`	`Date`	The timestamp of the event
`runId`	`string`	Unique identifier for this workflow run instance