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:

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' })

// Or with a resourceId to associate the run with a specific resource
const run = await workflow.createRun({
  runId: 'my-run-id',
  resourceId: 'user-123',
})

The resourceId parameter associates the workflow run with a specific resource (e.g., user ID, tenant ID). This value is persisted with the run and can be used for filtering and querying runs later.

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.

To associate a run with a specific resource, pass resourceId to createRun():

const run = await workflow.createRun({ resourceId: 'user-123' })

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

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.runById(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' },
})

cancel()

Cancel a running workflow:

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

const result = await run.cancel()
// Returns: { message: 'Workflow run canceled' }

This method stops any running steps and prevents subsequent steps from executing. Steps that check the abortSignal parameter can respond to cancellation by cleaning up resources (timeouts, network requests, etc.).

See the Run.cancel() reference for detailed information about how cancellation works and how to write steps that respond to cancellation.

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))
}

runById()

Get the execution result for a workflow run:

const result = await workflow.runById(runId)

// Or with options for performance optimization:
const result = await workflow.runById(runId, {
  fields: ['status', 'result'], // Only fetch specific fields
  withNestedWorkflows: false, // Skip expensive nested workflow data
  requestContext: { userId: 'user-123' }, // Optional request context
})

A workflow run result yields the following:

<PropertiesTable content={[ { name: 'runId', type: 'string', description: 'Unique identifier for this workflow run instance', }, { name: 'eventTimestamp', type: 'Date', description: 'The timestamp of the event', }, { name: 'payload', type: 'object', description: 'Contains currentStep (id, status, output, payload) and workflowState (status, steps record)', }, ]} />