> ## Documentation Index
> Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Run Loop on a schedule
> Configure a Loop automation to investigate your project on a schedule, control what it's allowed to change, and send results to Slack or a webhook.
A Loop automation is a scheduled Loop run with an instruction, a model, write tool permissions, and optional destinations. Use one for recurring work that shouldn't depend on someone starting and managing a chat.
For example:
* Find patterns in recent traces.
* Review cost or latency on a schedule.
* Check whether quality is degrading.
* Summarize recent errors.
* Review logs using the filters from a dashboard.
* Send a Slack or webhook digest after each run.
To find patterns specifically, [enable Patterns](/docs/observe/patterns/enable) instead. That creates a Loop automation with the right instruction and permissions already configured.
## Create a Loop automation
Go to ** Settings** > [** Automations**](https://www.braintrust.dev/app/~/configuration/automations), click **+ Automation**, and select **Loop**.
Each automation has its own instruction, frequency, model, query range, write permissions, and destinations.
| Field | What it controls |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name** | The automation name shown in ** Settings** > [** Automations**](https://www.braintrust.dev/app/~/configuration/automations). |
| **Description** | Optional context for what the automation is for. |
| **Active** | Available when editing a saved automation. See [Pause or delete an automation](#pause-or-delete-an-automation). |
| **Frequency** | How often the automation runs. Choose **Daily**, **Weekly**, **Interval**, or **Custom (cron)**. Daily and weekly schedules also include a run time and show the next scheduled run. Custom cron schedules use five fields: minute, hour, day of month, month, and day of week. |
| **Instruction** | What Loop should do during the run: what to look at, how deeply to look, and when to stop. |
| **Agent configuration** | The model, its reasoning effort, and whether the run uses Braintrust's built-in models or one of your own AI providers. An automation set to the built-in models stays on them once your model credits are exhausted, and its runs fail until the credits reset or you select a provider. See [Models and providers](/docs/loop/manage#models-and-providers). |
| **Default query range** | The time range Loop queries by default, such as 3 hours, 6 hours, 12 hours, 1 day, 3 days, 7 days, or a custom range. Each run inspects the full range, not only the traces created since the previous run. |
| **Write tool permissions** | What the run is permitted to change. See [Set write permissions](#write-tool-permissions). |
| **Destinations** | Slack channels or webhooks for run digests. See [Send results](#destinations). |
Cost depends on the model the automation uses and how much data each run inspects. Keep the instruction focused: a run that reads a broad set of traces costs more than one reviewing a narrower slice. Models served by your configured [AI providers](/docs/admin/ai-providers) bill to those providers. Runs on the built-in models draw down your monthly [model credits](/docs/plans-and-limits#model-credits) instead.
To run a saved automation immediately, open it and click **Run now**. Braintrust queues the run and shows a link to the Loop thread when it's ready.
### Examples
Two automations with different shapes: one reports and changes nothing, the other investigates and writes patterns.
Posts a cost breakdown to Slack every Monday morning.
| Field | Value |
| -------------------------- | ------------------------------------- |
| **Frequency** | Weekly, Mondays at 9:00 AM |
| **Default query range** | 7 days |
| **Write tool permissions** | None. The run only reads and reports. |
| **Destinations** | Send to Slack |
```text wrap Instruction theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
Create a weekly estimated-cost report for this project.
Periods:
- Use the automation's seven-day window as the current period.
- Compare it with the immediately preceding seven days.
- State both UTC date ranges in the report.
Cost by user:
- Query project logs separately for each period.
- Group by `span_attributes.created_by_user_id` and sum `metrics.estimated_cost`.
- Keep null creator IDs as `Unattributed`, and never guess a name.
Return only:
1. A Markdown table with columns `User`, `Past 7 days`, `Prior 7 days`, `Change`.
2. One sentence summarizing the total week-over-week change.
3. A short paragraph on which work drove the spend, based on the highest-cost
traces in the window. Describe the tasks, not the people.
```
Narrows pattern discovery to one concern, using an existing [facet](/docs/observe/topics/custom-facets) to choose which traces to investigate. Run this alongside the default **Pattern discovery** automation when a specific area deserves its own cadence.
| Field | Value |
| -------------------------- | -------------------------- |
| **Frequency** | Daily |
| **Default query range** | 7 days |
| **Write tool permissions** | Create and update patterns |
| **Destinations** | Optional |
```text wrap Instruction theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
Analyze recent project traces to find recurring failures within the existing
"Primary failure mode" facet's topic classifications.
Use the facet and its topic classifications only to select candidates. They are
noisy, and are not evidence by themselves.
Workflow:
1. Use the automation window.
2. Collect a sample of 100-200 facet occurrences, spread across the available
topic classifications rather than only the newest or largest cluster.
3. Cap the sample at two occurrences per root trace, and deduplicate repeated
facet runs and copies of the same underlying conversation.
4. For each candidate, inspect the compact context around the occurrence: the
user request, agent actions, tool results, and outcome.
5. Validate every proposed pattern against raw trace evidence. Reject any
hypothesis explained by explicit user direction, a permission or environment
block, or intentional fail-fast behavior.
Record a pattern only when it describes a specific recurring behavior, is
supported by at least three independent conversations, has a meaningful impact
and an actionable response, and includes short quotes and relevant span IDs.
```
The instruction does most of the work in both cases. To create reliable instructions:
* **Pin the time range.** Telling Loop to reuse the automation's window, rather than compute its own, keeps consecutive runs comparable.
* **Specify the output.** "Return only" and an explicit column list produce a digest that reads the same every week, which matters when results go to Slack.
* **Say what doesn't count.** Instructions like "never guess a name" or "reject any hypothesis explained by explicit user direction" close off the failure modes you'd otherwise find by reading a bad run.
Write the instruction as if briefing someone who will do the work once, without you there to answer questions. Say what to look at, how deeply, what to return, and when to stop.
In an interactive thread, actions that change something pause for your approval. A scheduled run has nobody to ask, so it relies on its **Write tool permissions** instead.
* Read-only tools never require approval, so a run can always inspect project data such as traces, existing patterns, experiments, and datasets.
* Automations created from the [** Patterns**](https://www.braintrust.dev/app/~/patterns) page can create and update pattern records by default. A pattern record can include trace evidence, monitor chart configurations, and recommendations for measuring the pattern later. Creating scorers, facets, or other project objects requires the corresponding write tools.
* To let a run create or modify other project objects, add the corresponding tools. The dropdown lists what each one permits.
Enabling a tool lets scheduled runs make that kind of change without asking. Choose only the tools the automation needs.
Allowing a run to create or update online scoring rules can start work that continues after the run ends. Online scoring rules score production traffic continuously and keep costing money until you stop them.
Objects a run creates are not linked back to any pattern it recorded. If a pattern's monitor chart measures a scorer or facet the run created, deleting that object stops new data from reaching the chart.
Send results
Every run's results are available in Braintrust on the automation's [**Past runs**](#review-past-runs) tab, and any patterns it records appear in the [** Patterns**](https://www.braintrust.dev/app/~/patterns) list. Add a destination when you also want each run pushed to your team.
Click **+ Destination** in the configuration panel, then choose **Send to webhook** or **Send to Slack**.
* **Slack.** Select a channel to post a text digest. This requires a [connected Slack workspace](/docs/admin/organizations#enable-slack-integration). Every message opens with the project name in bold on its own line. Use the destination's **Formatting prompt** to tell Loop how to format the rest of the message.
* **Webhook.** Enter a URL to send run results to an external service. Use the **Formatting prompt** to describe the JSON payload Loop should produce.
Destinations belong to automation runs. Patterns that Loop records during an interactive chat appear in the Patterns list but do not trigger Slack or webhook destinations.
## Review past runs
Each run creates a read-only thread recording the work Loop did. To find it, open the automation, select the **Past runs** tab, and select a run.
These threads stay with their automation and don't appear in the thread list on the [** Loop**](https://www.braintrust.dev/app/~/loop) page. They also can't be deleted the way an interactive thread can.
To ask follow-up questions from a run, select **Continue**. This forks the read-only transcript into a private, editable thread, which is the fastest way to work out why a run behaved the way it did.
## Pause or delete an automation
Pause an automation to stop its scheduled runs while keeping its configuration and history. Do this when you're tuning an instruction, controlling spend, or investigating a run that behaved unexpectedly. When you're ready, you can re-enable the automation.
To pause, open the automation and turn off **Active**. The rule then shows as **Paused** in ** Settings** > [** Automations**](https://www.braintrust.dev/app/~/configuration/automations). Turn **Active** back on to resume the schedule.
To remove an automation entirely, delete the rule from ** Settings** > [** Automations**](https://www.braintrust.dev/app/~/configuration/automations).
Deleting an automation is permanent. If you might want the automation again, pause it instead.
Neither pausing nor deleting an automation affects the objects its runs already created. Patterns, scorers, facets, and other objects a run produced remain in your project, and any online scoring rules a run created keep running until you stop them separately.
## Next steps
* [Enable Patterns](/docs/observe/patterns/enable) for scheduled pattern discovery.
* [Set up alerts](/docs/observe/alerts) for conditions you can already define, without an agent run.
* [What Loop can do](/docs/loop/capabilities) to decide what's worth automating.