Analytics API
Read CallDescribeAnalytics3
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
-
metricsarray optionalReturn only these metric IDs.
-
searchstring optionalReturn only metrics whose ID, title or description contains this text, ignoring case. For example
redemption. -
definitionsboolean optionalInclude each metric's formula and the metrics it depends on. Makes the response much larger; combine with
metricsorsearch. -
custom_tablesboolean optionalAlso return the stored tables and their columns, for writing a
QueryAnalyticsCustom3query.Tables and columns are internal and change without notice.
Output
-
First day analytics has data for.
-
Today in the shop's time zone.
-
marketsarray requiredMarket keys accepted by the
marketfilter. -
campaignsarray requiredCampaign names accepted by the
campaignfilter. -
metricsarray requiredMetrics sorted by ID.
Each has
metric(the ID),title,description,unitanddaily. Withdefinitions:definition(formula text),query(the same formula as a query object) anddepends_on. -
unitsobject requiredWhat each unit means.
-
notesarray requiredHow periods, daily metrics, axes and filters work.
-
custom_tablesarray optionalWhen
custom_tableswas requested: each stored table with itsentity,kind(fact-field,snap-fieldorevent),tablename, a readyscanquery, andcolumnswithnameandtype(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: For example: 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: |