Analytics API
Read CallQueryAnalytics3
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
-
metricsarray requiredMetric IDs to compute. Duplicates are ignored.
-
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.
-
First day of a comparison period. Give it together with
compare_end_day. -
Last day of the comparison period.
Output
-
First day actually computed.
-
Last day actually computed.
-
resultsarray requiredOne result per requested metric, in the order of first request.
Each result has
metric,title,unitandaxes. A metric without axes has one number invalue. A metric with axes hascells: each cell hascoords(one per axis; days as dates, object IDs as hexadecimal strings), optionallabels(names of tiers) andvalues.Units:
countis a whole number;moneyis a decimal string in the shop's base currency;numberis a decimal;percentis a percentage (12.5 means 12.5%);daysis a duration in days.A metric that failed has
errorinstead of values; the other metrics are still returned. At most 10,000 cells are returned per metric;truncatedsays 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: 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: |