Schedule a dashboard and inspect its results

← Dashboards & Pages

Ask your agent to schedule a dashboard, for example: “Run yesterday’s revenue report every weekday at 09:00 in America/New_York. Preview the dates and inputs before applying, then show me the first completed result.”

Schedules belong to the dashboard definition. Each named schedule supplies a cron expression, a time zone, and every declared dashboard parameter. Editing a draft does not change running schedules; applying it does (Apply in Review draft, or the agent’s apply action). Remove a schedule from the definition and apply to stop future runs. There is no separate enable switch or “run as” user.

You need the Explorer role or higher to change schedules, preview drafts, and inspect applied schedules and run history. Viewers read the results of dashboards added to Pages and can’t start new results. Result reads check current access; a denied result does not mean its query failed.

Choose the dashboard and inputs

Call monomer_list with {"path":"workspaces"}, select a returned workspace ID, and read workspace with monomer_read. Follow the returned availableOperations paths to inspect the dashboard and any existing shared draft. Pass the entire advertised entry to monomer_describe before constructing create, start, edit, or apply inputs; previously fetched schemas can be reused in the session. Preserve unrelated draft work and existing schedule keys.

For a new example, first verify the connector and revenue metric using Create a dashboard. The following monomer_create input creates an unscheduled dashboard. Replace the illustrative workspace and connector UUIDs and the metric name with verified values.

monomer_create input

{
  "workspaceId": "0198ef28-2000-7000-8000-000000000001",
  "path": "workspace/dashboards",
  "input": {
    "kind": "DASHBOARD_DEFINITION",
    "definition": {
      "schemaVersion": 1,
      "meta": {"title": "Scheduled revenue report"},
      "parameters": {
        "period": {"type": "DATE_RANGE", "nullable": false},
        "reportDate": {"type": "DATE", "nullable": false},
        "asOf": {"type": "TIMESTAMP", "nullable": false},
        "label": {"type": "TEXT", "nullable": false}
      },
      "variables": {
        "reportPeriod": {"type": "DATE_RANGE", "nullable": false, "initial": {"kind": "PARAMETER", "name": "period"}}
      },
      "queries": {
        "revenue_total": {
          "type": "SEMANTIC",
          "connectorId": "0198ef28-2000-7000-8000-000000000002",
          "query": {
            "schemaVersion": 4, "metrics": ["revenue"], "groupBys": [],
            "filters": [], "orderBy": [], "rowLimit": 10,
            "metricTimeRange": {"kind": "VARIABLE", "name": "reportPeriod"}
          }
        }
      },
      "widgets": {
        "revenue_table": {"type": "TABLE", "queryName": "revenue_total", "columns": [{"field": "metric.revenue", "header": "Revenue"}]}
      },
      "layout": {"sections": [
        {"id": "revenue", "height": {"mode": "SCALED", "scale": 1}, "root": {"type": "WIDGET", "id": "revenue_node", "widgetId": "revenue_table"}}
      ]}
    }
  }
}

Only period affects this example’s query. The other parameters demonstrate fixed text, a relative date, and the scheduled instant; they remain visible in the recorded inputs. Declaring a parameter alone does not filter data. The query must consume it, here through reportPeriod and its parameter-based initial value.

For an existing dashboard, inspect its declared parameters and query references first. If its query still uses a fixed reporting period, make focused shared-draft edits to declare the required DATE_RANGE parameter, initialize a DATE_RANGE variable from it, and reference that variable in the existing query’s metricTimeRange, following the example above. Preserve other parameters, variables, queries, and widgets. Each schedule must bind that dashboard’s actual parameter set; do not copy the example’s four names into a different definition unchanged.

Schedule SQL queries

Schedules execute both SEMANTIC and SQL query entries through the same dashboard Session path. For a SQL query, use bindings to reference its declared parameters or range endpoints, as in Use a SQL query. A CALENDAR_RANGE DATE_RANGE parameter can supply start and end; SCHEDULED_TIME can supply a TIMESTAMP parameter. Schedule preview resolves inputs without executing or validating SQL. Verify a draft run with representative inputs before applying, then inspect an actual occurrence’s QueryRuns and results.

