> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# 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:

```typescript
const workflows = await mastraClient.listWorkflows()
```

## Working with a specific workflow

Get an instance of a specific workflow by its ID:

```typescript
export const testWorkflow = createWorkflow({
  id: 'city-workflow',
})
```

```typescript
const workflow = mastraClient.getWorkflow('city-workflow')
```

## Workflow methods

### `details()`

Retrieve detailed information about a workflow:

```typescript
const details = await workflow.details()
```

### `createRun()`

Create a new workflow run instance:

```typescript
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 its completion, returning the full result as the workflow output.

```typescript
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:

```typescript
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](https://mastra.ai/docs/workflows/workflow-state) for more details.

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

```typescript
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 (fire-and-forget). Returns immediately with a success message. Use `runById()` on the workflow instance to check results later:

```typescript
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:

```typescript
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:

```typescript
const run = await workflow.createRun({ runId: prevRunId })

await run.resume({
  step: 'step-id',
  resumeData: { key: 'value' },
})
```

When a [`.foreach()`](https://mastra.ai/reference/workflows/workflow-methods/foreach) step suspends across multiple iterations, pass `forEachIndex` (zero-based; `0` targets the first iteration) to resume one iteration at a time. Iterations you don't target remain suspended.

```typescript
await run.resume({
  step: 'approve',
  resumeData: { ok: true },
  forEachIndex: 1, // resumes the second iteration
})
```

`forEachIndex` is also supported by `resumeAsync()` and `resumeStream()`.

### `cancel()`

Cancel a running workflow:

```typescript
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()](https://mastra.ai/reference/workflows/run-methods/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:

```typescript
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:

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

### Run result format

A workflow run result yields the following:

**runId** (`string`): Unique identifier for this workflow run instance

**eventTimestamp** (`Date`): The timestamp of the event

**payload** (`object`): Contains currentStep (id, status, output, payload) and workflowState (status, steps record)

## Schedules

Schedules are declared in code via the `schedule` field on `createWorkflow`. The client SDK exposes read and operational methods for managing workflow schedules at runtime. See [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows).

### `createSchedule()`

Create a workflow schedule by passing `workflowId`.

```typescript
const schedule = await mastraClient.createSchedule({
  workflowId: 'daily-report',
  cron: '0 9 * * *',
  inputData: { reportType: 'summary' },
})
```

### `listSchedules()`

List workflow schedules, optionally filtered by workflow ID or status.

```typescript
const schedules = await mastraClient.listSchedules({
  workflowId: 'daily-report',
  status: 'active',
})
```

### `getSchedule()`

Fetch a single workflow schedule by ID.

```typescript
const schedule = await mastraClient.getSchedule('daily-report')
```

### `updateSchedule()`

Update a workflow schedule.

```typescript
const updated = await mastraClient.updateSchedule('daily-report', {
  cron: '0 10 * * *',
  inputData: { reportType: 'summary' },
})
```

### `deleteSchedule()`

Delete a workflow schedule.

```typescript
await mastraClient.deleteSchedule('daily-report')
```

### `runSchedule()`

Fire a workflow schedule once immediately without changing its cron cadence.

```typescript
const run = await mastraClient.runSchedule('daily-report')
```

### `pauseSchedule()`

Pause a schedule so the scheduler stops firing it. Returns the updated schedule.

```typescript
await mastraClient.pauseSchedule('daily-report')
```

### `resumeSchedule()`

Resume a paused schedule. The next fire time is recomputed from now, so a long-paused schedule doesn't fire a backlog. Returns the updated schedule.

```typescript
await mastraClient.resumeSchedule('daily-report')
```

### `listScheduleTriggers()`

List the trigger history for a workflow schedule, including the joined run summary for each fire.

```typescript
const { triggers } = await mastraClient.listScheduleTriggers('daily-report', {
  limit: 50,
})
```