Refresh a dashboard

How-to guideApplies to: Unified engine deployments

Create a dashboard with one inline SQL dataset, request a refresh, and inspect its snapshot. The dashboard service and query compute must be enabled.

Create and refresh an inline dashboard

Create a Manual dashboard, request one snapshot, and read its dataset results.

Placeholder	Value
`{{dashboard_submission}}`	A new UUID for this request; reuse it when recovering the same submission.
`{{refresh_submission}}`	A new UUID for this request; reuse it when recovering the same submission.
`{{dataset_id}}`	A new UUID for this request; reuse it when recovering the same submission.

Replace the placeholders in your client. Keep returned IDs for later requests. Paths below use the native API prefix; adjust it for your deployment.

1. Create the definition

POST /api/v1/dashboards
Host: <ENGINE_HOST>
Content-Type: application/json

{
  "submission_id": "{{dashboard_submission}}",
  "definition": {
    "name": "HTTP example - category dashboard",
    "datasets": [
      {
        "dataset_id": "{{dataset_id}}",
        "name": "Category sales",
        "sql": "WITH orders(id, category, region, amount) AS (VALUES (1, 'Books', 'North', 20), (2, 'Games', 'South', 30), (3, 'Games', 'North', 15), (4, 'Books', 'North', 40), (5, 'Garden', 'South', 25), (6, 'Garden', 'North', 10)) SELECT category, SUM(amount) AS sales FROM orders GROUP BY category ORDER BY category",
        "settings": {
          "current_catalog": "default",
          "namespace": [
            "default"
          ],
          "time_zone": "UTC",
          "case_sensitive": false,
          "ansi_enabled": true
        }
      }
    ],
    "widgets": [],
    "schedule": "Manual",
    "options": {
      "execution_target": "DuckDb"
    }
  }
}

From the response, keep dashboard_id from /dashboard/dashboard_id, dashboard_revision from /dashboard/revision. Endpoint reference.

2. Request one refresh

POST /api/v1/dashboards/{{dashboard_id}}/refresh
Host: <ENGINE_HOST>
Content-Type: application/json

{
  "submission_id": "{{refresh_submission}}",
  "expected_revision": {{dashboard_revision}},
  "parameters": {}
}

From the response, keep refresh_id from /snapshot/refresh_id. Endpoint reference.

3. Follow the snapshot

GET /api/v1/dashboards/{{dashboard_id}}/snapshots/{{refresh_id}}
Host: <ENGINE_HOST>

Repeat this read until /snapshot/status reaches a terminal state: Succeeded, Failed, Cancelled, OutcomeUnknown, Skipped. Endpoint reference.

4. Read category totals

GET /api/v1/dashboards/{{dashboard_id}}/snapshots/{{refresh_id}}/datasets/{{dataset_id}}/results?limit=1
Host: <ENGINE_HOST>

Endpoint reference. Saving a definition and activating recurring execution are different actions. This example keeps scheduling Manual. A refresh returns a snapshot identity; follow that snapshot before reading a dataset result. Expected category totals are Books 60, Games 45, and Garden 35. A snapshot can contain dataset failures or widget errors, so inspect those details as well as the overall status. The saved dashboard remains after you leave the page. Read its current revision before pausing, changing, or deleting it. Cancellation does not roll back any earlier committed data work.

Transformation Engine

Learn Laminar

Workloads

SQL reference

HTTP API

Recipes

Operations

Create and refresh an inline dashboard

1. Create the definition

2. Request one refresh

3. Follow the snapshot

4. Read category totals

​Create and refresh an inline dashboard

​1. Create the definition

​2. Request one refresh

​3. Follow the snapshot

​4. Read category totals

Create and refresh an inline dashboard

1. Create the definition

2. Request one refresh

3. Follow the snapshot

4. Read category totals