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

# Loops

> Start coding sessions in a factory from GitHub events, schedules, webhooks or by hand.

Beta

> [!NOTE]
>
> **Agent Sessions** is in private preview. The feature is enabled per workspace by the **Orq.ai** team and the API is not part of the public SDKs yet. Behavior and field names can still change.

A loop belongs to a factory and starts a coding session for every run. Manage loops under **Factories** > the factory > **Loops**.

## Configuration

| Field | Purpose |
| - | - |
| `model` | Model of the coding agent. `reasoning_effort` is optional. |
| `system_instructions` | System instructions of the coding agent. |
| `instructions` | First message of every run. May use `{{event.*}}` placeholders from the trigger payload, and mention up to 8 of the factory's agents as `@agent[<agent_id>]`: each run can delegate to them as sub-agents, and they read as `@<agent name>`. Agents are read at every run, so a deleted or archived agent fails that run, and so does an agent that gained skills, MCP gateways or plugins since the loop was saved. |
| `skill_ids`, `mcp_gateway_ids`, `plugin_ids` | Skills, MCP gateways and plugins available to every run. |
| `repositories` | Repositories cloned into the run's workspace. Each is a fixed pick and cannot use `{{event.*}}` placeholders. Up to 7. |
| `event_repository` | Access (`read` or `write`, `read` by default) and trust of the repository an event names. Not trusted unless `trusted` is `true`. |
| `runner_id` | Saved runner of the factory every run starts from: its machine size, repositories, vaults, install script and snapshot. The loop's `repositories` and the event repository are added to the runner's. Empty uses the factory's default environment. |
| `metadata` | Up to 13 key-value pairs, values up to 512 characters, may use `{{event.*}}`. Stamped on the run's session. |
| `status` | `active`, `paused` or `archived`. |

## Triggers

A loop has up to 10 triggers and any of them starts a run. A loop can have none.

* **GitHub events**: an event of a connected GitHub source, optionally scoped (for example to a repository) and filtered by conditions on the event payload, such as `author_association`. Events caused by the factory's own GitHub App are ignored unless `include_app_events` is set.
* **Schedules**: hourly, daily, weekly or monthly, in an IANA time zone (UTC by default), with an optional end time.
* **Webhooks**: `POST` requests to the trigger's URL. The secret goes in the `X-Webhook-Secret` header or the `?secret=` query parameter, and is shown once when the trigger is created or rotated. Other methods are not routed, and a request whose conditions do not match is accepted and ignored.
* **Manual**: any active loop can be run by hand, with or without triggers. The run has `trigger_id` `manual` and the optional input is available as `{{event.input}}`. A paused or archived loop cannot be run by hand.

A run started by an event from a connected repository also clones that repository, first in the run's workspace and through the trigger's connection, with the loop's `event_repository` settings. A fixed repository that names the same repository takes its place. The run fails with `the event names no repository` when the event carries none. Schedule, webhook and manual runs clone only the fixed repositories.

An archived factory stops all of its loops from firing.

## Limits

Server defaults, not editable in the UI.

| Limit | Default | Behavior |
| - | - | - |
| `max_concurrent_runs` | `1` | Extra runs queue and start in order as earlier runs finish. |
| `max_invocations_per_hour` | `20` | Firings above the cap in a rolling hour are recorded as skipped with `rate_limited`. |
| `max_runtime_seconds` | 24 hours | Lifetime of each run's session. |

## Runs

Every firing is recorded as a run with a status: `queued`, `running`, `completed`, `failed` or `skipped`. A skipped run has no session and a `skip_reason`:

| Reason | Meaning |
| - | - |
| `paused` | The loop was paused. |
| `archived` | The loop was archived. |
| `rate_limited` | The hourly firing cap was reached. |
| `factory_archived` | The factory was archived. |

The **Sessions** tab of a loop lists its runs with their event, status and linked session.

## Templates

**Loops** offers a gallery of predefined templates. Choosing one prefills a new loop with its triggers, instructions and system instructions. Skills and MCP gateways are workspace-specific and stay empty. Trigger connections and repository connections are seeded with your first active connection of the provider. An event template works on the repository its event names and adds no repository row, while a schedule or webhook template that works on GitHub adds an empty repository row that has to be picked before saving. A template whose trigger needs a provider that is not connected asks to connect it first.

## API

| Method and path | Purpose |
| - | - |
| `POST /v3/factories/{factory_id}/loops` | Create a loop. Trigger ids are assigned by the server. |
| `GET /v3/factories/{factory_id}/loops` | List the loops of a factory. |
| `GET /v3/factories/{factory_id}/loops/trigger-catalog` | List trigger sources, events and payload fields. |
| `GET /v3/factories/{factory_id}/loops/templates` | List loop templates. |
| `GET /v2/loops/{loop_id}` | Get a loop. |
| `PUT /v2/loops/{loop_id}` | Replace a loop. |
| `POST /v2/loops/{loop_id}/status` | Set the loop to active, paused or archived. |
| `DELETE /v2/loops/{loop_id}` | Delete a loop. |
| `POST /v2/loops/{loop_id}/runs` | Run a loop by hand with an optional `input`. |
| `GET /v2/loops/{loop_id}/runs` | List runs. |
| `POST /v2/loops/{loop_id}/triggers/{trigger_id}/secret` | Rotate a webhook trigger's secret. |


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