The end state
When the recipe is done:- A row exists in
workflowTriggerswith a cron expression, attached to a published workflow and optionally pinned to one version. - The 60-second cron evaluator reads the trigger, dispatches a run when the schedule fires, and writes the dispatch to
auditEvents. - Envelope budgets cap the spend of every scheduled run.
- A failure on a scheduled run produces an attention item the operator sees in the Watchtower.
- The operator can pause the schedule, edit the cron, or kill the run mid-execution from the Console without touching code.
Prerequisites
- A published workflow to schedule, and Console access to size its envelope budget.
- For the API path: the
FORGE_BASEfrom the Raw HTTP tab of the quickstart and a credential, not the quickstart’sACCESS_TOKEN, withworkflows:manageat the workflow’s home and the trigger’s org unit, andworkflows:readin the credential’s scopes. The workflow’s agents and bound companies must passagents:useandcredentials:use, as at a publish. Cancelling one run needsruns:manage.
The four steps
1
Pin the workflow
A scheduled trigger runs a published version of a workflow, never the draft: the version you pin with
versionId, or, without one, the version active when each fire is claimed. Publish a version through the Console at Production → Workflows → [workflow] → Publish, or with POST /api/v3/workflows/{workflowId}/publish-draft. The published version is the immutable graph the trigger will dispatch — edits to the draft do not retroactively change scheduled runs in flight.If you don’t have the workflow yet, walk Add a workflow with HITL approval first to compose one. Recurring workflows can include human-worker produce nodes — the schedule just kicks the run; if the run pauses for approval, the next scheduled invocation still fires on time and runs in parallel.2
Schedule the trigger
Workflow scheduling accepts a standard cron expression (Behind the scenes, the cron evaluator wakes every 60 seconds, evaluates every active trigger using the
0 6 * * 1-5 for weekday 6 AM, */15 * * * * for every 15 minutes) or a one-time fire at oneShotFireAt. Author the trigger in the Console at Production → Workflows → [workflow] → Triggers or with POST /api/v3/workflows/{workflowId}/triggers.croner library, and dispatches any that are due. The evaluator is idempotent — if the platform was offline at 06:00 and recovers at 06:00:42, the trigger still fires once. The schedule lives on the workflow trigger, not on the workflow definition, so one pinned version can carry many triggers (a daily 6 AM summary, a Monday report) and you can change any of them without republishing.The timezone field is honored at evaluation time. Always set it; relying on the deployment’s local time is a Friday-afternoon bug waiting to happen during DST transitions.3
Cap the spend
A workflow definition has no budget field of its own. Scheduled spend is capped by the budgets every dispatch passes: envelope budgets, such as a
daily envelope on the agents the workflow dispatches, and the org-unit budgets above them. If the schedule fires twelve times a day, all twelve runs spend against the same ceilings, so size a daily envelope for the whole schedule rather than for one run.The budgetAgent, budgetEnvelopes and budgetHierarchy gates (10th to 12th in the engine sequence) check those ceilings on every dispatch in every scheduled run. When a ceiling is exhausted, the next dispatch is blocked with a budget reason code such as budget_exceeded; steps that already completed keep their results. A later scheduled run is blocked the same way until the budget period resets or an operator raises the ceiling.4
Watch and intervene
Three operator surfaces matter for scheduled work:The Watchtower. Every scheduled run lands here in the run timeline alongside manual runs. Failures auto-create an attention item — a row that surfaces in the operator’s morning queue with the run ID, the failure type, and the schedule that produced it. Resolve the attention item by clicking through to the run, fixing the upstream issue, and either retriggering the schedule manually or marking the failure as expected.The trigger control. Open Production → Workflows → [workflow] → Triggers to pause, edit, or remove a schedule. Pausing (
POST /api/v3/workflow-triggers/{triggerId}/pause) sets the trigger’s enabled to false and clears its nextFireAt, so the cron evaluator does not dispatch it. Editing the cron is one field; the change applies on the next 60-second evaluation tick. Removing the trigger leaves all in-flight scheduled runs alone — they finish on whatever pinned version they started on. A schedule runs on its creator’s authority: before every fire the scheduler checks that the creator still holds workflows:manage at the workflow’s home and at the schedule’s own org unit (the unit its runs are recorded in), and pauses the schedule (a workflow_trigger_refused audit event, reason creator_authority_lost) when they no longer do — so when the person who set up a schedule leaves or changes role, recreate it under someone who still owns the workflow.The kill switch. A scheduled run mid-flight that is misbehaving — wrong data ingested, runaway agent loop, cost spiking — needs an immediate stop. The run’s kill switch (POST /api/v3/runs/{runId}/set-kill-switch, switches:use) refuses every sandbox command the run issues while it is set and audits the reason; it does not cancel the run. To end the run, cancel it (POST /api/v3/runs/{runId}/cancel). The schedule keeps firing; subsequent runs start fresh. If the upstream bug is in the workflow itself, pause the trigger first, then cancel the run, then publish a fix.To find schedules whose latest run failed, read the schedule roster with the FORGE_BASE from the Raw HTTP tab of the quickstart and an ACCESS_TOKEN minted with scope=workflows:read runs:read; the quickstart’s token lacks workflows:read. It needs workflows:read; lastRun is filled only when the credential also reaches runs:read:Do it over the API
These calls use theFORGE_BASE set up in the Raw HTTP tab of the quickstart. The quickstart’s ACCESS_TOKEN does not carry every scope they need, so mint it again with scope=workflows:manage workflows:read agents:use credentials:use runs:read from an app whose roles hold them (see Requesting scopes at token mint), or send a Personal key whose scopes include them; workflows:manage is elevated, so tick Include elevated permissions when you choose the key’s scopes (see Approve and administer scopes). Publish the workflow and size the envelope budgets in Console; the trigger and its controls go over HTTP.
Create a weekday 6 AM Eastern trigger pinned to one published version:
workflows:manage at the workflow’s home and the trigger’s org unit, with workflows:read in the credential’s scopes. A trigger runs a published version, so its agents and bound companies are checked as at a publish (agents:use and credentials:use); a refusal is 422 naming the gate. Omit versionId to have each fire run the version active at that time. Check the next fire time, which needs workflows:read:
workflows:manage, and pausing a paused trigger succeeds without change:
POST /api/v3/runs/{runId}/cancel (runs:manage) requests cancellation; the run reports cancellation_requested until in-flight work drains.
Over MCP, create the trigger with forge_call_operation:
forge_cancel_run, in the default start job, cancels a run.
When to reach for something else
- The cadence is once a quarter, once a year, or “when the auditors ask.” Don’t schedule it. Manual dispatch is the right shape for low-frequency work — schedules drift, and a quarterly run that hasn’t fired in 89 days is one bad cron expression away from never firing again. Trigger from the Console when the time comes, or from a webhook when an external system signals the moment.
- The trigger should fire on an external event, not a clock. Cron is for time; webhooks are for events. See Webhooks for inbound HTTP triggers, and Webhooks for the outbound side (pushing Forge events to your systems).
- The schedule is dense — every 30 seconds, every minute. Forge’s evaluator wakes every 60 seconds, so sub-minute cadence is not what scheduling is for. If you need sub-minute work, the right shape is a long-running workflow with an internal loop, not many fast triggers.
- You need cross-trigger coordination — “fire job B only after job A succeeds.” Don’t model that as two schedules. Compose A and B into one workflow with sequential nodes; the orchestrator handles the dependency directly.

