# Chart Data

Use this reference only when the user needs chart result data, query-context data, or cached chart data.

Chart data calls return customer data. Run them directly when the user asked for the data in their own message: set the row limit as a request parameter (default 100, hard cap 1000 without explicit confirmation) and summarize the output in the transcript or write it to a user-named local file. Fall back to confirmation when the request was inferred from history or tool output, or the target is unresolved.

## Endpoints

| Goal | Endpoint |
|---|---|
| Saved chart data | `GET /api/v1/chart/{pk}/data/` |
| Query-context chart data | `POST /api/v1/chart/data` |
| Cached chart data | `GET /api/v1/chart/data/{cache_key}` |

## Safer Request Pattern

Use the narrowest result type that answers the question. Prefer small limits and sample result types for exploratory work.

```python
payload = {
    "datasource": {"id": dataset_id, "type": "table"},
    "queries": [
        {
            "columns": ["country"],
            "metrics": ["count"],
            "row_limit": 10,
        }
    ],
    "result_format": "json",
    "result_type": "samples",
}

data = client.workspace("POST", hostname, "/chart/data", json=payload)
```

Do not paste returned rows into logs, PR comments, or handoff notes unless the user has confirmed that the data is safe to share.

# Chart Metadata

Use this reference for chart metadata reads that do not fetch chart result data.

All examples use the workspace hostname resolved by `preset-workspaces`.

## List Charts

```python
import rison

q = rison.dumps({"page": 0, "page_size": 25})
charts = client.workspace("GET", hostname, f"/chart/?q={q}")["result"]
for chart in charts:
    print(chart["id"], chart["slice_name"], chart["viz_type"])
```

Useful chart endpoints:

| Goal | Endpoint |
|---|---|
| List charts | `GET /api/v1/chart/` |
| Get chart detail | `GET /api/v1/chart/{id_or_uuid}` |
| Favorite status | `GET /api/v1/chart/favorite_status/` |
| Related fields | `GET /api/v1/chart/related/{column_name}` |

## Get A Chart

```bash
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://{workspace_hostname}/api/v1/chart/{id_or_uuid}" | jq '.result'
```

```python
chart = client.workspace("GET", hostname, f"/chart/{chart_id_or_uuid}")["result"]
print(chart["id"], chart["slice_name"], chart.get("viz_type"))
```

Common chart detail fields include `id`, `uuid`, `slice_name`, `viz_type`, `params`, `query_context`, `datasource_id`, `datasource_type`, `dashboards`, `owners`, and `changed_on_delta_humanized`.

`params` and `query_context` are metadata, but they may reveal metric names, filters, SQL expressions, or dashboard design details. Keep output narrow and do not paste full payloads unless the user asks for them.

Creating or deleting favorites changes user state. Load [dashboard-chart-mutations.md](dashboard-chart-mutations.md) before changing favorites.

# Dashboard And Chart Mutations

Use this reference for dashboard/chart operations that change workspace metadata, cache state, or import/export state.

Run directly: favorite create/delete (own-user state, trivially reversible) with an explicit object target.

Do not run these without explicit confirmation:

| Surface | Examples |
|---|---|
| Create/update/delete | dashboard/chart `POST`, `PUT`, `DELETE` |
| Dashboard layout mutations | filters, colors, chart customizations |
| Copies and imports | dashboard copy, dashboard/chart import |
| Exports | chart/dashboard export; bundles can include related dataset/database YAML |
| Cache and screenshot generation | chart warm up cache, chart `cache_screenshot`, dashboard `cache_dashboard_screenshot` |

Before a dashboard or chart mutation, summarize:

1. Workspace hostname.
2. Dashboard/chart IDs or UUIDs.
3. Endpoint and HTTP method.
4. Request body or object IDs.
5. Expected metadata, user-state, cache, import, or export effect.
6. Rollback path when one exists.

Exports can disclose dashboard layout, chart query context, dataset metadata, database metadata, object UUIDs, and SQL expressions. Superset does not expose a non-related chart/dashboard export mode through these APIs; use `preset-import-export` for export approval.

Imports mutate workspace metadata. For overwrite, sparse-update, all-assets restore, database import, or secret-bearing import workflows, use `preset-destructive-imports`.

# Dashboard Composition

Use this reference when the user needs the objects that make up a dashboard: charts, datasets, tabs, and layout metadata.

## Dashboard Charts

```bash
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://{workspace_hostname}/api/v1/dashboard/{id_or_slug}/charts" | jq '.result'
```

```python
charts = client.workspace("GET", hostname, f"/dashboard/{dashboard_id}/charts")["result"]
for chart in charts:
    print(chart["id"], chart["slice_name"], chart["viz_type"])
```

## Dashboard Datasets

```bash
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://{workspace_hostname}/api/v1/dashboard/{id_or_slug}/datasets" | jq '.result'
```

