> ## Documentation Index
> Fetch the complete documentation index at: https://ara-90a60a07.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Loops

> Loops are standing work a Reason does on a schedule or when a webhook, GitHub event or Slack message wakes it. Create, run, pause and delete them.

A Loop is standing work a [Reason](https://ara-90a60a07.mintlify.site/docs/reasons.md) 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

| Wake | It runs when |
| - | - |
| Schedule | A time arrives: once, at a fixed interval, or on a cron expression |
| Webhook | Another service sends an event to the URL the Loop gives out |
| GitHub | An issue or pull request event happens in a connected repository |
| Slack | A message, mention, keyword or reaction appears in a channel the Reason's Slack app is in |

### Schedules

A schedule takes one of three forms:

| Form | Example |
| - | - |
| A one-time ISO 8601 time, with `Z` or an offset | `2026-12-01T09:00:00Z` |
| A fixed interval, 60 seconds at least | `every 30 minutes` |
| A cron expression | `0 9 * * 1-5` |

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](https://ara-90a60a07.mintlify.site/docs/github.md#connect-github), as `owner/name`, and one event. Its runs work in that repository.

| Event | Wakes on |
| - | - |
| `issue_opened` | A new issue |
| `issue_labeled` | A label added to an issue. Needs a `label` filter |
| `issue_closed` | An issue closed. Needs a `label` filter |
| `pr_opened` | A new pull request |
| `pr_reopened` | A pull request reopened |
| `pr_ready_for_review` | A draft marked ready for review |
| `pr_pushed` | New commits pushed to a pull request |
| `pr_closed` | A pull request closed, merged ones included |
| `pr_review_submitted` | A review submitted on a pull request |

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:

| Match | Wakes on |
| - | - |
| `message` | Any new message a person posts, top level or in a thread. This is the default |
| `mention` | A message that @mentions Reason's Slack app or names the Reason |
| `keyword` | A message containing any of the words you list |
| `reaction` | An emoji reaction: any of the emoji you list, or any emoji when you list none |

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](https://ara-90a60a07.mintlify.site/docs/slack.md).

### 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](https://ara-90a60a07.mintlify.site/docs/skills.md) 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:

```text theme={null}
Every weekday at 9:00 Oslo time, check the open pull requests in acme/web and tell me which ones are waiting on review.
```

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:

```bash theme={null}
reason routines add "Triage new issues" --schedule "0 9 * * 1-5"
reason routines add "Check the deploy" --schedule "every 2 hours" --reason NAME
reason routines add "Post the weekly summary" --schedule "0 9 * * 1" --timezone Europe/Oslo
reason routines                    # every Loop on your Reasons
reason routines run ID             # run one now
reason routines rm ID              # delete one
```

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](https://ara-90a60a07.mintlify.site/api-reference/loops/create-a-loop.md) takes a `prompt` and a `wake_on` list:

```bash theme={null}
curl -sS -X POST "https://api.reasonmachines.com/v3/organizations/$ORG_ID/reasons/$REASON_ID/loops" \
  -H "Authorization: Bearer $REASON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekday triage",
    "prompt": "Triage the issues opened since the last run.",
    "wake_on": [{ "schedule": "0 9 * * 1-5" }],
    "timezone": "Europe/Oslo"
  }'
```

## 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](https://ara-90a60a07.mintlify.site/docs/plans.md). 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](https://ara-90a60a07.mintlify.site/docs/build/auth-and-scopes.md).

| Do | Call | Scope |
| - | - | - |
| List a Reason's Loops | [`GET /v3/organizations/{orgId}/reasons/{reasonId}/loops`](https://ara-90a60a07.mintlify.site/api-reference/loops/list-a-reasons-loops) | `automations:read` |
| Create a Loop | [`POST .../reasons/{reasonId}/loops`](https://ara-90a60a07.mintlify.site/api-reference/loops/create-a-loop) | `automations:write` |
| Read one | [`GET .../loops/{loopId}`](https://ara-90a60a07.mintlify.site/api-reference/loops/retrieve-a-loop) | `automations:read` |
| Change, pause or resume one | [`PATCH .../loops/{loopId}`](https://ara-90a60a07.mintlify.site/api-reference/loops/update-a-loop) | `automations:write` |
| Run one now | [`POST .../loops/{loopId}/run`](https://ara-90a60a07.mintlify.site/api-reference/loops/run-a-loop-now) | `automations:write` |
| Delete one | [`DELETE .../loops/{loopId}`](https://ara-90a60a07.mintlify.site/api-reference/loops/delete-a-loop) | `automations:write` |
| Send a webhook event | [`POST /webhooks/automations/{publicToken}`](https://ara-90a60a07.mintlify.site/api-reference/loops/send-an-event-to-a-loop) | The Loop's webhook key |

The endpoints under `/automations` are the older form of Loops. Prefer the Loops under a Reason, which take every kind of wake.


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