@mastra/core/dist/docs/references/reference-schedules-overview.md

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

# `mastra.schedules`

**Added in:** `@mastra/core@1.50.0`

`mastra.schedules` is the CRUD service for persisted cron schedules. Use it to create, list, update, pause, resume, manually run, and delete schedules for agents or workflows.

For usage patterns and concepts, see [Schedules](https://mastra.ai/docs/long-running-agents/schedules).

## Usage example

Create an agent schedule:

```typescript
const schedule = await mastra.schedules.create({
  agentId: 'pinger',
  cron: '0 * * * *',
  prompt: 'Give me a status update.',
})
```

Create a workflow schedule:

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

Schedules require a storage adapter that implements the schedules domain. Supported adapters include `@mastra/libsql`, `@mastra/pg`, `@mastra/mysql`, `@mastra/mongodb`, `@mastra/convex`, and `@mastra/spanner`.

## Methods

### Create schedules

#### `create(input)`

Creates an agent or workflow schedule. Pass `agentId` to create an agent schedule, or `workflowId` to create a workflow schedule.

```typescript
const schedule = await mastra.schedules.create({
  agentId: 'pinger',
  cron: '0 * * * *',
  prompt: 'Give me a status update.',
})
```

##### Agent schedule input

**id** (`string`): Optional stable schedule ID. The value is normalized to agent\_\<slug>. When omitted, Mastra generates an agent\_\<uuid> ID.

**agentId** (`string`): ID of the agent to run on each schedule fire.

**cron** (`string`): Cron expression for the schedule. Accepts 5-, 6-, or 7-part cron expressions and Croner nicknames.

**prompt** (`string`): Prompt sent to the agent on each schedule fire.

**name** (`string`): Free-form label for distinguishing multiple schedules on the same agent or thread.

**timezone** (`string`): IANA timezone used to resolve cron fire times, for example America/New\_York.

**threadId** (`string`): Thread that receives the scheduled signal. When omitted, each fire runs threadless with agent.generate().

**resourceId** (`string`): Resource ID for threaded schedules. Required when threadId is set.

**signalType** (`AgentSignalType`): Signal type for threaded schedule fires. Defaults to notification.

**tagName** (`string`): XML tag name used to render the scheduled signal. Defaults to schedule.

**attributes** (`AgentSignalAttributes`): Attributes rendered on the scheduled signal XML tag.

**providerOptions** (`Record<string, unknown>`): JSON-safe provider options merged into the schedule signal payload on every fire.

**ifActive** (`ScheduleIfActive`): Behavior when the target thread is actively streaming. Requires threadId.

**ifIdle** (`ScheduleIfIdle`): Behavior when the target thread is idle. Requires threadId.

**metadata** (`Record<string, unknown>`): Arbitrary metadata stored with the schedule row.

**status** (`'active' | 'paused'`): Initial lifecycle status. Defaults to active. (Default: `'active'`)

##### Workflow schedule input

**id** (`string`): Optional stable schedule ID. The value is normalized to schedule\_\<slug>. When omitted, Mastra generates a schedule\_\<uuid> ID.

**workflowId** (`string`): ID of the workflow to start on each schedule fire.

**cron** (`string`): Cron expression for the schedule. Accepts 5-, 6-, or 7-part cron expressions and Croner nicknames.

**timezone** (`string`): IANA timezone used to resolve cron fire times.

**inputData** (`unknown`): Input data passed to the workflow run.

**initialState** (`unknown`): Initial workflow state for the scheduled run.

**requestContext** (`Record<string, unknown>`): Request context passed to the workflow run.

**metadata** (`Record<string, unknown>`): Arbitrary metadata stored with the schedule row.

**status** (`'active' | 'paused'`): Initial lifecycle status. Defaults to active. (Default: `'active'`)

### Read schedules

#### `get(id)`

Gets a schedule by ID. Bare agent schedule IDs are also resolved to the normalized `agent_<slug>` form.

```typescript
const schedule = await mastra.schedules.get('pinger')
```

#### `list(filter?)`

Lists schedules. Without a filter, it returns agent and workflow schedules.

```typescript
const schedules = await mastra.schedules.list({
  agentId: 'pinger',
  status: 'active',
})
```

**filter** (`ListSchedulesFilter`): Optional filters for the list operation.

**filter.agentId** (`string`): Return only agent schedules for this agent.

**filter.workflowId** (`string`): Return only workflow schedules for this workflow.

**filter.threadId** (`string`): Return only agent schedules for this thread.

**filter.resourceId** (`string`): Return only agent schedules for this resource.

**filter.name** (`string`): Return only agent schedules with this label.

**filter.status** (`'active' | 'paused'`): Return only schedules with this status.

### Update schedules

#### `update(id, patch)`

Updates a schedule. Changing `cron` or `timezone` recomputes the next fire time. Updating `status` from `paused` to `active` also recomputes the next fire time.

```typescript
const updated = await mastra.schedules.update('pinger', {
  cron: '*/30 * * * *',
  prompt: 'Give me a status update every 30 minutes.',
})
```

Agent schedule patches can update `cron`, `timezone`, `prompt`, `name`, `signalType`, `tagName`, `attributes`, `providerOptions`, `ifActive`, `ifIdle`, `metadata`, and `status`. `threadId` and `resourceId` aren't patchable; create a new schedule when the thread target needs to change.

Workflow schedule patches can update `cron`, `timezone`, `inputData`, `initialState`, `requestContext`, `metadata`, and `status`. Agent-only patch fields such as `prompt`, `signalType`, and `ifIdle` throw on workflow schedules.

### Lifecycle

#### `pause(id)`

Pauses a schedule. Pausing is durable and idempotent.

```typescript
const paused = await mastra.schedules.pause('pinger')
```

#### `resume(id)`

Resumes a paused schedule and recomputes the next fire time from the current time.

```typescript
const active = await mastra.schedules.resume('pinger')
```

#### `run(id)`

Fires a schedule once immediately without changing its cron cadence.

```typescript
const run = await mastra.schedules.run('pinger')
```

For agent schedules, `claimId` uses `manual_<scheduleId>_<timestamp>`. For workflow schedules, `claimId` uses `sched_<scheduleId>_<timestamp>` and is reused as the workflow run ID.

#### `delete(id)`

Deletes a schedule. Deleting a missing schedule is a no-op.

```typescript
await mastra.schedules.delete('pinger')
```

## Schedule behavior

- Agent schedule IDs use the `agent_` prefix. Workflow schedule IDs created through `mastra.schedules.create()` use the `schedule_` prefix.
- Threaded agent schedules require `resourceId` when `threadId` is set.
- `signalType`, `ifActive`, `ifIdle`, and `resourceId` require `threadId`.
- Workflow schedules don't accept agent-only patch fields such as `prompt`, `signalType`, or `ifIdle`.
- `run()` publishes a manual fire immediately and doesn't change the stored cron cadence.