Skip to main content
The schedule UI lives under /settings/schedule. Admins on a Builder workspace can create and manage scheduled runs from here; Free workspaces see an upgrade panel instead of the form.

​
Routes

Scheduled runs have their own tab in the settings header nav (/settings/schedule), alongside Account, Billing, API keys, Workspace, and Data sources.

​
The form

/settings/schedule/new and /settings/schedule/[id]/edit share <ScheduleFormFields>. Field order:
1

BYOK key

Dropdown of every BYOK key on the workspace. The selection drives which models are available in the next field.No BYOK key? Add one at /settings/api-keys → BYOK panel before coming back. See BYOK keys.
2

Model

Filtered against KNOWN_MODELS[provider] based on the BYOK selection:
  • Anthropic — claude-opus-4-7, claude-sonnet-4-6, claude-haiku-4-5
  • OpenAI — gpt-5.5, gpt-5.4-mini, gpt-5
The runner rejects anything outside the whitelist at save time.
3

Block (optional)

Optional. Pick a block to focus the run on — usually so the prompt can refer to “this block” and the agent has an obvious write target via blocks.setWidgetData. Leave blank for a workspace-wide run.
4

Prompt

Plain-English instructions, up to 4000 chars. The runner passes this verbatim into generateText along with the tool set discovered from tools/list.Treat the prompt like a system prompt for a one-off agent. Be specific about which tool to call and on which block / data source.
5

Cron expression

Preset dropdown (every-15-min / every-hour / daily-9am / weekdays-9am / custom) plus a raw cron field. All cron times are UTC — Trigger.dev does not respect any local-timezone hint in v1.See Concepts → Cron presets for the preset values.
After save, the row syncs to Trigger.dev via schedules.create. The returned schedule id is stored on the row as triggerScheduleId — you don’t see it in the UI, but it’s how pause/resume/delete sync back through the SDK.

​
The list view

/settings/schedule shows one row per saved schedule with:
  • Status badge — active / paused / error. Errors include the most recent errorMessage.
  • Cron expression plus a human label if it matches a preset.
  • Last run — relative timestamp from the most recent scheduledRunHistory row.
  • Actions — Run now (admin + active only), Pause / Resume, Edit, History, Delete.
The Run-now button is the small Zap icon. It calls scheduledRuns.runNow, which dispatches tasks.trigger("scheduled-agent-run", { scheduledRunId }) against Trigger.dev. A new scheduledRunHistory row appears in History within ~10–30 seconds.

​
Pause and resume

Both flip the row’s status field and call Trigger.dev’s schedules.update to toggle the schedule on the Trigger side. Paused schedules stay in the list but don’t fire on the cron until resumed.

​
History

/settings/schedule/[id]/history lists scheduledRunHistory rows in reverse chronological order. Columns: First page is 50; “Load more” extends to 200. Beyond that, drop into the Convex dashboard.

​
Delete

Deleting a scheduled run:
  1. Removes the scheduledRuns row.
  2. Cascades the per-row system-flagged cb_live_* key (so the runner can never invoke MCP with this key again).
  3. Calls Trigger.dev schedules.del to remove the cron from their side.
  4. Leaves scheduledRunHistory rows in place (for audit; they’ll fall off via retention later).

​
Plan gating

The form components include UI-only checks (e.g. disabling Save), but the authoritative gate is server-side. requireProPlan (the function name predates the Pro → Builder rename) runs at the top of schedule.set, schedule.pause, schedule.resume, schedule.delete, schedule.preview, and schedule.runNow — both UI mutations and MCP tool calls go through it. Free workspaces calling these via MCP get a PRO_REQUIRED error on the wire; the UI shows a Builder upsell panel linking to /settings/billing.

​
What’s next

Preview and run-now

Test a prompt without waiting for the cron, or fire a one-off run of a saved schedule.

BYOK keys

Manage the LLM keys that scheduled runs decrypt at runtime.