Automations
What they are, what they do not do.
An Automation is a recurring, observe-only investigation. You write a goal in plain language, pick a schedule, and Beetl reports what it found. It reads your data, runs SQL, and writes a Markdown report with the evidence behind every step. It never changes anything.
An Automation cannot tell you anything
There is no outbound notification path anywhere in the server. No email, no Slack, no webhook.
An Automation that goes needs_attention notifies nobody. Someone has to open Beetl and look at
the Automations list. Plan for that before you make a business control depend on one.
How one works
You answer a single question: what should Beetl check? Optionally you add Markdown instructions for how the report should read, and named starting SQL queries to point the investigation at the right tables.
The starting queries are guidance, not a query plan. The runtime may adapt them, inspect the dataset catalog first, or run other read-only queries instead. Every run records the SQL it actually executed and links the durable result artifacts as evidence, so a report is checkable rather than merely readable.
Test before you save. Running an unsaved definition returns the finding, the report and the full investigation, then deletes its temporary results and session. No stable identity means no history, so a test costs nothing.
Observe-only, by construction
The runtime for an Automation has a read ceiling. Write-scoped tools are not offered to it at all, so an Automation cannot build a pipeline, deploy anything, or modify a dataset. There is no action-proposal or approval flow either. It reports, and that is the whole contract.
Workspace-owned, not creator-owned
An Automation belongs to the workspace, not to the person who wrote it. The detail page carries a Workspace badge. This is deliberate: a recurring business control should survive its author leaving the company.
Everything else in Beetl stays creator-scoped, including chat sessions, query results and API keys. Automations are the first shared object.
The flip side is that there is no role gate on them. Any authenticated user in the tenant can create, edit, pause, run and delete a workspace-owned Automation.
Reading a result
Three state axes are kept separate on purpose, so a runtime failure can never be mistaken for a business conclusion.
| Axis | Values |
|---|---|
| Lifecycle | active, paused |
| Run execution | scheduled, running, completed, failed |
| Finding | clear (Healthy), needs_attention (Needs attention) |
A completed run returns a fixed envelope of finding, summary and report, constrained by the model's native JSON response schema and re-parsed by the server as a boundary guard. Invalid output fails the run rather than triggering a repair turn. When the newest run fails, the last good finding stays visible.
More detail on Reading a report.
Limits
| Limit | Value |
|---|---|
| Goal length | 8,000 characters |
| Report instructions | 16,000 characters |
| Named starting queries | 20, with 64,000 SQL characters in total |
| Schedule | 6-field cron plus an IANA timezone |
| Minimum interval | 15 minutes |
| Previous runs visible to the model | The 10 most recent finalized runs |
| Previous-run report fed back in | Truncated at 24,000 characters |
Schedule validation walks 1,000 upcoming occurrences and rejects anything more frequent than the 15-minute floor or with no future occurrence at all. Missed intervals are coalesced rather than replayed, so a paused platform does not produce a burst of catch-up runs.
read_previous_run returns the previous report only. The conversation transcript is no longer fed to the model, though it stays durable and readable in the UI.
What you should know before relying on this
- Reports outlive their evidence. The report persists, but the durable query results it links to expire on the normal 7-day clock. An older report's evidence links go dead while the report itself stays.
- No programmatic read. The run-history tools are deliberately not exposed over MCP, so there is no way to pull findings into your own system. Combined with the missing notification path, Beetl's UI is the only place a finding exists.
- No retention or quota policy for automation runs, sessions or evidence.
- No templates for common master-data checks such as missing required fields or duplicate identifiers.
- No rollup view. Answering "what is red this morning" means filtering the list page client-side.
- Automations do not appear on the Data Landscape graph, cannot be tagged, and get no generated wiki document.
In this section
| Page | What it covers |
|---|---|
| Writing a goal | Plain language in, a scheduled investigation out. |
| Reading a report | The finding and summary envelope. |
| Limits | Goal length, named queries, and evidence expiry. |