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

import { PaidClient } from "@paid-ai/paid-node";
async function main() {
    const client = new PaidClient({
        token: "YOUR_TOKEN_HERE",
    });
    await client.customViewsExperimental.getCustomViewData("monthly-sales-summary", {
        customerId: "cust_987654321",
        periodKind: "relative",
        periodUnit: "month",
        periodAmount: 3,
    });
}
main();

{
  "data": {
    "query_001": [
      {
        "date": "2024-03-01",
        "total_sales": "152340",
        "transactions": 1245,
        "average_order_value": 122.35
      },
      {
        "date": "2024-04-01",
        "total_sales": "178920",
        "transactions": 1390,
        "average_order_value": 128.85
      },
      {
        "date": "2024-05-01",
        "total_sales": "165780",
        "transactions": 1310,
        "average_order_value": 126.55
      }
    ],
    "query_002": [
      {
        "region": "North America",
        "sales": "320450",
        "orders": 2750
      },
      {
        "region": "Europe",
        "sales": "210780",
        "orders": 1900
      }
    ]
  }
}

⚠️ 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.

⚠️ **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.

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

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.

Errors

400

Bad Request Error

403

Forbidden Error

404

Not Found Error

408

Request Timeout Error

429

Too Many Requests Error

500

Internal Server Error