Skip to Content
ReferenceClient SDK - JSWorkflows (vNext) API

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:

FieldTypeDescription
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
eventTimestampDateThe timestamp of the event
runIdstringUnique identifier for this workflow run instance