--- title: "Org element-grain query-performance analytics." method: GET path: "/v1/orgs/{orgId}/analytics/performance" tags: ["dashboards"] --- # Org element-grain query-performance analytics. `GET /v1/orgs/{orgId}/analytics/performance` ## Request - Base URL: `http://localhost:8080` - URL: `http://localhost:8080/v1/orgs/{orgId}/analytics/performance` - Auth: one of: - API key in cookie `dvt_session` - HTTP bearer Which specific dashboard elements are slow, failing, or heavily run — a leaderboard sibling to `GET /v1/orgs/{orgId}/analytics` (DVT-1215). Admin or owner only (audit:read). The `data` object shape is frozen — field names are a client contract. ## Query parameters - `days` integer - `connectionId` string, uuid - `dashboardId` string, uuid - `actorType` 'user' | 'api_key' | 'agent' ## Response `200` Org element-performance result. - object - `data` OrgAnalyticsPerformance, required: Element-grain query-performance leaderboard for a single organization over a rolling window (DVT-1215) — which specific dashboard elements are slow, failing, or heavily run. All field names are a frozen client contract. - `rangeDays` integer, required: The requested window in calendar days (echo of the clamped `days` param). - `generatedAt` string, date-time, required: RFC3339 UTC timestamp when this result was assembled. - `kpis` object, required: Scalar org-window KPIs, narrowed by the same filters as `elements`. - `p50Ms` number, required: Median duration in ms across all matching dashboard-render executions (0 when no data). - `p95Ms` number, required: P95 duration in ms across all matching dashboard-render executions (0 when no data). - `errorCount` integer, required: Executions with status='error' in the window. - `timeoutCount` integer, required: Executions with status='timeout' in the window. - `runs` integer, required: Total matching dashboard-render executions in the window. - `rowsReturned` integer: SUM of row_count across all matching dashboard-render executions in the window (counts only — never row data, ADR-0011 pushdown). 0 when no data. Optional; older clients ignore it. - `elements` object[], required: Up to 50 element-grain (or hash-grain, for unattributed queries) groups, descending by P95 duration. - `key` string, required: The GROUP BY identity: the element UUID when known, else "hash:" for queries with no element attribution. - `elementId` string, required: Element UUID, or empty string for hash-keyed groups. - `elementName` string, required: Element display name (spec title, else slug); 'deleted element' when the id is set but unresolvable (soft-deleted / cross-org); empty for hash-keyed groups. - `elementType` string, required: e.g. 'chart:bar'; empty when unresolved. - `pageId` string, required: Page UUID, or empty string when unresolved. - `pageTitle` string, required: Page title, or empty string when unresolved/untitled. - `dashboardId` string, required: Dashboard UUID, resolved via the element join or falling back to the group's own dashboard_id; empty string when neither is known. - `dashboardTitle` string, required: Dashboard title, or empty string when unresolved/untitled. - `runs` integer, required: Query executions in this group within the window. - `p50Ms` number, required: Median duration in ms within the window. - `p95Ms` number, required: P95 duration in ms within the window. - `errorCount` integer, required: Executions with status IN ('error','timeout') in this group. - `views` integer, required: Distinct dashboard-render request_ids in this group. - `lastRunAt` string, date-time, required: Most recent execution's started_at in this group. - `lastEditedAt` string, date-time, nullable, required: The element's latest revision timestamp, or null when no revision history / not element-keyed. - `lastEditedBy` string, required: Latest editor's display_name, else email, else 'unknown'; empty string when no revision history. - `lastEditedByType` string, required: Latest revision's actor_type ('user', 'agent', or 'system'); empty string when no revision history. - `latestSql` string, required: Latest non-empty query_text in this group (params bound separately — no literal PII). Empty string when not captured. - `trendP95` object[], required: Per-day P95 duration series for this group, ascending by date. Empty array (never null) for hash-keyed groups or when no trend data. - `date` string, required: YYYY-MM-DD (UTC). - `p95Ms` number, required - `connectionHealth` object[]: DVT-1500 (Health page) addition: per-connection latency histogram + last-connection-test status, one entry per live connection in the org (even with zero window activity), honoring the same `days`/`connectionId` filters as `elements`. - `connectionId` string, required: Connection (data source) UUID. - `name` string, required: Connection display name. - `lastTestedAt` string, date-time, nullable, required: Timestamp of the connection's most recent test, or null when never tested. - `lastTestError` string, required: The most recent test's error, truncated to 160 characters; empty string when the last test succeeded (or none on record). - `isHostConnection` boolean, required: DVT-1782: true for the single boot-provisioned host Snowflake connection (spcs_token). That connection's lastTestedAt/lastTestError come from POST /v1/connections/host/test's caller's-rights PER-MEMBER probe (DVT-1777) — whichever member last self-tested, not an admin-run service-level test. Clients MUST label this connection's health distinctly (e.g. "last member connection test") rather than presenting it as an authoritative service test. - `isHostWritebackConnection` boolean: DVT-2905: true for the single boot-provisioned host Snowflake WRITEBACK connection (auth_method='spcs_token', kind='writeback') — the sibling of isHostConnection above (the pushdown connection). Unlike isHostConnection, this row's lastTestedAt/lastTestError follow the SAME ordinary service-credential test path as any other connection (there is no caller's-rights writeback probe), so it carries no per-member-freshness caveat. - `histogram` object, required: Server-side fixed-edge bucketing of this connection's window query durations — raw durations are never shipped to the client. - `bucketsMs` integer[], required: Ascending upper-bound edges in ms. - `counts` integer[], required: One more entry than `bucketsMs` — the trailing entry is the open-ended tail bucket. - `runs` integer, required: Window dashboard-render executions on this connection. - `errorCount` integer, required: Window executions with status IN ('error','timeout') on this connection. - `errorCalendar` object[]: DVT-1500 (Health page) addition: daily failed dashboard-render query counts over a FIXED 90-calendar-day window (independent of the `days` filter, so the calendar shape stays stable regardless of the current KPI window), narrowed by `connectionId` when set. Only nonzero-error days are included. - `date` string, required: YYYY-MM-DD (UTC). - `errors` integer, required: Total failed dashboard-render executions that day. - `worstElementId` string, required: UUID of the element with the most errors that day; empty string when no error that day is element-attributed. - `worstElementName` string, required: That element's display name, or 'deleted element' when unresolvable; empty string when worstElementId is empty. - `worstCount` integer, required: That element's error count that day; 0 when worstElementId is empty. - `mirror` object: DVT-3495 (child of DVT-3481) — the postgres->Snowflake mirror's durability state: is this install's metadata actually backed up, and if not, what must an admin do about it. Rendered as the Health page's durability banner. ABSENT means "nothing to report", and is the normal shape in three distinct situations a client must treat identically (render nothing): a non-snowflake edition, where no mirror exists (`editionCapabilities.mirrorDurability` is false); a snowflake install whose service spec carries no mirror container yet; and a mirror the operator has explicitly disabled. Absence is NEVER "unknown" — an unreachable mirror reports `state: unknown` explicitly, because "we cannot tell you whether you have a backup" is information an admin needs and must not be silently swallowed. Snowflake mode only. The field is populated from the mirror container's own status endpoint on an in-pod, read-only probe that runs concurrently with this endpoint's query; a probe failure degrades this field, never the response. - `state` 'durable' | 'not_durable' | 'stale' | 'unknown', required: `durable` — the last sync cycle completed; the mirror is current. `not_durable` — the consumer has NO usable backup right now; the loudest state on the page, always accompanied by `reason`. `stale` — a generation exists but no cycle has succeeded within the worker's staleness bound (3x MIRROR_INTERVAL); a warning, not an outage. `unknown` — the mirror container could not be reached, or answered something this build does not understand; never render this as healthy. - `reason` string: The mirror worker's own actionable remediation prose, forwarded VERBATIM and never rewritten, re-worded, or truncated by the API — the single-source-prose discipline (`_WRITEBACK_NOT_PROVISIONED_MESSAGE`) applied to the mirror, so the copy telling an admin which SQL to run lives in exactly one place. Typically present on `not_durable` and `stale`, and deliberately ABSENT on `unknown`: the API has no worker answer to forward there and will not invent one (clients supply their own "couldn't reach the mirror" copy, a fact about reachability rather than about the consumer's Snowflake account). When `reason` is absent on a failing state, `lastError` below usually carries the diagnostic instead. - `lastError` string: The mirror worker's raw error text for the last failed cycle, forwarded VERBATIM under the same no-rewriting rule as `reason`. A SEPARATE field because the worker's own contract keeps them separate: `reason` is the actionable remediation ("run this SQL"), `lastError` is the diagnostic ("connection to server failed"). A worker may send either, both, or neither — so a client rendering only `reason` will show a bare NOT DURABLE headline with no explanation whenever the failure was transient rather than a provisioning gap. Render it as secondary detail when `reason` is absent. - `errorCode` string: Structured failure code from the engine. Known values: `mirror-not-provisioned` (the mirror database does not exist — with `neverCompleted` true the admin has not run the one-time setup yet) and `mirror-schema-not-app-owned`. The engine emits `mirror-not-provisioned` only after confirming from the persisted log that no generation ever completed; a database lost after a generation completed never carries this code and stays a red NOT DURABLE. Clients must treat unknown values as absent. Never render the code text itself. - `neverCompleted` boolean: True when NO mirror generation has ever completed for this install — the DVT-3495 install-completion criterion. Always accompanied by `state: not_durable`: "you have no backup yet" must read as NOT DURABLE and must be rendered DISTINCTLY from `stale`, never softened into it. The one carve-out: when `errorCode` is `mirror-not-provisioned` the engine has confirmed from the persisted log that no backup was ever written, and the UI may show a neutral "set up" state. That state still says there is no backup. Derived from whether the worker REPORTED a last success, not from whether the API could parse the timestamp it used — an unreadable timestamp degrades `lastSuccessAt` alone and never changes this flag. Kept as its own flag rather than a fifth `state` value because the mirror worker's status contract is frozen and emits no such state. Absent/false means a generation exists (or, on the `unknown` path, that no worker answer was available to assert this from). - `lastSuccessAt` string, date-time: When a sync cycle last completed. HISTORICAL — it survives a detach and never resets, so it may be present long after `currentGeneration` has gone absent. Absent when no cycle has ever completed, or when the state is `unknown`. RFC 3339 UTC. - `consecutiveFailures` integer: Consecutive failed cycles since the last success. Absent/0 when the last cycle succeeded. - `currentGeneration` object: The mirror generation currently live in the consumer's Snowflake database — the generation a restore would read. VERIFIED-CURRENT: present only when the worker confirmed the generation within its most recent cycle, so it goes absent as soon as the mirror becomes unreadable to the application. Contrast `lastSuccessAt`, which is HISTORICAL and never resets. READ IT TOGETHER WITH `state`; absent means different things under each, and only one of them is a claim about your backup. Under `state: not_durable`, absent means there is nothing live to restore from, and `neverCompleted` separates the two shapes: true, no generation has ever completed (setup was never finished); false, a sync succeeded previously but no generation is live now. Do not read an absent `currentGeneration` together with a prior `lastSuccessAt` as "a copy still exists". That second shape is ALSO the expected post-detach steady state: after the consumer detaches the mirror to their own role (the supported step before uninstalling), the application can no longer read it, so `currentGeneration` goes absent while `lastSuccessAt` is retained. Clients MUST NOT render it as unqualified data loss — the consumer's copy is intact in that case, and the worker's `reason` names it. Under `state: unknown`, absent asserts NOTHING. The API had no worker answer at all — it never learned whether a generation exists and will not claim one is missing. Rendering "nothing to restore from" here would report a lost backup that dvt merely could not see, which is the same overclaim in the opposite direction from a false all-clear. - `id` string, required: Generation identifier recorded in mirror_meta. - `schemaVersion` string: The source schema_migrations version this generation was taken at — a restore requires it to equal the running image's head. - `imageTag` string: The app image tag that produced this generation. - `completedAt` string, date-time: When this generation's promotion transaction committed. - `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. - `403`: The caller's role does not permit this action. - `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)