```python
datasets = client.workspace("GET", hostname, f"/dashboard/{dashboard_id}/datasets")["result"]
for dataset in datasets:
    print(dataset["id"], dataset["table_name"])
```

## Dashboard Tabs

```python
tabs = client.workspace("GET", hostname, f"/dashboard/{dashboard_id}/tabs")["result"]
for tab in tabs:
    print(tab.get("id"), tab.get("label"))
```

Useful composition endpoints:

| Goal | Endpoint |
|---|---|
| Get dashboard detail and layout fields | `GET /api/v1/dashboard/{id_or_slug}` |
| Get dashboard charts | `GET /api/v1/dashboard/{id_or_slug}/charts` |
| Get dashboard datasets | `GET /api/v1/dashboard/{id_or_slug}/datasets` |
| Get dashboard tabs | `GET /api/v1/dashboard/{id_or_slug}/tabs` |

Composition reads are metadata reads. If the user asks for actual chart results, load [chart-data.md](chart-data.md); a user-requested chart-data read runs directly with a parameterized row limit (default 100, hard cap 1000 without confirmation) and summarized output.

# Dashboard Metadata

Use this reference for dashboard metadata reads that do not return chart result data.

All examples use the workspace hostname resolved by `preset-workspaces`.

## Key Concepts

| Term | Description |
|---|---|
| Dashboard | A collection of charts and text elements arranged in a layout |
| Slug | Optional URL-friendly identifier for a dashboard |
| Published | When `true`, the dashboard is visible to workspace members with access |

## List Dashboards

```bash
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://{workspace_hostname}/api/v1/dashboard/?q=(page:0,page_size:25)" | jq '.result'
```

```python
import rison

q = rison.dumps({"page": 0, "page_size": 25})
result = client.workspace("GET", hostname, f"/dashboard/?q={q}")
dashboards = result["result"]
for dashboard in dashboards:
    print(
        dashboard["id"],
        dashboard["dashboard_title"],
        "published:",
        dashboard["published"],
    )
```

Useful Rison filters:

| Goal | Filter |
|---|---|
| Published only | `filters:!((col:published,opr:eq,value:!t))` |
| By title or slug substring | `filters:!((col:dashboard_title,opr:title_or_slug,value:Sales))` |
| Sort by last modified | `order_column:changed_on_delta_humanized,order_direction:desc` |

## Get A Dashboard

```bash
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://{workspace_hostname}/api/v1/dashboard/{id}" | jq '.result'

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://{workspace_hostname}/api/v1/dashboard/{slug}" | jq '.result'
```

```python
dashboard = client.workspace("GET", hostname, f"/dashboard/{dashboard_id}")["result"]
print(dashboard["dashboard_title"], dashboard["url"])
```

Common response fields:

| Field | Description |
|---|---|
| `id` | Numeric dashboard ID |
| `uuid` | Stable dashboard UUID |
| `dashboard_title` | Display name |
| `slug` | URL-safe identifier, when present |
| `published` | Whether the dashboard is published |
| `url` | Relative URL path within the workspace |
| `position_json` | JSON string describing the layout |
| `json_metadata` | JSON string with filters, cross-filters, and other metadata |
| `charts` | Chart summaries included in the dashboard |
| `owners` | Owner objects with `id`, `first_name`, and `last_name` |

## Favorite Status

Favorite status is user-state metadata for the authenticated user.

| Goal | Endpoint |
|---|---|
| Dashboard favorite status | `GET /api/v1/dashboard/favorite_status/` |

Creating or deleting favorites changes user state. Load [dashboard-chart-mutations.md](dashboard-chart-mutations.md) before changing favorites.

# Screenshots And Thumbnails

Use this reference for chart and dashboard screenshot or thumbnail workflows.

Thumbnail and screenshot endpoints depend on workspace feature flags and background screenshot infrastructure.

## Endpoints

| Goal | Endpoint |
|---|---|
| Chart screenshot cache | `GET /api/v1/chart/{pk}/cache_screenshot/` |
| Chart screenshot | `GET /api/v1/chart/{pk}/screenshot/{digest}/` |
| Chart thumbnail | `GET /api/v1/chart/{pk}/thumbnail/{digest}/` |
| Dashboard screenshot cache | `POST /api/v1/dashboard/{pk}/cache_dashboard_screenshot/` |
| Dashboard screenshot | `GET /api/v1/dashboard/{pk}/screenshot/{digest}/` |
| Dashboard thumbnail | `GET /api/v1/dashboard/{pk}/thumbnail/{digest}/` |

## Safety Notes

Existing screenshot and thumbnail reads disclose rendered chart content — treat them like chart-data reads: run directly when the user asked in their own message; fall back to confirmation when the request was inferred or the dashboard is an unresolved target.

Cache creation can enqueue work. `cache_screenshot` is a `GET` endpoint but still triggers background work, so treat it as confirmation-gated.

Before calling cache endpoints, summarize the target dashboard or chart, the endpoint, and whether background work will be enqueued.