> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ship a scheduled, recurring workflow

> End-to-end recipe — turn a working workflow definition into a cron-driven recurring run with envelope budgets, attention items on failure, and a kill-switch the operator can pull.

A recurring workflow is the shape most production agent work eventually takes — ingest, summarize, notify, sleep. Forge ships scheduling as a first-class trigger primitive: a cron expression or a one-time fire, attached to a published workflow, with the same governance, budget, and audit treatment as a manual run. This recipe wires the trigger, sizes the envelope budgets that cap its spend, sets up failure handling, and shows the operator paths for pausing or killing the schedule.

## The end state

When the recipe is done:

* A row exists in `workflowTriggers` with 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](https://docs.gloo.com/forge/run/budgets-and-cost.md) cap the spend of every scheduled run.
* A failure on a scheduled run produces an [attention item](https://docs.gloo.com/forge/run/observability.md) the operator sees in the [Watchtower](https://docs.gloo.com/forge/console/observe.md).
* 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_BASE` from the Raw HTTP tab of the [quickstart](https://docs.gloo.com/forge/quickstart.md) and a credential, not the quickstart's `ACCESS_TOKEN`, with `workflows:manage` at the workflow's home and the trigger's org unit, and `workflows:read` in the credential's scopes. The workflow's agents and bound companies must pass `agents:use` and `credentials:use`, as at a publish. Cancelling one run needs `runs:manage`.

## The four steps

SHIP A RECURRING WORKFLOW

<ol aria-label="SHIP A RECURRING WORKFLOW" />

**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](https://docs.gloo.com/forge/recipes/add-workflow-with-hitl-approval.md) 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](https://docs.gloo.com/forge/run/scheduling-and-triggers.md) accepts a standard cron expression (`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`.

```yaml theme={null}
# The trigger as GET /api/v3/workflow-triggers/{triggerId} returns it (abridged).
# The create body sends orgUnitId, cronExpression, timezone and versionId.
kind: cron
cronExpression: "0 6 * * 1-5"
timezone: "America/New_York"
workflowId: "<workflow id>"
pinnedVersionId: "<version id>"
enabled: true
```

Behind the scenes, the cron evaluator wakes every 60 seconds, evaluates every active trigger using the `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](https://docs.gloo.com/forge/run/budgets-and-cost.md), 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](https://docs.gloo.com/forge/console/observe.md).** Every scheduled run lands here in the run timeline alongside manual runs. Failures auto-create an [attention item](https://docs.gloo.com/forge/run/observability.md) — 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](https://docs.gloo.com/forge/quickstart.md) 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`:

```bash theme={null}
curl -sS "$FORGE_BASE/api/v3/workflow-triggers?kind=cron" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  | jq '.data[] | select(.lastRun.status == "failed") | {triggerId: .trigger.id, workflow: .workflow.name, lastRun}'
```

## Do it over the API

These calls use the `FORGE_BASE` set up in the Raw HTTP tab of the [quickstart](https://docs.gloo.com/forge/quickstart.md). 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](https://docs.gloo.com/forge/reference/conventions.md#requesting-scopes-at-token-mint)), or send a [Personal key](https://docs.gloo.com/forge/console/settings/personal-keys.md#choose-scopes) 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](https://docs.gloo.com/forge/console/settings/personal-keys.md#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:

```bash theme={null}
TRIGGER_ID=$(curl -sS -X POST "$FORGE_BASE/api/v3/workflows/$WORKFLOW_ID/triggers" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice-ingest-weekday-6am-v1" \
  -d "{\"orgUnitId\": \"$ORG_UNIT_ID\", \"versionId\": \"$VERSION_ID\", \"cronExpression\": \"0 6 * * 1-5\", \"timezone\": \"America/New_York\"}" \
  | jq -r '.data.trigger.id')
```

This needs `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`:

```bash theme={null}
curl -sS "$FORGE_BASE/api/v3/workflows/$WORKFLOW_ID/triggers" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  | jq '.data[] | {id, kind, pinnedVersionId, cronExpression, timezone, enabled, nextFireAt, consecutiveMisses}'
```

Pause the trigger when the workflow itself is at fault. It needs `workflows:manage`, and pausing a paused trigger succeeds without change:

```bash theme={null}
curl -sS -X POST "$FORGE_BASE/api/v3/workflow-triggers/$TRIGGER_ID/pause" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: invoice-ingest-pause-v1" \
  | jq '.data.trigger | {id, enabled, nextFireAt}'
```

To stop one running run, `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`:

```json theme={null}
{
  "operationId": "createWorkflowTrigger",
  "input": { "workflowId": "<workflow id>", "orgUnitId": "<org unit id>", "versionId": "<version id>", "cronExpression": "0 6 * * 1-5", "timezone": "America/New_York" },
  "idempotencyKey": "invoice-ingest-weekday-6am-v1"
}
```

and pause it the same way:

```json theme={null}
{ "operationId": "pauseWorkflowTrigger", "input": { "id": "<trigger id>" }, "idempotencyKey": "invoice-ingest-pause-v1" }
```

`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](https://docs.gloo.com/forge/run/webhooks.md) for inbound HTTP triggers, and [Webhooks](https://docs.gloo.com/forge/run/webhooks.md) 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.

**A schedule without an attention item is a schedule that fails silently. A schedule without a kill switch is a schedule that nobody trusts.**


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.