Skip to navigation
API ReferenceCustom Views Experimental

Fetch a custom view’s data, scoped to a customer or the organization (experimental)

⚠️ Experimental — this endpoint may change or be removed without notice and is not subject to v2 backwards-compatibility guarantees. Do not build production-critical integrations against it yet.

Runs every stored query of the view on the read-only analytics database and returns the result sets keyed by query id. For a customer-scoped view (the default), the query is scoped to the caller’s organization AND the given customerId (both enforced as ClickHouse row filters) — customerId is required. For an organization-scoped view, the data is org-wide (scoped only to the caller’s organization) and customerId is ignored. The scope is enforced by the database — it cannot be widened by the stored SQL. If the view declares filters, pass per-request values as filter_<name> query parameters (e.g. filter_region=eu); undeclared names or disallowed values are rejected with 400. Filters narrow data within the scope — never widen it. Only PUBLISHED views are served by default; a DRAFT returns 404. To check a saved DRAFT’s real data before publishing, pass includeDraft=true. Embeds and share links never serve a DRAFT.

Authentication

AuthorizationBearer
API Key authentication using Bearer token

Path parameters

displayIdstringRequired

Query parameters

customerIdstringOptional>=1 character

Customer to scope the data to (dev/preview only; the embed derives this from the verified token). Required for customer-scoped views; ignored for organization-scoped views (their data is org-wide).

periodKindenumOptional

Override the view’s default date range for this request only. ‘relative’ = rolling window (set periodUnit + periodAmount); ‘absolute’ = fixed range (set periodStart + periodEnd).

Allowed values:
periodUnitenumOptional

relative override only: unit of the rolling window.

Allowed values:
periodAmountintegerOptional<=3650

relative override only: how many units back from today.

periodStartstringOptionalformat: "^\d{4}-\d{2}-\d{2}$"

absolute override only: inclusive start date (YYYY-MM-DD).

periodEndstringOptionalformat: "^\d{4}-\d{2}-\d{2}$"

absolute override only: inclusive end date (YYYY-MM-DD).

includeDraftenumOptional

Pass ‘true’ to also serve a DRAFT view, so you can check its real data before publishing. Without it a DRAFT returns 404. End-customer embeds and share links never serve a DRAFT.

Allowed values:
unitModeenumOptional

Unit selection for this request. Omit both unit parameters for all customer activity. Shared links instead use their saved starting selection when omitted; pass all to reset a shared link.

Allowed values:
unitExternalIdstringOptional>=1 character
The unit's external ID. Required with direct or subtree, and omitted with all.

Response

200
datamap from strings to lists of maps from strings to any

Result sets keyed by query id. Each value is an array of row objects (column name → value); 64-bit integers are returned as JSON strings to preserve precision.

contextobjectOptional

What these rows were read for. The render bundle receives this object as context in the paid:data message.

Errors

400
Bad Request Error
403
Forbidden Error
404
Not Found Error
408
Request Timeout Error
409
Conflict Error
429
Too Many Requests Error
500
Internal Server Error