custom-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.

get/experimental/views/{displayId}/data

Request

  • Base URL: https://api.agentpaid.io/api/v2
  • URL: https://api.agentpaid.io/api/v2/experimental/views/{displayId}/data
  • Auth: HTTP bearer

Path parameters

displayIdstring required

Query parameters

customerIdstring

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).

periodKind'relative' | 'absolute'

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

periodUnit'day' | 'month' | 'year'

relative override only: unit of the rolling window.

periodAmountinteger

relative override only: how many units back from today.

periodStartstring

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

periodEndstring

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

includeDraft'true' | 'false'

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.

unitMode'all' | 'direct' | 'subtree'

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.

unitExternalIdstring

The unit's external ID. Required with direct or subtree, and omitted with all.

Response

200

dataobject required

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.

Changes

No recorded changes to this operation across all 1 revision of this API.