Analytics API

Read Call

ExplainAnalytics3

Drill down into one analytics number: show the formula behind a metric, the value of every metric it is built from for the same period, and a query for each step that reveals the rows behind it, such as the customers counted.

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

Works only for shops on Analytics V4. It answers "why is this number what it is?" the way the back office metric trace page does.

steps lists the nodes of the formula, outermost first. A step with a query yields a table of its own: pass that query to QueryAnalyticsCustom3 with the same days and filters to see it, for example one row per customer.

In formulas, days are numbers counted from the shop's analytics launch day, and money and fractions are integers scaled by 1,000,000.

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

  • metric string required

    ID of the metric to explain, from DescribeAnalytics3.

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

Output

  • start_day date required

    First day actually computed.

  • end_day date required

    Last day actually computed.

  • result object required

    The metric's value, as QueryAnalytics3 returns it.

  • definition string required

    The formula as text.

  • steps array required

    The formula's nodes: depth, step (text) and, where the step yields a table, query.

  • depends_on array required

    The value of every metric the formula refers to, for the same days and filters.

Usage Examples

Why the outstanding points value is what it is

Request

{
  "end_day": "2026-07-07",
  "metric": "points_outstanding_value",
  "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
DescribeAnalytics3