Cascade

    Analytics

    POST /analytics/query

    Aggregate a resource into chart-ready rows. Name the measures and dimensions you want, and pass the same filter document the resource's list endpoint takes, so one filter can drive both the list and the chart. Measure and dimension names are whitelisted per resource: anything else is rejected. Grouping by a date buckets it with granularity in the organization's time zone, and the empty buckets inside the series are filled in. Grouping by anything else returns the top limit combinations plus one Other row carrying the rest.

    Requires the analytics:read permission.

    Costs 5 rate limit tokens instead of the usual one. See Rate limits.

    Body Parameters

    resourcereviews | review-answers | orders | customers | products | loyalty-members | loyalty-activity | loyalty-rewardsrequired

    The resource to aggregate. Call /analytics/schema for what each one offers.

    measuresstring[]required

    The measures to report, by name. Names are whitelisted per resource and anything else is rejected: reviews (measures: count, avgRating, publishedCount, flaggedCount, verifiedBuyerCount, uniqueCustomers, uniqueProducts); review-answers (measures: count, averageStep, uniqueReviews); orders (measures: count, revenue, averageOrderValue, uniqueCustomers); customers (measures: count, subscribedCount, optedOutCount); products (measures: count, reviewedCount); loyalty-members (measures: count, activeCount); loyalty-activity (measures: count, pointsEarned, pointsSpent); loyalty-rewards (measures: count, redeemedCount).

    groupBystring[]

    The dimensions to group by, by name, at most three and at most one of them a date. Omit for a single total row.

    granularityhour | day | week | month | quarter | year

    The bucket size for a date dimension. Defaults to day. Ignored when nothing in groupBy is a date.

    filterstring

    The same filter document the resource's list endpoint takes, so the filter bar's current filter can be sent to both.

    timezonestring

    The time zone to bucket date dimensions in, as an IANA name such as America/New_York. Defaults to the organization's own time zone.

    limitinteger

    How many distinct group-by combinations to return, from 1 to 500. Defaults to 50. Everything past the cap is re-aggregated into one "Other" row.

    fillGapsboolean

    Whether to materialize the empty buckets inside a date series, so a quiet week reads as zero rather than as a straight line. Defaults to true.

    Request
    curl \
  -X POST \
  "https://api.cascade.dev/analytics/query" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "resource": "reviews",
  "measures": [
    "string"
  ],
  "groupBy": [
    "string"
  ],
  "granularity": "hour",
  "filter": "string",
  "timezone": "string",
  "limit": 0,
  "fillGaps": true
}'
    Response
    {
  "data": ["..."],
  "meta": {
    "resource": "reviews",
    "timezone": "string",
    "granularity": "hour",
    "dimensions": [
      {
        "name": "...",
        "label": "...",
        "type": "...",
        "association": "..."
      }
    ],
    "measures": [
      {
        "name": "...",
        "label": "...",
        "type": "...",
        "description": "..."
      }
    ],
    "truncated": true,
    "otherLabel": "string"
  }
}

    GET /analytics/schema

    List what the analytics endpoint can aggregate: every resource, with the measures and dimensions it accepts and what each one means. Use it to build a chart picker, or to check a saved chart still names something real.

    Requires the analytics:read permission.

    Request
    curl \
  "https://api.cascade.dev/analytics/schema" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"
    Response
    {
  "data": [
    {
      "resource": "string",
      "measures": ["..."],
      "dimensions": ["..."]
    }
  ]
}