Analytics API

Read Call

DescribeAnalytics3

List the analytics metrics (KPIs) a shop has, with a plain-English definition of each: participants, revenue, points earned and redeemed, redemption rate, tier counts, referral results and more. Start here before computing analytics.

Kind Read API call
Method GET or POST
URL https://app.bubblehouse.com/api/v2023061/<shop>/DescribeAnalytics3
Authentication Shop Token

Works only for shops on Analytics V4. It returns the catalog that QueryAnalytics3 computes from: every metric's ID, title, description and unit, plus the shop's markets and campaigns to filter by, its analytics launch day and today's date in its time zone.

With definitions, each metric also carries its formula: as text, as a query object for QueryAnalyticsCustom3, and the IDs of the metrics it is built from.

A metric whose ID ends in _daily has one value per day; the same ID without the suffix is the total for the period.

With custom_tables, the result also lists the stored analytics tables that a custom query can read. Only QueryAnalyticsCustom3 needs them.

Input

  • metrics array optional

    Return only these metric IDs.

  • search string optional

    Return only metrics whose ID, title or description contains this text, ignoring case. For example redemption.

  • definitions boolean optional

    Include each metric's formula and the metrics it depends on. Makes the response much larger; combine with metrics or search.

  • custom_tables boolean optional

    Also return the stored tables and their columns, for writing a QueryAnalyticsCustom3 query.

    Tables and columns are internal and change without notice.

Output

  • launch_day date required

    First day analytics has data for.

  • today date required

    Today in the shop's time zone.

  • markets array required

    Market keys accepted by the market filter.

  • campaigns array required

    Campaign names accepted by the campaign filter.

  • metrics array required

    Metrics sorted by ID.

    Each has metric (the ID), title, description, unit and daily. With definitions: definition (formula text), query (the same formula as a query object) and depends_on.

  • units object required

    What each unit means.

  • notes array required

    How periods, daily metrics, axes and filters work.

  • custom_tables array optional

    When custom_tables was requested: each stored table with its entity, kind (fact-field, snap-field or event), table name, a ready scan query, and columns with name and type (u8, u16, u64, i64, bool, time-of-day).

Usage Examples

Finding redemption metrics

Request

{
  "search": "redemption rate"
}

Response

{
  "campaigns": [],
  "launch_day": "2024-03-01",
  "markets": [
    "ROOT"
  ],
  "metrics": [
    {
      "description": "Percentage of points redeemed versus points earned by customers with positive net revenue in the selected period.",
      "metric": "points_redemption_rate",
      "title": "Redemption rate",
      "unit": "percent"
    },
    {
      "daily": true,
      "description": "Percentage of points redeemed versus points earned by customers with positive net revenue in the selected period.",
      "metric": "points_redemption_rate_daily",
      "title": "Redemption rate",
      "unit": "percent"
    }
  ],
  "today": "2026-07-07"
}

Specific Errors

Status Error Reason & Examples
400 bad_data

The shop is not on Analytics V4, its analytics data is not built yet, or an input is invalid.

For example: Analytics V4 is not available for this shop

For example: unknown metric: example_metric (DescribeAnalytics3 lists metrics)

For example: start_day cannot be after end_day

Global Errors

Status Error Reason & Examples
401 invalid_token

The provided authentication token is invalid or has expired.

For example: The token has expired

429 rate_limit_exceeded

Your usage is over the rate limit. Ensure that you're not making duplicate calls, and contact our team for a rate limit increase.

For example: You are over the read limit per second for this customer

Previous
Version History