GeezerVison is showing docs.cube.dev — Scheduled Tasks - Cube Documentation Scheduled Tasks let you run tasks on a schedule — or whenever you need them.
Save a natural-language prompt for the
agent and have Cube run it
automatically on a schedule or on demand. Each run produces a chat thread
you can open later to read the agent’s answer. You can also ask the agent to create a
scheduled task for you from any of your chats.
For example, you might schedule a task to “every weekday at 9am, summarize
yesterday’s signups, flag anything anomalous, and email me the results” and
review the summary each morning.
Scheduled Tasks are scoped to a deployment — each task belongs to the
deployment it was created in.
Where to find it
In the deployment sidebar, open Scheduled (the clock icon, below
Explore). The Tasks tab of the Scheduled page lists the
deployment’s tasks, and is searchable. Each row shows:
- Enable/disable toggle — the untitled first column; pauses or resumes the
task (see Managing tasks).
- Name and Description. A click on a row opens the task’s
detail page.
- Schedule — when the task runs, followed by its timezone, for example
“Daily at 9:00 AM UTC” or “Weekly on Monday at 9:00 AM America/New_York”, or
“Manual”.
- Condition — the task’s condition in plain
language, or “Every run” when it has none.
- Next run — how long until the next run, counted from your clock and
given in its largest unit, for example “in 25 minutes”, “in 7 hours”, or “in
15 days”, as on the
dashboard delivery
cards; a run whose time has passed reads “due now” or, for example, “due 3
hours ago”. Hovering it shows the line with the date and time of the run
under it, in your timezone and naming it. It reads “Paused” for a paused
task, “Manual” for a manual one, and “Not scheduled” for an enabled task
that has no next run.
- Notifications — where the task’s notifications go (see
Notifying people when a run finishes):
its channels, how many people and groups, and its Slack channels, for
example “Inbox, Email · 3 people, 1 group · #sales, #finance-alerts”, or
“Nobody is notified”.
- Last check — on a conditional task, the outcome of its last check, for
example “3 minutes ago, Count increased by 2.7%, notified”, or “Not checked
yet” before the first one; ”—” on a task with no condition. Only the task’s
creator sees what the check read; anyone else sees, for example, “3 minutes
ago, notified”. Hovering it shows the whole line and the date and time of
the check, and the task’s detail page tells the whole
check.
Click the Name, Description, or Schedule column header to sort the
list. The Schedule column sorts by frequency and time, as on the
Refreshes, deliveries and alerts
tab, with manual tasks last.
The Refreshes, deliveries and alerts tab lists the deployment’s
refreshes, dashboard deliveries, and alerts,
and the Report deliveries tab its
report deliveries; if you can use
only one of them, the page shows it without tabs.
Anatomy of a task
A task has these settings, all edited in the Settings panel of its
detail page:
- Name (required) — how the task appears in the list.
- Description (optional) — a short summary shown in the list.
- Instructions (required) — the natural-language prompt the agent runs on
each execution.
- Agent (optional) — the agent that runs the task. Deployment default
follows the deployment’s
default agent at run time; a
task created from chat keeps that chat’s agent unless you ask the agent for
another.
- Schedule — how often the task runs (see below).
- Enabled — a toggle to activate or pause a scheduled task.
- Notify — the people and groups to notify when a run finishes, and how:
Inbox, Email, and Slack channels, in any combination (see
Notifying people when a run finishes).
- How — Every time, or Alert on condition with a metric
condition that decides whether the agent runs at all (see
Conditional tasks).
On Deployment default, a task whose creator can’t use the default agent
falls back to Auto, or fails when Auto is turned off. A task whose picked agent is
deleted fails its runs until you pick another.
Schedule options
Scheduled Tasks use the same schedule editor as
dashboard deliveries,
offering these frequencies:
- Manual — no schedule; the task runs only when you trigger it with
Send now (Run now on a task that notifies nobody) or, on a
conditional task, Check condition.
- Hourly, Daily, Weekly (with a day of the week), and Monthly
(with a day of the month) — each with a time picker.
- Custom — a raw five-field cron expression. Its minute field must be a
single number, so it fires at most once an hour:
30 9 * * 1-5 (9:30 on
weekdays) works, while */15 * * * * is rejected.
A timezone selector (defaulting to your browser’s timezone) controls when
the schedule fires; it is stored per task, and the task’s schedule is shown
with it, for example “Daily at 9:00 AM UTC”.
Conditional tasks
Set How to Alert on condition in the task’s Settings to hear
from the agent only when a metric moves. A condition on a task works as an
alert does on a dashboard delivery, with the
same rules and the same words. Before the agent runs, Cube reads one measure,
with the creator’s data access, and checks the condition:
- Measure — the metric to watch.
- Time dimension and By (Day, Week, Month, Quarter, or Year) —
picking a measure fills in the first time dimension of its view, if it has
one. Clear it to watch the measure’s all-time total instead; By then
stays disabled.
- Condition — one of:
- is above or below — the value is above, is below, or is
equal to the Value you enter. With a time dimension, the value is
the last complete period’s; without one, the total.
- changes by — the last complete period increases by ≥,
decreases by ≥, or changes by ≥ (in either direction) the
Percent you enter, compared with the period before it.
- is unusual — the last complete period is outside the range of the
periods before it (their median ± 3 × median absolute deviation). It needs
at least 8 complete periods before the last one.
changes by and is unusual compare periods, so they’re unavailable
without a time dimension. Setting How back to Every time and saving
removes the condition. The period still in progress is never read: a
monthly condition checked in mid-September compares August with July.
The task notifies once each time the condition starts to hold:
- The agent runs the task’s Instructions in a new chat thread that opens
with the facts it found: the value read, what it was compared with, and the
periods. Ask follow-up questions in that thread as in any chat.
- The task’s recipients are notified
on the channels the task has on. The creator’s message is titled with the
task’s name and “condition met” and states the change, for example
“Revenue rose 7.2 % (Aug → Sep 2026), above your 5 % threshold”. The
message names the measure by the title picked in the task’s Settings, or
by its full name (such as
orders.revenue) on a task that has no title for
it. Everyone else, and each Slack channel, is told that the condition
started to hold, without the figures. The figures stay in the run’s chat
thread, which everyone the task is shared with can open (see
Managing tasks).
A task with a condition must notify someone: Inbox or Email on with at
least one person or group picked, or Slack on with at least one channel.
Until it does, Create (or, on an existing task, Update) in the task’s
Settings stays disabled and says why, and the agent refuses the save. The
Platform API refuses it too when the request sets the task’s notification
field; a request that leaves that field out is saved.
While the condition keeps holding, later checks send nothing. Once a check
finds it no longer holding, the next time it holds notifies again. Changing
the condition’s measure, time dimension, period, or rule, or pausing the
task, starts over: the next check that finds the condition holding notifies.
Editing only the name, instructions, or schedule doesn’t.
A check that finds the condition not holding, that can’t decide (for example,
the measure is no longer in the data model, the previous period was 0, so
there is no % change, or the task’s access to the data couldn’t be renewed, as
when its creator has been deactivated), or that can’t read the metric at all
(for example, the query fails) runs no agent, creates no thread, and sends
nothing. It doesn’t appear in History; the task’s
Last check shows what it read and why nothing was sent. A
check that can’t decide or can’t read the metric also leaves the condition’s
state as it was: on a task that has already notified, the next check that
finds the condition still holding sends nothing.
Every scheduled run of a conditional task checks the condition. A Manual
task’s condition is checked only when its creator, an admin, or a role granting
Manage all scheduled tasks presses Check condition, which checks it
right away, exactly as a scheduled run would. The explainer under How in the
task’s Settings says so as the Condition line does:
“when you press Check condition” for the task’s creator, and “when its owner or
an admin presses Check condition” for anyone else. Send now skips the
check: it always runs the agent and leaves the condition’s state as it was.
Limits
Each user can have up to 20 active tasks across all of the account’s
deployments, where active means scheduled and enabled. Manual and paused
tasks don’t count toward this limit. At the limit, anything that would make
a task active fails: creating a scheduled task, resuming a paused one, or
adding a schedule to a Manual task. Pause or delete another task first,
or keep the new one Manual.
The Scheduled tasks tab lists one deployment’s tasks, so active tasks you
created in other deployments count toward the limit without appearing there.
Check the Scheduled page of each deployment you work in to find them.
Managing tasks
A task is visible only to its creator, to admins, to roles granting View all
scheduled tasks or Manage all scheduled tasks on the deployment, and to
the people and groups it’s shared with. The creator, an admin, or a role granting Manage all scheduled tasks shares it with the Share
button on its detail page. Sharing is view-only: the people it’s shared with
see the task, its schedule, and its run history, and its detail page shows
a View only tag in place of its actions and its settings with no
Update button, none of them editable. Creating a task needs the
Create scheduled tasks
permission,
which every built-in role grants. Users without it, for example those whose
only role is a custom role that leaves it out, get no Create scheduled task button, and
the agent and the Platform API refuse to create a task for them; tasks they
already created stay theirs to manage. Only a task’s creator, a user with
the Admin role, or a
user whose role grants Manage all scheduled tasks on the deployment (see
custom roles)
can edit, pause, run, check, share, or delete it, because every run executes as
the creator (see Reading the output).
That exception carries the creator’s data access with it: an admin or a
Manage all scheduled tasks holder who edits another user’s task changes what runs under that user’s access. A run’s chat
thread belongs to the task’s creator, and only the creator, admins, users with
the Access chat history
permission, people the thread
itself is shared with, and the people and groups the task is shared with can
open it. For anyone the task is shared with, the thread is view-only.
From the list, you can:
- Create a new task with Create scheduled task. It opens a Create scheduled task
page with empty settings. If you can use
Analytics Chat, the agent chat sits
beside them, and a message asking the agent to explain scheduled tasks and
interview you about what the task should do and when it should run is sent
for you. Answer the agent and it creates the task: the page becomes the new
task’s detail page, with the same chat still open. Or
fill in the settings yourself and press Create: the page becomes the new
task’s detail page beside a new, empty chat, and the set-up conversation
stays in the chat’s history.
- Open a task by clicking its row, to change it on its
detail page.
- Enable / Pause a scheduled task with the switch at the start of its row:
a paused task stops running on its schedule, and its Next run reads
“Paused”. A manual task’s switch is off and disabled, because a manual task
runs only when started by hand. While the change saves, the switch is
disabled; if it fails, an error message appears and the switch keeps its
previous state. A task shared with you has no switch.
- Send now — trigger a one-off run immediately and notify the task’s
recipients. This works for both manual and scheduled tasks. A task that
notifies nobody offers Run now instead, which runs it the same way.
Triggering a run shows a toast with a View link straight to the run’s
chat thread, and the thread appears in the Recent chats sidebar
immediately. On a conditional task, Send now runs
the agent without checking the condition.
- Check condition — on a conditional task, check the condition right
away. A Check started toast appears, and the result shows on the task’s
detail page.
- Delete a task. Deleting removes its schedule and stops all future runs.
Task detail page
Clicking a task in the list opens its detail page. The header shows a
breadcrumb back to Scheduled Tasks and the task name, along with Share,
Delete (trash), and a primary Send now button (Run now on a task
that notifies nobody). A conditional task also has a Check condition
button. On a conditional task, hovering Send now shows “Sends now without
checking the condition.”, and hovering Check condition shows “Checks the
condition now; sends only if it starts to hold.” On a narrow window, Share,
Check condition, and Send now show only their icons; hovering one shows
its name, followed on a conditional task by the same hint.
The page is in three parts, side by side: the task’s history on the left, its
Settings next to it, and, if you can use
Analytics Chat, the agent chat on the
right. On a narrow window, the history sits above the settings.
The left part shows the task’s description and a status tag (Manual,
Active, or Paused), then:
- Condition — on a conditional task only, above History: the
condition in plain language (for example, “Count changes by ≥ 5 % vs the
previous month”), then, on a line of its own, when it is checked. On a
scheduled task, that line says each scheduled run checks the condition
first and runs the agent only when it holds; on a Manual task, that the
condition is checked only when Check condition is pressed, by you or, on a
task you didn’t create, by its owner, an admin, or a role granting
Manage all scheduled tasks. Its Last check follows.
- History — the task’s runs, newest first. Each entry is a timestamped
link that opens that run’s chat thread, if you can
access it. Currently-executing runs
show a Running tag, and failed runs a Failed tag. The list shows
the latest 50 runs; a “Showing the latest 50 runs” note appears once the
cap is hit.
The Last check shows when the last check ran, its result (Condition not
met, Condition met — notified, Still holding — already notified,
Could not check, or Check failed), the value it read with the
comparison it made, and, when nothing was sent, why. On a task that notifies
nobody when its condition holds, for example one created through the Platform
API without a notification field, the two results of a check that finds it
holding read
Condition met and Still holding. While a check runs, it reads
Checking…. After a check that finds the condition starting to hold, the
agent run it started appears in History on the same page. The check reads
the metric with the creator’s data access, so only the creator sees the values
it read and the error behind a Check failed. Anyone else who can open the
task, an admin included, sees when it ran, its result, and why nothing was
sent, for example “The metric could not be read. Nothing sent.”
Changing a task’s settings
The Settings panel holds every setting of the task,
each showing its saved value. Update stays disabled until you change one;
pressing it saves only the settings you changed and shows “Scheduled task
updated”. Name and Instructions are required, and a condition that
isn’t complete keeps Update disabled and shows why.
Changing a task with the agent
The chat beside the settings works on the task on screen: every message you
send carries it, shown as a chip with the task’s name in the bottom row of the
message box, beside the agent picker. A name too long for the chip is cut;
hover the chip to read it whole. In a chat dragged narrow, the chip shrinks to
its clock icon, which still shows the name on hover. Ask in plain language,
for example “run it every day at 8:00 instead” or “tell me only when
monthly orders change by 5% or more”, and the agent changes this task. The
Settings panel shows the change without a reload.
Changes you haven’t saved in the panel stay as you typed them when the agent
changes the task, and Update stays enabled. Since Update saves only
the settings you changed, it doesn’t undo a change the agent made to another
setting.
Hide chat and Show chat in the header hide and show the chat; on a
narrow window, Show chat opens it over the page.
Reading the output
Each run creates a chat thread containing the agent’s response. Open the
thread in Analytics Chat to read the
full answer, ask follow-up questions, or
save results to a Workbook.
Scheduled-run threads are marked in the Recent chats sidebar with a clock
icon (hover over it to see the “Scheduled task” tooltip).
A run shows as Running while it executes, then completes or fails. A
failed run’s thread shows a failure notice instead of an empty thread.
A run’s thread carries no memory of earlier runs, so write the
Instructions as a complete request rather than a follow-up to the last
run.
The task runs headlessly under the security context of the user who created
it, so it sees exactly the data that user can access.
Notifying people when a run finishes
The Notify section of the task’s Settings decides who hears about a
finished run, and how:
- People and groups — any workspace users and user groups, picked from
the same search as the Share dialog. A group is expanded to its members
when the run finishes, so people who join it later are notified too. A
person picked directly and through a group is notified once.
- Send by — Inbox (an inbox notification), Email,
and Slack, in any combination. Inbox and Email go to every
person and group picked above. With Slack on, pick one or more channels:
each gets one post. If Slack isn’t connected to the workspace, the
Settings panel offers to connect it. Inbox is unavailable when the
inbox is off for the workspace, and a task saved with it on then sends no
inbox notifications but still sends its other channels.
A new task starts with you picked and Inbox on, so it notifies you the way
it did before; you can remove yourself. With every channel off, nobody is
notified, and the panel says so.
Each notification carries the task name, whether the run succeeded, the start
of the agent’s answer, and a link that opens the run. Each Slack post carries
the same answer and link. Saving a task with a newly picked person or group
shares the task with them, view-only, so the link opens the run for them,
whether they were picked in the task’s Settings, by the agent, or through
the Platform API. Removing them from Notify leaves the share in place;
remove it in the Share dialog. Besides the creator, a run notifies only
people who can open the task (admins, and anyone it’s shared with directly,
through a group, or with the whole organization) and read its deployment. A
picked person fails that in two ways: their share was removed in the Share
dialog after they were picked (saving the task again doesn’t share it back;
remove them from Notify and pick them again), or they can’t read the
deployment. The run skips them, and the Settings panel marks them No
access: won’t be notified in both cases. It marks a picked group the same
way when the task isn’t shared with that group or with the whole organization.
Deactivated users and people outside the workspace get nothing.
Notifications go to the task’s recipients, whoever runs the task: an admin or
a user with Manage all scheduled tasks who edits or runs it is notified
only if they are a recipient.
Each task email has an unsubscribe link. Unsubscribing stops that person’s
emails from this task, scheduled runs included, until the task’s creator picks
them again directly.
A failed run notifies only the task’s creator, if they are among the task’s
recipients, on the task’s Inbox and Email channels; other recipients
and Slack channels get nothing. Notifications apply to both scheduled runs and
Send now. On a conditional task, a check that runs no
agent sends nothing. See Inbox for what an
inbox notification shows.
A task that you create with the agent or the Platform API notifies nobody,
unless you ask for it: for example, “every Monday summarize sales, email it
to the Finance group and [email protected], and post it in #sales.” The agent
names people by email and groups by name. Channels belong to the whole task,
as in the Settings panel: asking the agent to notify one more person by
inbox turns Inbox on for everyone the task notifies, and the agent tells
you so. With the Platform API, set the task’s notification field.
What the agent can do in a scheduled run
Beyond querying the semantic model, the agent in a scheduled run can:
- Send email to workspace members — for example, “summarize yesterday’s
signups and email the summary to me.” This requires the agent email tool
to be enabled for the workspace; recipients are restricted to workspace
members.
- Use web search.
- Create and update reports, workbooks, and dashboards, using the task
creator’s permissions.
- Work with the data model — for example, “review last week’s slow
queries and propose pre-aggregations for them.” The agent can read the
data model and query history, edit model files, and commit the changes to
its own dev branch. This requires the
task’s creator to have the Edit data model or Edit data model on dev
branches permission.
- Query data sources with SQL, if the task’s creator has the Access SQL
Runner permission.
A scheduled run never publishes changes. It can’t merge to the main
branch, switch your active branch, or build pre-aggregations. To apply its
changes, review the branch it committed to and merge it yourself.
Managing tasks from chat
You can also create and manage Scheduled Tasks conversationally in
Analytics Chat — from any chat, not
just the one beside a task on its detail page. Ask the
agent to schedule, update, list, or delete tasks in plain language — for
example, “schedule a daily summary of yesterday’s signups at 9am” or
“list my scheduled tasks.” When the agent opens a task in the chat’s side
panel, its pencil button opens the task’s detail page with that chat beside
it. An alert on a chart of a published
dashboard is not a task: it belongs to a dashboard delivery of that dashboard,
and the agent doesn’t create a task for it.
The agent’s actions render in the chat as labeled steps with a clock icon —
“Creating scheduled task…” / “Created scheduled task”, “Listed
scheduled tasks”, “Updated scheduled task”, and “Deleted scheduled
task”.
The agent manages task definitions: when listing tasks, it can report each
task’s id, name, description, schedule, timezone, enabled state, next run
time, who it notifies and how, agent, and condition with its last check
(the check’s values and error text only to the task’s creator). It can also
add, change, or remove a task’s condition — for
example, “tell me when monthly orders change by 5% or more” — and pick the
agent a task runs on, or set it back to Deployment default. Some agents can
also Send now or Check condition on a task when you ask for it now, for
example “send the Revenue task now”, and tell you what came of it. On a
deployment with more than 50 agents, the agent sees only 50 of them and says
so; pick any other in the task’s Settings. A task’s run history lives on
its detail page. The agent follows the same
limits and permissions as the Scheduled page, and a scheduled
run can’t create or change tasks itself.
Managing tasks with the Platform API
You can also create, update, pause, run, and delete Scheduled Tasks from
scripts and CI with the Platform API (by
default, only admins can
create API keys). Its
Scheduled Tasks endpoints follow the same limits and
permissions as the Scheduled page. A task’s
notification field holds its
recipients and channels: channels
(inbox, email, slack), userIds, groupIds, and slackChannels, with
at most 1,000 users, 200 groups, and 50 Slack channels. An unknown user or
group id is refused. The older notificationEnabled field is
deprecated: it reads whether the creator gets an inbox notification, and
writing it adds or removes that. A task’s optional
condition field holds its condition (null on an
update removes it), and lastConditionCheck holds its latest check, whose
values and error text are returned only to the task’s creator. See the
API reference for the
endpoints, fields, and responses. |