> Documentation index: https://docs.beetl.io/llms.txt

# Automations

> Scheduled, observe-only checks on your data that return a finding, a report and the queries behind it.

Source: https://docs.beetl.io/automations/
Last updated: 2026-10-28

An automation is a recurring investigation you describe in plain language. On its schedule, Beetl
works through your datasets with read-only SQL and writes a Markdown report. Each run ends with a
finding, **Healthy** or **Needs attention**, and lists every query it ran, why it ran it, and the
result.

Automations only observe. A run can look up datasets and run read-only queries, but it cannot
change data, build or deploy a pipeline, or propose an action. See
[The agent trust boundary](https://docs.beetl.io/concepts/agent-trust-boundary).

Automations belong to the workspace rather than to the person who created them. Every user in the
tenant sees the same list and can open any run's report and evidence, even though query results are
otherwise private to their creator.

## Create and run an automation

Automations need AI in the tenant: managed AI, or your own key if a TenantAdmin has registered one.
If neither is available, **New automation** is disabled. See [AI in a tenant](https://docs.beetl.io/concepts/ai-settings).

    ### Describe the check [#describe-the-check]

    Open **Automations** in the sidebar and choose **New automation**. Give it a **Name** and fill in
    **Instructions** with what Beetl should check. **What should the report include?** is optional, for
    example "list the violating records grouped by country".

    ### Add starting queries (optional) [#add-starting-queries-optional]

    Under **Starting queries**, choose **Add query** to give Beetl named SQL to begin from. Turn on
    **Use previous runs** if the check should compare against earlier results, such as "did the count
    go up since last week".

    ### Pick a model and a schedule [#pick-a-model-and-a-schedule]

    The model chip and the reasoning-effort chip (Default, Low, Medium or High) work as they do in
    chat. Leaving the model unset uses the workspace default.

    Optionally pick a **report template** to render each completed run's findings as a PDF; see
    [Reading a report](#reading-a-report). Templates are shared across the workspace and are described
    in [Reports](https://docs.beetl.io/reports).

    Under **Schedule**, run it every hour, day, week or month at a time you choose, or open **Use an
    advanced cron expression**. Set the **Timezone** the schedule follows. A new automation starts out
    daily at 08:00 in your browser's timezone.

    ### Test it, then save [#test-it-then-save]

    **Test automation** runs the current, unsaved definition and shows the finding, the report and the
    investigation. A test leaves no run history, and its query results are not kept. When the result
    looks right, choose **Save automation**.

After saving, the automation's page has these actions:

* **Run now** starts a run immediately, even while the automation is paused. Only one run of an
  automation can be in progress at a time.
* **Pause** stops future scheduled runs, and **Resume** starts them again.
* **Edit** reopens the editor.

To delete an automation, open the actions menu on its row in the Automations list, choose
**Delete** and confirm. You can't delete an automation while a run is in progress.

Any user in the tenant, TenantAdmin or TenantUser, can create, edit, run, pause, resume and delete
automations.

## Writing a good goal

Give each automation one concern. "Active suppliers missing a VAT ID or payment terms" produces a
clear finding. A goal that also checks open orders and stock levels produces a long report with a
muddy verdict, so split separate concerns into separate automations.

Name the datasets and columns when you know them. Beetl can look them up, but every lookup spends
part of the run's budget (see [Limits](#limits)).

Say what **Needs attention** means, with a threshold. "Needs attention if more than 5 active
suppliers are missing a VAT ID, or if any supplier created this week is" gives a run something to
decide against. Without a threshold, the verdict is the model's judgment.

Add a starting query when you already know the SQL that answers the question. Beetl treats it as a
starting point and may adapt it or run other read-only queries, so describe the intent in the goal
as well.

Keep the goal short. A few sentences usually work better than a page of instructions, and wishes
about layout belong in **What should the report include?**.

## Reading a report

The automation's page shows the latest run first:

* The finding, Healthy or Needs attention.
* A summary of a sentence or two, which also appears on the Automations list.
* The findings: up to 20 items, each with a title, a detail and references to the evidence.
* The report in Markdown, shaped by your report instructions.
* **How Beetl investigated**, which lists each step with its purpose. For a query step, **View
  evidence** opens the SQL and the rows it returned.

If the automation has a report template, a completed run also shows its findings as a PDF, with a
PDF and Summary toggle on the run page and a per-page view. Choose **Render PDF** to produce it, or
**Retry render** if rendering failed. A run that did not complete, or an automation without a
template, has no PDF to render. PDFs are written to your object storage.

**Run history** lists earlier runs; open one to read its report and evidence.

If a run fails, its page gives the reason and says that no business conclusion was produced. The
last completed finding stays visible next to the failure, so a failed run never reads as Healthy. A
run also fails if it couldn't query any data, for example because the workspace has no queryable
datasets, or when the tenant's monthly AI credits run out.

Reports are kept with no time limit, but the query results they link to expire after 7 days. To
check a number in an older report, run the automation or the query again. See
[Query results](https://docs.beetl.io/concepts/query-results).

The Automations list shows each automation's status, its latest summary, its schedule and its next
run. Filter it by **Needs attention**, **Failed** or **Paused** to see what needs a look.

## Limits

| Limit                              | Value                                                          |
| ---------------------------------- | -------------------------------------------------------------- |
| Name                               | 255 characters                                                 |
| Instructions (the goal)            | 8,000 characters                                               |
| Report instructions                | 16,000 characters                                              |
| Starting queries                   | 20, with unique names and up to 64,000 SQL characters in total |
| Schedule                           | At most once every 15 minutes                                  |
| Investigation time                 | 5 minutes, then the run writes its report from what it found   |
| Tool calls per run                 | 32, counting every query, dataset lookup and previous-run read |
| Time per query                     | 60 seconds                                                     |
| Whole run                          | Marked failed after 7 minutes                                  |
| Runs in progress                   | 1 per automation                                               |
| Query results linked from a report | 7 days                                                         |

An advanced cron expression has 6 fields, starting with seconds: `0 30 7 * * Mon-Fri` runs at 07:30
on weekdays. Saving fails if the schedule would ever run twice within 15 minutes.

If a check needs more queries or time than this, split it into several automations, or compute the
heavy part in a [pipeline](https://docs.beetl.io/concepts/pipelines) and point the automation at its output dataset.

## Managing from chat and over MCP

The assistant in chat can create, update, run, pause, resume and delete automations. Deleting one
asks for your confirmation first.

An MCP client with a `write` key can do the same, and `create_automation` and `update_automation`
accept an optional `template`. A `read` key can list automations and read their runs, with their
findings and rendered PDF, using `list_automation_runs` and `get_automation_run`. See [Tool reference](https://docs.beetl.io/mcp/tool-reference) and [MCP setup](https://docs.beetl.io/mcp/setup).

## Notifications

Beetl does not send email, Slack or webhook notifications, so a Needs attention finding waits in
the app until someone looks. Check the Automations list with the **Needs attention** filter, or have
an MCP client poll `list_automation_runs` on a schedule and raise alerts in your own tools.

## Related

- [Runs](https://docs.beetl.io/concepts/runs-and-jobs): Where run history lives and how long it is kept.

- [AI in a tenant](https://docs.beetl.io/concepts/ai-settings): Managed AI, your own key, models and credits.

- [Query results](https://docs.beetl.io/concepts/query-results): The evidence behind a report and its 7-day expiry.