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.

Usage example

Create an agent schedule:

src/mastra/schedules.ts

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

Create a workflow schedule:

src/mastra/schedules.ts

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.

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'

= 'active'

Initial lifecycle status. Defaults to 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'

= 'active'

Initial lifecycle status. Defaults to active.

Read schedules

get(id)

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

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

list(filter?)

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

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

filter?:

ListSchedulesFilter

Optional filters for the list operation.

ListSchedulesFilter

agentId?:

string

Return only agent schedules for this agent.

workflowId?:

string

Return only workflow schedules for this workflow.

threadId?:

string

Return only agent schedules for this thread.

resourceId?:

string

Return only agent schedules for this resource.

name?:

string

Return only agent schedules with this label.

status?:

'active' | 'paused' | 'completed'

Return only schedules with this status. The default listing omits completed schedules.

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. A schedule becomes completed once its cron has no future occurrence. A cadence edit that leaves no future occurrence completes the row even when it was paused. Editing the cadence of a completed schedule reactivates it when the new cadence can still fire, and leaves it completed when it can't.

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.

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

resume(id)

Resumes a paused schedule and recomputes the next fire time from the current time. A paused schedule whose cron has no future occurrence is completed instead of resumed.

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

run(id)

Fires a schedule once immediately without changing its cron cadence.

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.

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.