Skip to Content

Workflows API

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

Initialize Mastra Client

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

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 run = workflow.createRun(); const result = await workflow.startAsync({ runId: run.runId, inputData: { param1: "value1", param2: "value2", }, });

Resume Workflow run asynchronously

Resume a suspended workflow step and await full run result:

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

Watch Workflow

Watch workflow transitions

try { // Get workflow instance const workflow = client.getWorkflow("workflow-id"); // Create a workflow run const run = workflow.createRun(); // Watch workflow run workflow.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 workflow.start({ runId: run.runId, inputData: { city: "New York", }, }); } catch (e) { console.error(e); }

Resume Workflow

Resume workflow run and watch workflow step transitions

try { // Get workflow instance const workflow = client.getWorkflow("workflow-id"); //To resume a workflow run, when a step is suspended const run = workflow.createRun({ runId: prevRunId }); //Watch run workflow.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 workflow.resume({ runId: run.runId, step: "step-id", resumeData: { key: "value" }, }); } catch (e) { console.error(e); }

Workflow run result

A 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