> ## 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.

# Enable Patterns

> Turn on pattern discovery for a project, choose where results are delivered, and tune the schedule and scope of the Loop automation behind it.

Enable Patterns to schedule a [Loop automation](/docs/loop/automations) that investigates your project traces and records recurring problems and trends.

## Before you start

To enable Patterns, you need:

* **Project traces.** Patterns analyzes your project logs. If your project has no logs, [log traces](/docs/instrument) first.
* **Model access.** Patterns uses [Loop's models](/docs/loop#choose-a-provider-and-model). Built-in models require no provider setup and use your organization's monthly [model credits](/docs/plans-and-limits#model-credits). On Starter, they [require](/docs/admin/ai-providers#requirements) an organization owner with a work email address or a payment method on file. To use your own key or continue after credits run out, configure an OpenAI-compatible [AI provider](/docs/admin/ai-providers).
* **Permission to create project automations.** Members of the **Owners** and **Engineers** [permission groups](/docs/admin/access-control#built-in-permission-groups) have this permission by default.
* **The Loop runtime on self-hosted AWS deployments.** Runs fail until you [enable the Loop runtime](/docs/admin/self-hosting/configure/loop-runtime) in your data plane.

To configure providers or enable built-in models, you must belong to the **Owners** [permission group](/docs/admin/access-control) or a custom permission group with the **Manage settings** organization permission. Otherwise, ask an organization owner or administrator.

<AccordionGroup>
  <Accordion title="How Patterns selects a provider">
    * When built-in models are available, Patterns selects them automatically. On Enterprise, you can choose a compatible configured provider instead.
    * When built-in models are unavailable, Patterns selects your only compatible configured provider automatically. If you have several, you choose one.

    You can change the provider after setup in the [automation's configuration](#tune-the-automation).
  </Accordion>

  <Accordion title="Set up Slack notifications (optional)">
    To receive notifications, [connect a Slack workspace](/docs/admin/organizations#enable-slack-integration), then choose a workspace and channel during Patterns setup. You can also [add a notification destination](/docs/loop/automations#destinations) after setup.
  </Accordion>
</AccordionGroup>

## Enable pattern discovery

1. Go to [**<Icon icon="scan-search" /> Patterns**](https://www.braintrust.dev/app/~/patterns). The **Get started with Patterns** panel guides you through setup.
2. If the panel shows **Add provider**, configure an organization-level AI provider before continuing. See [Common issues](#common-issues) for provider and model credit requirements.
3. If the panel shows **Continue**, click it to open **Configure Patterns**. Choose a provider under **Select a model provider** if that field appears. If a Slack workspace is connected, you can also choose a workspace and channel for notifications.
4. Click **Enable Patterns**. If no provider choice or Slack configuration is needed, this button appears directly on the initial panel.

Braintrust creates a **Pattern discovery** automation with these defaults:

* **Schedule:** Daily at 9:00 AM in your default timezone.
* **Query range:** The last 30 days.
* **Permissions:** Create and update patterns.
* **Instruction:** A default prompt telling Loop what to look for. You can [edit it](#tune-the-automation).

The first run is queued immediately. The page shows **Analyzing traces...** while a run is in progress, and patterns appear as it finishes.

<Note>
  If a project has no patterns yet and no run is in progress, click **Analyze patterns** to queue another run without waiting for the schedule.
</Note>

## Tune the automation

You can change the automation's instruction, schedule, model, query range, and destinations.

To edit it, either click **Settings** on the [**<Icon icon="scan-search" /> Patterns**](https://www.braintrust.dev/app/~/patterns) page and select the automation, or go to **<Icon icon="settings-2" /> Settings** > [**<Icon icon="radio" /> Automations**](https://www.braintrust.dev/app/~/configuration/automations).

Start with these fields:

* **Frequency.** How often the run happens. A project with steady traffic rarely needs more than daily.
* **Default query range.** Each run inspects the full range, including traces inspected by previous runs. A wider range costs more.
* **Instruction.** What Loop should look at, how deeply, and when to stop.
* **Destinations.** Where run digests are delivered.

Click **Save** to apply your changes. For all fields, see [Create a Loop automation](/docs/loop/automations#create-a-loop-automation).

When you [resume a paused automation](/docs/loop/automations#pause-or-delete-an-automation), Patterns keeps its saved model and provider unless you select a different one.

<Note>
  Keep the instruction framed around finding or updating patterns, even when you narrow the automation to one concern. An instruction that asks for a summary produces a summary, not a pattern record.
</Note>

## Add a focused automation

Add an automation when a concern needs its own scope or schedule, such as tool-call errors, cost growth, latency for specific customers, or quality regressions. All automations write to the same patterns list.

Select **Settings** > **New automation** on the [**<Icon icon="scan-search" /> Patterns**](https://www.braintrust.dev/app/~/patterns) page. Review the prefilled automation, adjust its settings, and click **Create**.

## Common issues

<AccordionGroup>
  <Accordion title="Setup asks you to add a provider">
    When neither a compatible organization-level AI provider nor usable [built-in models](/docs/admin/ai-providers#available-models) are available, the setup panel shows **Add provider** instead of **Enable Patterns**. Click **Add provider** to configure a provider without leaving setup.

    * **Built-in models are disabled.** To use them instead of your own provider, enable them in **<Icon icon="settings-2" /> Settings** > [**<Icon icon="sparkle" /> AI providers**](https://www.braintrust.dev/app/~/configuration/org/secrets). Your organization must meet the [built-in model requirements](/docs/admin/ai-providers#requirements).
    * **Your model credits are exhausted.** Add your own provider key with **Add provider**, or select **Upgrade** to raise your plan's limits. See [model credits](/docs/plans-and-limits#model-credits) for how usage is counted.
  </Accordion>

  <Accordion title="An automation error appears on the Patterns page">
    If the latest run of an enabled Patterns automation fails, the page header shows <Icon icon="triangle-alert" /> **Last run failed**:

    1. Click it to see automation names and error messages.
    2. Select an entry to open the failed run in Loop in a new tab.

    Automation errors can also appear in a banner below the page header. Enabling Patterns does not test your provider's connection before creating the automation.

    For provider errors, check that the configured credentials are valid and the provider can serve the automation's selected model. After resolving the error, [run the automation again](/docs/loop/automations#create-a-loop-automation) with <Icon icon="play" /> **Run now**.
  </Accordion>

  <Accordion title="A run finished but recorded nothing">
    Loop records a pattern only when it can attach supporting evidence, so a quiet run is a normal outcome rather than a failure.

    Open the automation's **Past runs** tab and select the run to read its transcript. Select <Icon icon="git-fork" /> **Continue** to fork an editable thread and ask Loop why it recorded nothing.

    If runs are consistently empty, the query range or the instruction is usually too narrow.
  </Accordion>

  <Accordion title="Patterns aren't notifying Slack">
    Destinations belong to automation runs. Patterns that Loop records during an interactive chat appear in the list but do not trigger Slack or webhook destinations.

    Confirm the destination is configured on the automation itself, under **Destinations** in the configuration panel, and that the [Slack workspace is still connected](/docs/admin/organizations#enable-slack-integration).
  </Accordion>

  <Accordion title="The page asks you to upgrade your data plane">
    Patterns requires data plane v2.13 or later. To upgrade, see the [routine upgrade guide](/docs/admin/self-hosting/upgrade/routine).
  </Accordion>
</AccordionGroup>

## Next steps

* [Review and act on patterns](/docs/observe/patterns/review) once the first run finishes.
* [Run Loop on a schedule](/docs/loop/automations) to configure destinations, write permissions, and past runs in depth.
* [Set up alerts](/docs/observe/alerts) for conditions you already know how to detect.
* [Active observability for coding agents](/docs/cookbook/recipes/CodingAgentInsights) to find recurring problems in coding-agent sessions with Topics facets and a Loop automation.