Dashboards

list_dashboards browses a workspace, or finds a dashboard by name when you pass query. get_dashboard is the primary read — it returns the agent-facing context summary alongside the widgets. create_dashboard with fromDashboardId copies one.

Read-only

List or search the dashboards in a workspace that you can access. Without query it ENUMERATES: each row carries widgetCount, updatedAt and ownerId + ownerName, enough to triage and attribute without a list_widgets call per dashboard. With query it SEARCHES names, tags and descriptions, ranked ({ results, hint? }, each hit with matchedOn and score) — never list everything and filter the names yourself. RANK ORDER IS NOT IDENTITY: when the hint says near-identical names tie, confirm the target (get_dashboard / list_widgets) before any destructive call. Nothing matched: search each workspace from get_me, or list without query and match semantically. ownerId keeps what one person owns and accessibleBy what they can see ("what can Bob get to?"), each a uid from list_workspace_members; neither widens YOUR visibility.

Read-only

Return one dashboard in full: metadata (archived: true = soft-deleted), its context summary (purpose, use cases, caveats, a plain-language reading per widget), every widget and the parameters. contextStatus: ready = current, generating = a regeneration is in flight and this is the previous text, stale = queued or failed. The summary is enough to describe the dashboard; for actual values read the cached rows with get_widget include data (no refresh, no pipeline run), and for one widget's full wiring use get_widget. Refresh only when the user needs newer data than the last refresh. url is its address; publicLink and embed say who else can open it (set_sharing). A select with more than 25 options returns 10 with optionsTotal and optionsSampled: true; the full list is its source widget's rows, and set_parameter names the closest options when a value misses.

Additive write

Create a new dashboard in a workspace, or copy one with fromDashboardId; you own it. A COPY deep-copies every live widget (wiring, transform, last published rows) and the parameters into a new dashboard named '<source> copy' unless you pass name. Copying is the right call whenever the user wants a variant to edit without touching the original ("copy this and swap the country"): ONE call, then edit the copy — never rebuild by hand. It needs only view access to the source; archived sources copy fine. NOT copied: history, discussions, the public link, and the schedule's owner — a stored schedule is copied DISABLED; re-enable it with update_dashboard's cadence (runs then use YOUR connections). Returns the new dashboard's id.

Destructive write

Rename a dashboard, change its description, override its palette and formatting on top of the workspace theme (theme, or clearTheme: true to drop every override), or turn its scheduled refresh on or off (cadence, whose description holds the schedule's rules). Only what you pass changes. Use a theme override only when a dashboard genuinely needs to look different from the rest of the workspace: the workspace theme, which an admin sets in Settings, is the right place for a house style. Requires edit access.

cadence

The schedule: enabled plus an interval, every N minutes | hours | days | weeks (minimum 15 minutes). refresh runs once, NOW; this keeps data current. MATCH THE INTERVAL TO HOW OFTEN THE SOURCE PUBLISHES. Annual/quarterly sources: weeks (daily is 365 identical fetches a year). Daily sources (exchange rates, weather, filings): a day, or hours for same-day movement. Minutes only for a live feed. A DASHBOARD schedule is free: saving attributes it to YOU — runs execute on the dashboard owner's data-source connections, and a chart one repairs with AI (at most once a day per chart) draws your usage allowance — and re-saving un-pauses one paused for credential failures or failing sources. A SCHEDULE KEEPS THE FETCH CURRENT, NOT THE WINDOW: a widget argumentTemplate with a literal end bound (end_year 2020), or a notebook data cell / vistazo.call with a literal date, re-fetches the same window every run — check get_widget before promising it stays current. A NOTEBOOK schedule is BILLED: each run restarts the notebook and runs every cell as YOU, on your data access and compute allowance; it needs edit access, runs whatever the notebook holds at run time, and a failed run is reported to you and the owner. A seat holds at most 25 scheduled dashboards and 25 notebooks per workspace. enabled:false stops scheduling, keeping the configuration. An interval repeats from its first run (the next 15-minute sweep after enabling); the reply's note names that weekday and UTC time. Fixed weekdays/times (calendar schedules) are set in the web app's Schedule card; toggling enabled without an interval preserves one, and passing interval/unit replaces it. The reply reports the schedule AS IT NOW STANDS — nextRunAt (null when it will not fire; with a nextRunNote the run is due on the next sweep and nextRunAt is the latest it comes), lastRunAt, and pausedReason with how to resume. get_dashboard and get_notebook return the same block.

Destructive write

Archive a dashboard (soft delete): hidden from discovery, with its widgets, parameters, data and history kept; restore:true brings it back. Nothing hard-deletes a dashboard, and no follow-up cleanup call exists: list_dashboards hides it unless includeArchived:true and list_widgets' query stops returning it, while reads by id still work (get_dashboard reports archived:true; list_widgets and get_widget return the last published data). While archived every write refuses, as do refresh, explore_dashboard and turning its public link on; the public link stops resolving and scheduled refresh pauses (the cadence is kept), so its data freezes at the last refresh. Requires edit access (owner, editor, or workspace admin).