Analytics API
Read CallExplainAnalytics3
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
-
metricstring requiredID of the metric to explain, from
DescribeAnalytics3. -
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.
-
Last day to include, in the shop's time zone.
Defaults to today.
-
marketstring optionalLimit the computation to one market: a key from
marketsinDescribeAnalytics3. -
campaignstring optionalLimit the computation to one campaign: a name from
campaignsinDescribeAnalytics3, or the campaign's ID. -
time_limitinteger optionalHow 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
-
First day actually computed.
-
Last day actually computed.
-
resultobject requiredThe metric's value, as
QueryAnalytics3returns it. -
definitionstring requiredThe formula as text.
-
stepsarray requiredThe formula's nodes:
depth,step(text) and, where the step yields a table,query. -
depends_onarray requiredThe 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: For example: For example: For example: |
| 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: |
Global Errors
| Status | Error | Reason & Examples |
|---|---|---|
| 401 | invalid_token |
The provided authentication token is invalid or has expired. For example: |
| 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: |