---
title: "Get a single element."
method: GET
path: "/v1/dashboards/{id}/pages/{pageId}/elements/{elementId}"
tags: ["dashboards"]
---

# Get a single element.

`GET /v1/dashboards/{id}/pages/{pageId}/elements/{elementId}`

## Request

- Base URL: `http://localhost:8080`
- URL: `http://localhost:8080/v1/dashboards/{id}/pages/{pageId}/elements/{elementId}`
- Auth: one of:
  - API key in cookie `dvt_session`
  - HTTP bearer

Returns one element (type, title, grid position, data, spec, overrides) without
round-tripping the whole dashboard spec. The response includes a `themeContext` map —
the resolved values of every theme token the element references — so an agent can
interpret the element in isolation (mcp-server-design.md §Token budget).

## Query parameters

- `include` 'provenance' | 'themeTokens'

## Response `200`

The element plus its resolved themeContext.

- ElementEnvelope
  - `data` Element, required: A single dashboard element, fetched or patched without the rest of the spec. `themeContext`/`dvtRefs` are present on responses to let an agent interpret the element in isolation.
    - `elementId` string, uuid, required: Durable UUID primary key.
    - `slug` string, required: Readable, dashboard-scoped reference (the authored panel id), e.g. "panel-revenue".
    - `pageId` string, uuid, required
    - `dashboardId` string, uuid, required
    - `type` string, required
    - `title` string
    - `subtitle` string: Optional panel subtitle (POLISH-16).
    - `x` integer, required
    - `y` integer, required
    - `w` integer, required
    - `h` integer, required
    - `zIndex` integer
    - `data` object: Panel data binding (sourceId, query/metricRef, params, optional baked rows).
    - `spec` object: The element body (near-passthrough to ECharts); token references stay unresolved.
    - `overrides` object: Per-element token overrides.
    - `drill` object: Legacy drill-down block (POLISH-16).
    - `contextMenu` object: Right-click context menu binding (POLISH-16).
    - `brush` object: Brush-select interaction binding (POLISH-16).
    - `onClick` object: Single bare click-action binding — filter, drill, or openOverlay (POLISH-16).
    - `themeContext` object: Resolved values of every theme token this element references.
    - `resolvedTokens` object: The FULL resolved theme token map for this element — every key the tier stack (org baseline / preset / dashboard / page / element overrides) declares, i.e. the renderer's own ResolvedTokens (web/src/tokens.ts), not the referenced-token subset in `themeContext`. Present on GET-single-element responses only, and only when the caller opts in via `?include=themeTokens` (DVT-4298). A consumer that must reproduce what the browser PAINTED needs it: a table's header row is styled from `panel.background` and `text.secondary`, which no panel spec references, so `themeContext` cannot carry them and a formatted export built from it would fall back to default header colors.
    - `dvtRefs` string[]: Named $dvtRef registry keys the element uses (e.g. "formatter:pie-label").
    - `version` integer, required: Optimistic-concurrency version. Pass this back on PATCH.
    - `provenance` ElementProvenance: Bounded creation/last-edit summary for a single element (DVT-1665). `createdBy` is the version=1 revision's actor; `lastEdit` is the newest revision's actor. `revisionCount` is the total number of revisions (versions are sequential 1..N).
      - `createdBy` ElementProvenanceActor, required: Actor attribution for one point in an element's history (creation or most recent edit). `reason` and `version` are only meaningful on the `lastEdit` position — absent on `createdBy`.
        - `actorType` 'user' | 'agent' | 'system', required
        - `actorName` string: Resolved display name (display_name, else email). Absent for a system write with no actor.
        - `actorLabel` string: "via {key}" credential label (API-key name / MCP client id). Absent for first-party UI edits.
        - `createdAt` string, date-time, required
        - `reason` string: Optional user/agent-authored "why" for this revision. Only set on `lastEdit`.
        - `version` integer: The revision version this actor corresponds to. Only set on `lastEdit`.
      - `lastEdit` ElementProvenanceActor, required: Actor attribution for one point in an element's history (creation or most recent edit). `reason` and `version` are only meaningful on the `lastEdit` position — absent on `createdBy`.
        - `actorType` 'user' | 'agent' | 'system', required
        - `actorName` string: Resolved display name (display_name, else email). Absent for a system write with no actor.
        - `actorLabel` string: "via {key}" credential label (API-key name / MCP client id). Absent for first-party UI edits.
        - `createdAt` string, date-time, required
        - `reason` string: Optional user/agent-authored "why" for this revision. Only set on `lastEdit`.
        - `version` integer: The revision version this actor corresponds to. Only set on `lastEdit`.
      - `revisionCount` integer, required
  - `meta` Meta, required: Response metadata.
    - `requestId` string, required: Correlates with the X-Request-Id header.
    - `total` integer: Item count, present on collection responses.
    - `nextCursor` string, nullable: Opaque keyset-pagination cursor, present on paginated responses (e.g. GET /v1/dashboards) when more rows exist beyond this page. Pass it back as the `cursor` query param to fetch the next page; absent or null on the last page.
    - `roleResolveDegraded` boolean: Snowflake mode only (DVT-2260), on GET /v1/dashboards: present and true when the caller's live Snowflake role resolution failed or was unavailable — role-shared dashboards may be missing from this page. Omitted (not merely false) whenever resolution succeeded or the role-share arm does not apply (off snowflake mode, an org admin/owner, or off the ingress listener).

## Other responses

- `401`: Missing, invalid, or expired session.
- `404`: Resource does not exist.

---

[API](https://skmtc.dev/dvt/apis/dvt-rest-api.md) · [All operations](https://skmtc.dev/dvt/apis/dvt-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/dvt/apis/dvt-rest-api/revisions/00016f504165?raw)