Analytics API

Read Call

QueryAnalytics3

Compute analytics metrics (KPIs) for a period: totals or day-by-day series of participants, revenue, points earned and redeemed, redemption rate, tier counts and more, with an optional comparison period and market or campaign filter.

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

Works only for shops on Analytics V4. Get metric IDs from DescribeAnalytics3. This runs the same computations as the back office analytics pages.

Days are calendar days in the shop's time zone, inclusive. For a day-by-day series, ask for the metric's _daily variant.

To compare two periods, add compare_start_day and compare_end_day: each result then also carries compare_value or compare_cells.

Computing many metrics over a long period can take several seconds.

A computation may run for 30 seconds (time_limit raises that, up to 120) and may take 5 GB for the tables it builds. One stopped by a limit returns bad_data that says which limit; narrow the days or the filters, or ask for less at once. One computation runs at a time per shop, and a few on the whole server, so a call may wait for its turn; do not send calls for one shop in parallel.

Input

  • metrics array required

    Metric IDs to compute. Duplicates are ignored.

  • start_day date optional

    First day to include, in the shop's time zone.

    Defaults to the shop's analytics launch day. Earlier days count as the launch day.

  • end_day date optional

    Last day to include, in the shop's time zone.

    Defaults to today.

  • market string optional

    Limit the computation to one market: a key from markets in DescribeAnalytics3.

  • campaign string optional

    Limit the computation to one campaign: a name from campaigns in DescribeAnalytics3, or the campaign's ID.

  • time_limit integer optional

    How many seconds the computation may run before it is stopped.

    Defaults to 30. The server allows at most 120 and treats a larger number as 120. The limit is on computing. When analytics is busy the call first waits for its turn, for 10 seconds at most whatever this number is.

  • compare_start_day date optional

    First day of a comparison period. Give it together with compare_end_day.

  • compare_end_day date optional

    Last day of the comparison period.

Output

  • start_day date required

    First day actually computed.

  • end_day date required

    Last day actually computed.

  • results array required

    One result per requested metric, in the order of first request.

    Each result has metric, title, unit and axes. A metric without axes has one number in value. A metric with axes has cells: each cell has coords (one per axis; days as dates, object IDs as hexadecimal strings), optional labels (names of tiers) and values.

    Units: count is a whole number; money is a decimal string in the shop's base currency; number is a decimal; percent is a percentage (12.5 means 12.5%); days is a duration in days.

    A metric that failed has error instead of values; the other metrics are still returned. At most 10,000 cells are returned per metric; truncated says when cells were cut.

Usage Examples

A total and its daily series, compared with the week before

Request

{
  "compare_end_day": "2026-06-25",
  "compare_start_day": "2026-06-24",
  "end_day": "2026-07-02",
  "metrics": [
    "participants_count",
    "points_redemption_value",
    "points_earned_daily"
  ],
  "start_day": "2026-07-01"
}

Response

{
  "compare_end_day": "2026-06-25",
  "compare_start_day": "2026-06-24",
  "end_day": "2026-07-02",
  "results": [
    {
      "axes": [],
      "compare_value": 1180,
      "metric": "participants_count",
      "title": "Loyalty participants",
      "unit": "count",
      "value": 1204
    },
    {
      "axes": [],
      "compare_value": "398.000000",
      "metric": "points_redemption_value",
      "title": "Value of points redeemed",
      "unit": "money",
      "value": "412.500000"
    },
    {
      "axes": [
        "day"
      ],
      "cells": [
        {
          "coords": [
            "2026-07-01"
          ],
          "values": [
            5210
          ]
        },
        {
          "coords": [
            "2026-07-02"
          ],
          "values": [
            4987
          ]
        }
      ],
      "compare_cells": [
        {
          "coords": [
            "2026-06-24"
          ],
          "values": [
            4900
          ]
        },
        {
          "coords": [
            "2026-06-25"
          ],
          "values": [
            5100
          ]
        }
      ],
      "metric": "points_earned_daily",
      "title": "Points earned",
      "unit": "count"
    }
  ],
  "start_day": "2026-07-01"
}

Specific Errors

Status Error Reason & Examples
400 bad_data

The shop is not on Analytics V4, its analytics data is not built yet, an input is invalid, or the computation hit its memory or time limit.

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

For example: the computation was stopped: it ran longer than the 30s allowed. Narrow the days or the filters, or ask for fewer metrics at once. time_limit can raise the time limit, up to 2m0s.

429 too_many_requests

Analytics is busy: another computation is running for this shop, or six are running on the server, and no turn came up within 10 seconds. Nothing was computed; try again shortly.

For example: analytics is busy: another computation is running for this shop, or the server is at its limit. Nothing was computed after waiting 10s. Try again in about 10 seconds, and send calls for one shop one at a time

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
ListReferrals3