Skip to main content
A Loop is standing work a Reason does. Something wakes it: a schedule, a webhook, a GitHub event or a Slack message. Each wake opens or continues a Session of that Reason, with the Loop’s prompt as its instructions. Loops were called routines and automations before. The CLI command is still reason routines, and the API scopes are still automations:read and automations:write.

What wakes a Loop

Schedules

A schedule takes one of three forms: A cron expression is read in the Loop’s time zone, an IANA name such as America/Los_Angeles. The default is UTC. Every scheduled run is a run of the Reason: there is no schedule that runs a command or tool call without it. Some Workspaces can give a cron schedule a window in early access (flex_minutes, up to 120). The Loop then runs at one fixed point in that window after each scheduled time, so Loops on the same schedule don’t all start at once. A scheduled Loop can end by itself. Set until (no wake after that time) or max_runs (a number of runs from 1 to 100,000). Once it reaches either, its status reads completed. A Loop woken by events has no end of its own.

Webhooks

A Loop with a webhook gives out a URL and a key. The key is shown once, when the webhook is created; store it then. The sender authenticates in one of these ways:
  • The key as Authorization: Bearer <key>.
  • An HMAC signature of the body keyed with the key, in X-Signature-256 for a sender you write. GitHub (X-Hub-Signature-256), Standard Webhooks and Svix, Linear, Sentry and Shopify send their own signature headers once you paste the key in as their webhook secret.
  • A signature by a secret the sender generated, such as Stripe’s Stripe-Signature. Store that secret and name it as the Loop’s signing_secret_name.
  • The key as the last path segment of the URL, for a sender that only takes a URL. Prefer a header or a signature where the sender allows one: a URL is easier to leak.
Signatures that carry a timestamp are refused once it is over 5 minutes old. A retry with the same event id is answered 202 with duplicate: true and is not queued again. A paused or deleted Loop refuses events with 409 automation_disabled. Each event opens a Session. Events that share an X-Webhook-Correlation-Key header continue one Session. The event’s body, at most 256 KiB, reaches the Reason as untrusted data, never as instructions. A webhook can carry a condition: plain words a small model checks each event against before it opens a Session, for example a bug report or a complaint, not praise. An unclear answer still wakes the Loop.

GitHub events

A GitHub Loop names one repository connected to the Workspace, as owner/name, and one event. Its runs work in that repository. Filters narrow it. Only issues or pull requests that match every filter wake the Loop:
  • label: the name of a GitHub label.
  • author: up to 20 GitHub logins; the issue or pull request must have been opened by one of them.
  • title_contains: text the title must contain.
All three compare without regard to case.

Slack messages

A Slack Loop listens in channels that the Reason’s Slack app is in. You choose what in those channels wakes it: You can also limit it to certain Slack users, let other apps’ posts wake it (emails sent to the channel, alerts and integrations), name a channel where the Reason flags things for the team, and add a condition as for webhooks. A Slack Loop answers as its Reason, with one Session per Slack thread. See Slack.

Schedule or event?

Wake a Loop on the event when there is one. A Loop that reacts to a new issue, a failed check or a Slack message runs only when that happens. A schedule that checks for it runs every time, whether or not anything changed.

Run a script on a schedule

To run the same script or command regularly, keep the work in a skill and let a Loop run it:
  1. Put the script in a skill, with what counts as worth reporting, for example “report only if the export fails”.
  2. Create a Loop whose prompt names the skill as a goal: Run the nightly-export skill. Report only if it fails.
  3. Pin a small, cheap model on the Loop. Running a known script needs little reasoning.
The Reason reads the result each time, so it can notice a failure, retry, or tell you, which a bare scheduled command can’t. Write the prompt as what you want done rather than exact tool calls, so the run still works when a tool changes.

Where a Loop runs

  • One Session or a new one each time. A scheduled Loop either continues one Session across its wakes or opens a new Session on every wake. A Loop woken by events opens a Session per event.
  • Cloud or your computer. A Loop’s runs use a Reason cloud computer unless you give it one of your connected computers.
  • Model. A Loop runs on the model you pin for it. Without one, it uses the model of the Session it continues, or the Workspace’s.
  • Notifications. A Loop tells you about a run on important updates, which is the default, or only when a run fails.

Create a Loop

Ask a Reason. Describe the work and when it should happen. The Reason sets the Loop up and files it under itself:
Slack, GitHub and webhook Loops are set up in the app or by asking a Reason. When a Reason sets up a webhook for you, it gives you the URL and stores the key as a secret. In the app. A Reason’s Loops are listed under Loops on that Reason. Create a loop starts a message to the Reason for you to finish. From a terminal. The CLI adds scheduled Loops:
Without --reason, a Loop is filed under your main Reason. reason routines lists Loops that events wake as well. With the API. Create a Loop takes a prompt and a wake_on list:

Run, pause and delete

  • Run now. A scheduled Loop can run once outside its schedule. The run starts within a minute, and the schedule and the next regular run stay as they were.
  • Pause and resume. A paused Loop wakes on nothing. When you resume it, it continues from its next slot.
  • Delete. Deleting a Loop removes everything that wakes it, and its webhook key stops working. The Sessions it opened are kept.
In the app, a Loop’s menu has Run now, Pause or Resume, and Delete.

When Reason pauses a Loop

Reason pauses a Loop that can no longer run and says why. The reasons include:
  • Three runs in a row failed.
  • The Workspace is out of credits, or needs credits or a plan.
  • The Loop’s repository was disconnected. Reconnect it, then resume the Loop.
  • The Loop’s model account is not connected. The Loop resumes once you reconnect it.
  • The person who created it left the Workspace, or can no longer use the Session it runs in.
Through the API, a paused Loop names the cause in paused_reason.

Who can change a Loop

Who sees and changes a Loop follows its Reason:
  • The people who can use the Reason see and change its Loops.
  • A teammate’s Loop on a team Reason stays that teammate’s. The Reason’s owner may see it and stop it.
  • Workspace owners and admins may pause and delete any Loop.
  • What a Loop runs in (its Session or computer), its Slack channels and what wakes it stay with the person who created it.
Each run is a Session of the Reason and is billed like one.

Limits

  • A Workspace holds at most 2,000 live Loops across everyone in it. A new one past that is refused; existing Loops keep running.
  • A Workspace’s schedules together may run at most 1,000 times a day. A new or changed schedule past that is refused with schedule_budget_reached and a message saying what to change; schedules already saved keep running.
  • The Workspace’s plan and credits must be able to run the Loop’s model. See Plans. Free with ads does not cover Loops.
  • Through the API, a Loop’s prompt is at most 100,000 characters and its name at most 200.
  • A Loop has at most one schedule, one webhook and one Slack listener, and GitHub events on one repository. Waking one Loop by several of these at once is in early access for some Workspaces.

API

Every call needs an API key with the scope shown. See Authentication and scopes. The endpoints under /automations are the older form of Loops. Prefer the Loops under a Reason, which take every kind of wake.