Each new scheduled SQL run performs the native accident-prevention check and enforces its declared columns and row limit. A row-limit or column mismatch fails the QueryRun even when the occurrence was accepted. The saved SQL runs with the Connector’s warehouse credentials, so use a dedicated read-only account: excessive procedure or function privileges can repeat side effects at every occurrence. SQL badges identify the query types recorded for displayed results; before results are ready, they use the dashboard definition’s query types. Agent response queryType records the result’s query type.

Edit and preview the schedule

For the example, call monomer_invoke to start a draft with complete, literal test inputs. Replace the illustrative dashboard ID with the created dashboard’s ID. Choose a known reporting day with data for your own test.

monomer_invoke input

{
  "workspaceId": "0198ef28-2000-7000-8000-000000000001",
  "path": "workspace/dashboards/0198ef28-2000-7000-8000-000000000003/draft",
  "action": "start",
  "input": {
    "kind": "DASHBOARD_DRAFT_START",
    "parameterBindings": {
      "period": {"start": "2026-09-18", "end": "2026-09-18"},
      "reportDate": "2026-09-18", "asOf": "2026-09-19T13:00:00Z", "label": "Daily report"
    }
  }
}

Starting an existing draft returns that draft unchanged. Read its actual inputs and revision; do not assume the example values replaced them. Use the shared draft editing procedure for any required changes.

Read the start result’s result.path to get the draft’s current revision and EDIT entry, then describe that entry. Call monomer_edit with the latest returned revision at the top level. This example assumes the dashboard has no schedules yet; adding /definition/schedules on an existing map would replace that map. For an existing map, add or replace only the intended key, such as /definition/schedules/weekday_report.

monomer_edit input

{
  "workspaceId": "0198ef28-2000-7000-8000-000000000001",
  "path": "workspace/dashboards/0198ef28-2000-7000-8000-000000000003/draft",
  "revision": "0",
  "patch": [{
    "op": "add", "path": "/definition/schedules",
    "value": {
      "weekday_report": {
        "cron": "0 9 * * MON-FRI", "timeZone": "America/New_York",
        "parameters": {
          "period": {"type": "CALENDAR_RANGE", "unit": "DAY", "offset": -1},
          "reportDate": {"type": "RELATIVE_DATE", "offsetDays": -1},
          "asOf": {"type": "SCHEDULED_TIME"},
          "label": {"type": "LITERAL", "value": "Daily report"}
        }
      }
    }
  }]
}

A second key, such as weekly_report, can use 0 9 * * MON and CALENDAR_RANGE with unit: "WEEK", offset: -1. Supply the complete parameter map for that schedule too. Schedule names start with a letter or underscore, contain only letters, digits, and underscores, and are at most 128 characters; __proto__ is reserved.

Read the draft preview with monomer_read:

monomer_read input

{
  "workspaceId": "0198ef28-2000-7000-8000-000000000001",
  "path": "workspace/dashboards/0198ef28-2000-7000-8000-000000000003/draft/schedules"
}

Inspect the next three scheduled instants, local times, resolved parameters, and any previewError. Preview reads do not execute queries or activate the draft. For a September 21, 2026 09:00 New York occurrence, this example resolves period to September 20–20, reportDate to September 20, and asOf to 2026-09-21T13:00:00Z. A delayed start keeps those same inputs.

Apply and inspect an actual occurrence

After reviewing the preview, read the draft for its current revision and advertised apply entry. Describe that entry if its schema has not been fetched yet, then call monomer_invoke with the current revision:

monomer_invoke input

{
  "workspaceId": "0198ef28-2000-7000-8000-000000000001",
  "path": "workspace/dashboards/0198ef28-2000-7000-8000-000000000003/draft",
  "action": "apply",
  "input": {"kind": "DASHBOARD_DRAFT_APPLY", "expectedRevision": "1"}
}

