oneShotFireAt. A trigger takes one or the other, never both. There is no interval trigger: express “every N minutes or hours” as a cron expression.
For the workflow execution model itself, see Workflow Execution flow. Webhook and email triggers fire on an event instead of a time; see Ingress and Email.
How the evaluator works
The workflow trigger evaluator platform cron runs every 60 seconds. Each tick it reads up to 200 enabled triggers whose next fire time has passed, oldest first. Triggers beyond that page wait for the next tick. For each due trigger, the evaluator claims the fire and schedules the launch. The launch goes through the same start path as a manual run, attributed to the trigger. A trigger without a pinnedversionId runs the version that is active when the fire is claimed; one with a versionId always runs that version. Each fire passes the trigger’s dispatch arguments, which are validated against the workflow’s input schema when the trigger is saved.
The evaluator does not check whether an earlier run of the same trigger is still going. A trigger whose cadence is shorter than its runs starts overlapping runs.
Before each fire the evaluator checks that the trigger’s creator still holds workflows:manage at the workflow’s home and at the trigger’s org unit: a person through their roles, an External App or platform API key through its own grants. If the creator does not, or the workflow was deleted, the trigger is paused and the reason is recorded. If a trigger is deleted after a fire is claimed, or a cron trigger is paused after its claim, the launch is skipped and recorded as workflow_trigger_fire_skipped. A one-shot is consumed at its claim, so pausing it afterwards does not stop the launch.
Trigger types
Cron triggers
Cron expressions give control over run timing: day of week, time of day, monthly cadence. The expression is parsed bycroner; an expression it cannot parse is rejected when the trigger is saved. Forge sets no minimum cadence, but the evaluator runs once a minute, so a fire can start up to a minute after its scheduled time.
Common patterns:
After each fire, the next fire time is computed from the expression and the current time.
One-shot triggers
oneShotFireAt is an epoch-millisecond time that must be in the future when the trigger is created. The trigger fires once, even if the evaluator reaches it late, and is then disabled; the row stays for its history. A one-shot whose time has passed cannot be resumed.
Timezone support
A cron trigger takes an IANA timezone (America/New_York, Europe/London, Asia/Tokyo); the default is UTC, and an unknown zone is rejected when the trigger is saved. The expression is evaluated in that zone, so 0 9 * * 1-5 with America/New_York fires at 9 AM Eastern on weekdays across daylight saving changes.
Missed fires and backfillPolicy
A cron fire is missed when its window passes without the evaluator claiming it, for example during a platform outage. When the evaluator next reaches the trigger, it looks at up to 11 due windows, oldest first, and applies the trigger’s backfillPolicy:
The scan starts at the trigger’s next fire time and stops after 11 windows, so after a longer gap it covers only the oldest 11.
coalesce then fires the 11th-oldest window, not the latest, and the windows beyond the scan are neither fired nor counted as misses. There is no lookback limit by time: the cap is the number of windows. Email triggers store drop, but they fire on mail, not on the clock. After any policy, the next fire time is computed from the current time, so the trigger does not keep catching up on later ticks. The trigger’s consecutiveMisses counts the windows that did not run.
Trigger lifecycle: enabled, paused, deleted
Resuming a cron trigger computes its next fire time from the current time and resets
consecutiveMisses to 0. It does not backfill the windows that passed while it was paused, whatever its backfillPolicy. A one-shot resumes only while its oneShotFireAt is still in the future.
Operate from Platform → Schedules
Builders create and edit a workflow’s triggers on the workflow’s Schedule tab. Platform → Schedules (/platform/schedules) is the admin-only view, with Recurring, Upcoming and Triggers tabs. The Triggers tab lists the enabled and paused triggers homed at your current org unit; triggers in other units, including the units below it, do not appear:
From the row you can pause or resume a trigger, delete it, or run it now. Use this view, once per org unit, to audit which workflows run on schedules and to confirm next fire times after a timezone or DST change.
Operator runbook
When you set up scheduling for a workflow:- Write the cadence as a cron expression. Use a one-shot trigger for a single future run.
- Set the timezone explicitly when the schedule is calendar-aligned. For a cron that should fire at “9 AM” in some location, set the IANA zone; do not hand-compute UTC offsets.
- Avoid the DST hazard window. Anything between 1 and 3 AM in a timezone that observes DST can skip or double-fire. Pick
0 4 * * *instead of0 2 * * *. - Pick a
backfillPolicy. Keepcoalescewhen one catch-up run is enough, usefire_each_missedwhen each window’s run matters (up to 10 per pass), and usedropwhen a late run is worse than none. After a gap longer than 11 windows, no policy covers the whole backlog: start a manual run if a later window’s run matters. - Check overlap. If a run can last longer than the cadence, widen the cadence: the trigger starts a new run even while the last one is going.
- Verify the next fire time after creation on the workflow’s Schedule tab or in Platform → Schedules → Triggers.
Reference
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 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).
Schedule a workflow to fire at 9 AM Eastern on weekdays. A trigger takes either cronExpression (with timezone) or oneShotFireAt, never both. Without versionId each fire runs the active version, and backfillPolicy (coalesce, fire_each_missed or drop; default coalesce) says what happens to fires missed while the scheduler could not run:
workflows:manage at the workflow’s home and at the trigger’s org unit, and the credential’s scopes must also include workflows:read. An External App’s trigger belongs to the app and is paused, with an audit event, when the app loses workflows:manage; a Personal key’s belongs to its owner and keeps firing after the key expires.
Confirm the next fire time, which needs workflows:read:
nextFireAt is epoch milliseconds, and null when the trigger is disabled or its workflow is paused or retired. POST /api/v3/workflow-triggers/{triggerId}/pause stops a trigger and .../resume starts it again.
Over MCP, create the trigger with forge_call_operation:
forge_call_read_operation:
Cross-links: Workflow Execution flow · Observability · Webhooks
Trigger authority and signed ingress
Creating, changing, or resuming a trigger checks the signed-in operator against the published version’s Credential bindings and agents, just as publishing does. A trigger that follows the active version checks that version at the time of the change. Pausing, disabling (including from the edit dialog), and deleting a trigger remain available with workflow management permission; re-enabling it checks the operator again. A disable that also changes the schedule, backfill policy, or dispatch arguments is a change, and checks the operator like any other. Ingress for a version with company acting-for grants requires HMAC-SHA256 signing. A capability URL alone is insufficient. Enable signing in the ingress configuration and configure the same secret and signature header at the sender. Admission checks the version it will launch before deduplication, so a later privileged publish cannot leave an unsigned follow-active trigger open. Stored secrets and token hashes are never shown in trigger reads. Email routes follow the same rules. Creating a workflow route, or changing one other than disabling it, checks the operator the same way. Mail for a version with company acting-for grants is accepted only on a route whose sender policy requires a DKIM-aligned sender; an open route rejects it before any run starts. A Platform API dispatch that names a callback the published version does not allow gets422 with the reason. A workflow its owner must fix first, such as one with no home, gets
503.
Published callback destinations
In Workflow Settings, select a callback destination policy and publish a new version:- Disabled: no caller callback is accepted. This is also the behavior of older versions with no policy.
- Caller-selected destination: an authenticated external application can choose an HTTPS callback URL that passes the existing network-address checks.
- Fixed destination: publish the exact HTTPS URL and active external application ID. The application must be owned by the workflow’s home org unit or one of its descendants, and configuring it requires external application management permission at the application’s org unit. A caller cannot substitute another URL or application, and each run rechecks the application’s owner before it starts.
Where a workflow may run
A workflow runs at its home org unit. Every launch (the Run button, a schedule, a capability URL, the Platform API, the Personal Agent) is decided there: a person may launch it when they hold workflow execution for the whole platform, or when a role grant forworkflows:use covers the home, either at the home itself or at one of its parent
units. A grant at an unrelated unit does not count, and naming a different org unit on
the request does not change where the check happens. The Run button in the Console also
checks workflow execution for the whole platform before it decides at the home, so a
person whose workflows:use grant is held only at the home, or at one of its parent
units, cannot yet start the run from the Run button.
A Platform API dispatch is bounded by the calling application’s own owning org unit: an
application owned by an org unit may dispatch a workflow only when that unit is the
workflow’s home or one of the home’s parent units. An application owned by unit A can
therefore dispatch workflows homed at A or below it, but not at a sibling of A or at A’s
parent, even when its role grants hold workflows:use there. A launchable workflow outside
that tree answers 404. The application comes from how the request authenticated, never
from the request body. A plain API key has no owning org unit, and neither does an
application owned by a user, factory or project, so neither can dispatch a workflow through
the Platform API. Schedules and capability URLs carry the authority checked when their
trigger was authored.
A workflow with no home, or whose home no longer resolves, cannot be launched by anyone.
Set its home before running it.
Related
- Signed workflow ingress: start a run from an outside system.
- Webhooks: send events out when a run changes.
- Observability: watch scheduled runs.

