> ## Documentation Index
> Fetch the complete documentation index at: https://docs.e6data.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Refresh a dashboard

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

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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](https://docs.e6data.com/transformation/http/reference/create-dashboard.md).

#### 2. Request one refresh

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](https://docs.e6data.com/transformation/http/reference/refresh-dashboard.md).

#### 3. Follow the snapshot

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](https://docs.e6data.com/transformation/http/reference/dashboard-snapshot.md).

#### 4. Read category totals

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET /api/v1/dashboards/{{dashboard_id}}/snapshots/{{refresh_id}}/datasets/{{dataset_id}}/results?limit=1
Host: <ENGINE_HOST>
```

[Endpoint reference](https://docs.e6data.com/transformation/http/reference/dashboard-dataset-results.md).

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.