trigger_refresh

Refreshes a refreshable dashboard immediately, instead of waiting for its schedule. Use it right after a pipeline finishes loading new rows.

Requires a paid plan, and the dashboard must already be refreshable.

It never returns the dashboard's data. What it does return depends on where the dashboard keeps its data:

• A dashboard that keeps its data with Dashies refreshes in the background. The call answers that the refresh was queued and returns before it runs, with no row count or duration. Follow it with get_refresh_status.
• A dashboard whose numbers are computed into the page refreshes during the call, and the receipt is metadata only: rows refreshed, duration, and whether the data changed.

Behaviour hints for clients: not read-only, not open-world.

Parameters

Parameter	Type	Required	Notes
slug	string	yes	Canonical slug of the dashboard to refresh now.
workspace	string	no	Slug of a workspace you belong to. Refreshes that workspace's dashboard with this slug. Omit to use the connection's authorized target.
scope	string	no	full (the default) re-runs the dashboard's data as usual. grants re-reads only the access rules of a dashboard that filters rows per viewer, and rewrites nothing else: the numbers stay exactly as they are and the data files are not touched. Use it when somebody's access changed and the new rules should take effect now rather than at the next scheduled refresh. It still refuses to publish if the data holds an access-rule value nobody is granted. On a dashboard that does not filter rows per viewer there is nothing to re-read, and it is refused.

Returns

Three different outcomes are all successes. Handle each, because two of them mean no refresh ran.

It ran (a dashboard whose numbers are computed into the page):

Refreshed "revenue-overview": 96 rows in 3120 ms.

When the recomputed data was identical to what was already published, one more sentence is appended: The data cube was unchanged since the last refresh.

It coalesced:

Did not start a new refresh of "revenue-overview" (status: active): a refresh is either already in flight or finished within the last minute. Use get_refresh_status to see the run, which surface started it, and whether it is running the current version.

The one sentence covers two different situations, because the receipt carries no field that separates them. A refresh already in flight means the numbers are still moving; one that finished within the last minute means they are fresh already. get_refresh_status is where that distinction lives.

It queued (a dashboard that keeps its data with Dashies):

Refresh of "revenue-overview" was queued and runs in the background, so this call returns no row count or duration. Follow it with get_refresh_status and wait_seconds: the phase reads updating while it runs, and says how it ended once it finishes.

The size of the dashboard has nothing to do with it: every dashboard that keeps its data with Dashies answers this way, a five-row one included, and the run is visible in get_refresh_status as updating from the moment this returns.

Errors

Condition	Text
Missing slug	slug is required: the canonical slug of the dashboard to refresh.
View-only in the workspace	You hold a view-only role in this workspace, so you cannot publish, change or refresh its dashboards. A workspace admin can change your role.
Not in the workspace at all	You are not a member of this workspace.
Your seat changed mid-call	You do not have permission to refresh dashboards in this workspace. Refreshing rewrites a dashboard's data, so it needs the same seat as republishing it.
The refresh service is unreachable	Could not reach the refresh service right now. Please try again in a moment.
An unclassified failure	trigger_refresh failed: <err>
No such dashboard	No dashboard found with slug "<slug>" in this workspace.
Unpaid workspace	Refreshing on demand requires a paid plan on this workspace. Only a workspace admin can change the plan.
Not refreshable	Dashboard "<slug>" is not configured for refresh (it has no connected data source).
Changed mid-refresh	Dashboard "<slug>" changed during refresh. Please retry.
Too many triggers	Too many refresh triggers right now. Wait about a minute and try again.
The refresh itself failed	Refresh failed for "<slug>": <error>

The unreachable case fails closed: it refuses rather than reporting a refresh it cannot confirm.

The two seat refusals come from the tool itself and name your role. The third is the refresh service's, which is deliberately reason-free: it only appears if your seat changes between the tool's check and the service's, or if something calls that service directly. All three mean the same thing to you.

Rate limited twice: 20 calls per user per minute at this tool, plus an authoritative budget on the refresh service, which produces the Too many refresh triggers right now. sentence rather than the generic one. That second budget is keyed on the WORKSPACE, so colleagues sharing one share a single allowance. See Rate limits.

Scope

A refresh needs a seat, not just membership. It re-runs the dashboard's SQL and rewrites its data, so it takes the same permission as republishing it: a view-only member is refused. That is the same rule the Run now button in the web app applies.

And the plan that matters is the workspace's, whatever plan you happen to be on yourself.

Check it worked

Read get_refresh_status and confirm a new run appears at the top of the history with a success status and a row count. That is the only confirmation that holds across all three success shapes, and it is the required step after a queued refresh. A success whose run line is marked PARTIAL updated some datasets and not others; the lines under it name the ones that failed.