trigger_refresh
Refresh a dashboard now instead of waiting for its schedule. Parameters, the three success shapes, errors, and why it is personal only.
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.
The receipt is metadata only: rows refreshed, duration, and whether the data changed. It never returns the dashboard's data.
Behaviour hints for clients: not read-only, not open-world.
Parameters
| Parameter | Type | Required | Notes |
|---|---|---|---|
slug | string | yes | Canonical slug of the personal dashboard to refresh now. |
There is no workspace argument, and passing one does not help: this is the one
tool that refuses a workspace target outright.
Returns
Three different outcomes are all successes. Handle each, because two of them mean no refresh ran.
It ran:
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:
Skipped refreshing "revenue-overview": a refresh ran within the last minute (status: success), so the data is already fresh.It queued:
Refresh of "revenue-overview" was queued (large dataset); it runs asynchronously. Use get_refresh_status to check progress.Two of the three successes did not refresh anything
The coalesce and the queued path both return success. A script that treats any
success as "the data is now current" is wrong on both: the coalesce means a
refresh ran up to a minute ago, and the queued path means one has not finished
yet. Poll
get_refresh_status rather than
trusting the receipt.
Errors
| Condition | Text |
|---|---|
| Missing slug | slug is required: the canonical slug of the personal dashboard to refresh. |
| Workspace target | Triggering a refresh on demand isn't available for workspace dashboards yet - it works on personal dashboards only. |
| 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 personal dashboard found with slug "<slug>". |
| Free plan | Refreshing on demand requires a paid 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.
Rate limited twice: 20 calls per user per minute at this tool, plus an
authoritative per-owner budget on the refresh service, which produces the
Too many refresh triggers right now. sentence rather than the generic one. See
Rate limits.
Scope
Personal only. This is the single tool of the eighteen that refuses a workspace target. Scheduled refresh of a workspace dashboard works normally, and so does reading its status; only the on-demand trigger is deferred.
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.