Read the dashboard’s advertised /schedules path to confirm the applied configuration and next execution time. New or changed schedules start at the next matching time after application; unchanged schedules keep their existing next time. A definition created with schedules already present also activates those schedules immediately.

After a due time, use monomer_list to inspect history:

monomer_list input

{
  "workspaceId": "0198ef28-2000-7000-8000-000000000001",
  "path": "workspace/dashboards/0198ef28-2000-7000-8000-000000000003/occurrences",
  "limit": 20
}

Read an occurrence using its returned path. Its outcome says whether it was ACCEPTED, SKIPPED, or ADMISSION_FAILED; ACCEPTED does not mean the queries succeeded. Check resultState and each initial QueryRun’s state. Follow the returned QueryRun read paths, then their advertised result read paths. A permission error when reading a result is separate from its execution state.

There is no “run this schedule now” action. If the first scheduled time is still in the future, report the applied configuration and next time, with actual execution verification still pending. Revisit history after that time; preview success or a separately run draft query is not evidence that the scheduled occurrence completed.

In the web app, open Schedules and choose the occurrence. The scheduled result preserves its definition, inputs, and original QueryRun IDs. Reopening or reloading it does not execute new queries. Explore these results opens interactive exploration separately; it does not replace the recorded scheduled result. Each newly accepted occurrence adds a new entry to History with new initial query runs, even when its inputs match an earlier occurrence.

Change or stop a schedule

Edit only the intended key in the shared draft, preview, and apply the latest revision. To stop weekday_report, use a JSON Patch remove at /definition/schedules/weekday_report, then apply. Removing it only in the draft does not stop the applied schedule. Confirm it is absent from the current /schedules response. Previous occurrences and their original results remain in history. Removing and later re-adding the same key starts from a new future time, without backfilling old times.

On a revision conflict, read the current draft and reconcile the change. Never overwrite someone else’s draft or invent a later revision.

Time expressions and missed runs

Cron uses five fields: minute, hour, day of month, month, day of week. Lists, ranges, steps, and three-letter month/day names are supported. Seconds, year fields, @daily, and L, W, #, ? are not. */35 in the minute field means minute 0 and 35 of each hour, not an interval of 35 minutes. If day of month and day of week are both restricted without *, either may match: 0 9 1 * MON runs on the first of the month and on Mondays. Prefer previewing actual dates over guessing cron behavior.

Use an explicit IANA time zone such as America/New_York or Asia/Seoul. Missing local times at a daylight-saving transition are skipped; a repeated local time runs once at its earlier UTC instant.

A schedule’s time zone decides when it runs and which days a CALENDAR_RANGE covers. Metric results still group days in the Workspace’s Reporting time zone, which reads those DATE endpoints as its own days. Use the same zone for both when a schedule reports whole days.

Binding	Parameter type	Meaning
LITERAL with value	Any declared type	A fixed typed value. Use a decimal string for NUMBER; explicit null only for nullable parameters.
RELATIVE_DATE with offsetDays	DATE	Scheduled local date plus that number of calendar days.
CALENDAR_RANGE with unit, offset	DATE_RANGE	A complete DAY, WEEK, or MONTH; weeks are Monday–Sunday and both endpoints are inclusive. offset: 0 means the whole current period, not “so far.”
SCHEDULED_TIME	TIMESTAMP	The scheduled instant as a UTC timestamp.

Every schedule must bind every declared parameter, including nullable parameters. Bindings cannot reference variables, query results, another schedule, or arbitrary expressions. Dashboard variables use their declared initial values, resolved from that occurrence’s parameters where applicable. A viewer’s current filters do not affect scheduled runs.

An occurrence more than 15 minutes late is recorded as SKIPPED with reason LATE. If the same schedule’s previous execution still occupies its run slot, it is SKIPPED with reason OVERLAP. Inspect an ADMISSION_FAILED reason or a failed QueryRun before deciding the next action. Failed or interrupted work is not automatically retried or backfilled as a new run. Do not interpret a missing or denied result as zero revenue.