Automations

Use an automation to run an analysis on a recurring schedule. It can refresh an existing Explore or create a new one from a prompt, then optionally send notebook output by email or Slack. A live schedule, a completed run, and a delivered message are three different things to check.

For setup, use Schedule and deliver an analysis. This page defines schedule, run, and delivery behavior. Environments, sessions and runs covers runtime ownership and interruption.

Definition and published state

An automation is a YAML definition at automations/<id>.yaml; the filename supplies its ID. The path is relative to the configured context root in Context files. For example, a context root of querio puts definitions at querio/automations/<id>.yaml. The scheduler reads canonical files under that root, not unpublished working-copy edits. A manual test does not prove scheduled discovery.

name: Daily notebook refresh
description: Refresh the selected notebook each weekday.
status: draft
createdBy: analyst@example.test
updatedAt: '2026-10-25T09:00:00Z'
trigger:
  type: cron
  cron: '0 9 * * 1-5'
  timezone: UTC
workflow:
  type: explore-sync
  conversationId: example-notebook
action: null

Only trigger.type: cron is recognized. A definition with only a top-level schedule field is not a current automation; there is no automatic migration of that older shape.

The scheduler reads canonical definitions, not unpublished working-copy edits. It refreshes schedules periodically, every minute by default. Publishing, unpublishing, or deleting a definition does not cancel a run already started. Deleting the definition does not delete its Explores or recorded runs. See Files and versions for canonical publication.

Cron and timezones

The simple builder offers hourly, daily, weekly, and monthly schedules. A new automation starts at 0 9 * * * in UTC. Five-field cron uses this order:

minute hour day-of-month month day-of-week

trigger.timezone controls scheduling. It can be UTC or an IANA timezone such as America/New_York. The builder displays the stored timezone but has no timezone picker. Its Next run preview does not apply that timezone, so check the cron and stored timezone to establish the intended local time.

Six-field expressions with seconds are accepted, but the simple builder can drop nonzero seconds when it reads and saves them. Publishing or unpublishing from the list also rewrites the definition through that builder representation. Use five-field cron if the schedule will make that round trip.

An invalid cron or timezone prevents the schedule from being installed. Missed times after an outage are not promised to replay, and scheduling has no exactly-once guarantee. Check Runs after an expected time.

Workflows and run ownership

Explore sync uses the notebook/session's datasource and query-variable configuration. Run a prompt needs a nonempty prompt, model, and at least one datasource to publish or test. Both workflows run without a delivery action: sync still refreshes its Explore, and a prompt run still creates one.

Platform-managed execution does not need an open browser tab. A scheduled sync can reuse an existing notebook session or reopen a closed saved session with its retained configuration. Do not assume a fresh environment on every run. Saved code, live Python values, stored outputs, and run results remain distinct; see Environments, sessions and runs.

Scheduled runs use the automation's creator metadata for attribution, with an existing run creator selected if that attribution cannot be resolved. Manual tests use the caller. Neither attribution nor automation ownership grants query access or selects a database credential. Queries need datasource permission and exactly one authorized credential for that datasource; see credential selection.

Draft, live, and Test run

Test run is not a dry run. It can refresh a notebook, create an Explore, send email, or post to Slack. Review destinations before testing. The Runs tab marks manual executions Test, separately from scheduled runs.

Execution state and concurrency

Runs lists executions newest first. A returned run ID confirms submission, not completion or delivery.

A second ordinary execution of the same session and run kind is rejected while matching work is active. This is not a global limit of one automation per execution server. Interactive editing and execution have their own readiness, ownership, and busy checks.

A timeout, connection failure, server error, or uncertain acknowledgement can leave a run Pending. Its reservation remains to prevent overlapping work. Inspect the existing run and Explore before testing again; an uncertain acknowledgement does not mean nothing ran.

Before another scheduled notebook run is admitted, matching earlier Running scheduled work older than two hours can be marked Failed with Scheduled run exceeded 2-hour timeout without a recorded outcome. This changes the run record; it does not prove an old computation or warehouse query stopped. It does not clear every pending run, manual test, or prompt run, and is not a universal two-hour execution limit.

Delivery actions and limits

An automation has one optional delivery action. The action settings are captured when a run is submitted; changing the definition later does not change that run's destination.

Delivery uses cells in the run result. If layout cells are selected, only selected cells present in that result are included; otherwise all result cells are used. The agent's chat reply is not included. With no renderable cell output, no automation email or Slack message is sent, even if the agent replied.

Email recipients are explicit addresses and are not limited to workspace members. Choose recipients and channels authorized to receive the rendered data. The delivered View in Querio link does not grant Explore access; recipients need their own permission to open it.

Delivery is separate from execution success

Execution is recorded before delivery is attempted. Delivery errors are logged and do not change a Completed run to Failed. Runs has no persisted delivery success state or receipt, so Completed does not prove a message arrived.

There is no exposed durable automatic redelivery queue. Slack can join a channel and retry a not_in_channel post, but that is not a general delivery guarantee. Before rerunning, inspect the Explore and destination: another Test run repeats analysis and can send duplicate output.

Permissions and recovery

Saving or removing automation definitions needs workspace file-write access. Listing runs and requesting a test use workspace read permission. These permissions are separate from Explore sharing, datasource access, and access to delivery destinations. A test can send real data, so check its recipients even when the caller has read permission.

For the setup and recovery procedure, use Schedule and deliver an analysis. For session interruption and cleanup, use Environments, sessions and runs.