Reporting
Where each module's charts and counts live, and the query shape they share.
There is no single analytics API. Reporting is per module: each one exposes its own chart and count endpoints, and the console composes them into dashboards. This page is the map.
curl -G https://api.console.buildbase.app/api/users/chart \
-H "Authorization: $BUILDBASE_TOKEN" \
--data-urlencode 'groupBy=day' \
--data-urlencode 'filter[from]=2026-07-01T00:00:00Z' \
--data-urlencode 'filter[to]=2026-08-01T00:00:00Z'Before you start
/api/analytics holds two things: third-party integrations
(/api/analytics/integrations) and web analytics
(/api/analytics/web, with the tracker at /api/analytics/script.js). The
charts of each module's own data are the per-module endpoints below.
The Home dashboard
Open Home in the console (opens the console in a new tab)The console's Home puts these endpoints on one page. It shows only the cards your role can read: users, audience, email history, link analytics, workspaces, subscriptions or web sessions. A member with none of them sees "Nothing to show yet".
1. Open Home
In the left rail choose Home. The page opens on the Dashboard.

2. Read the totals
The first row counts everything so far: All users, All audience, Emails sent and Link clicks, each with its growth by month. The row under the day, week, month and year picker counts the same for the dates you choose, against the period before.

3. Compare this period with the last
Platform activity overview draws users, audience, emails, link clicks and workspaces as a radar, "current period vs previous".

4. See when people sign up
User signup activity is a heatmap of sign-ups by day of the week and hour of the day. The maps below it show where users and audience are.

Website visitors and revenue, the web analytics card, is explained on Analytics.
Which endpoint each card reads
| Card | Endpoint |
|---|---|
| All users, Users, Users vs audience growth | /api/users/counts, /api/users/chart, /comparison-chart |
| All audience, Audience, Audience by country | /api/audience/counts, /chart, /world-map-data |
| Emails sent, Emails, Email delivery status | /api/emails/counts, /chart, /stacked-chart |
| Email engagement tracking | /api/emails/history/stacked-chart |
| Link clicks, Link click trends | /api/links-analytics/counts, /chart |
| Workspaces, Workspace growth | /api/workspaces/counts, /chart |
| Subscriptions | /api/subscriptions/chart |
| Platform activity overview | each module's /counts, for this period and the one before |
| User signup activity, Users world map, Users by country | /api/users/heatmap, /world-map-data |
| Website visitors and revenue | /api/analytics/web/overview, /breakdown/channel |
Some figures come from rollups refreshed every 10 minutes (Freshness).
The shared query shape
Every module's chart endpoint (everything in the table below but web analytics) takes the same two parameters, and both are required:
| Parameter | Type | Required | Notes |
|---|---|---|---|
groupBy | string | Yes | One of day, week, month, year |
filter | object | Yes | { from, to }, both ISO 8601 date-times |
filter is an object in the query string: send filter[from]=...&filter[to]=...,
as above, or the same object as JSON (filter={"from":"...","to":"..."}). A
filter that is not a JSON object is a 400.
from and to are required inside filter, and are read as dates: the
time of day is dropped, and the range runs from the start of the from day to
the end of the to day, in the organization's time zone.
filter[to]=2026-10-30T05:00:00Z counts everything created on 30 October,
also after 05:00. The console sends the days picked as
2026-10-30T00:00:00.000Z and 2026-10-30T23:59:59.999Z.
Any other key in filter narrows the records counted, as a field match:
filter[status]=failed on /api/emails/chart counts only failed emails. Its
value goes through the same read-only operator allowlist as a list endpoint's
filter, and an operator outside it is a 400. Use a field the records have:
an unknown key is not refused, so a misspelt one gives a wrong count rather
than an error.
The stacked charts (/stacked-chart) also need config[stackedByKey], the
field whose values become the series: the console sends status to
/api/emails/stacked-chart and opened to /api/emails/history/stacked-chart.
/api/emails/history/stacked-chart takes at most 92 days between the from
day and the to day, so a calendar quarter fits. A longer range, or a to
before from, is a 400. The console's date picker on the email engagement
charts offers nothing longer.
On that chart, Opened and Clicked count messages, not events: a
message opened three times on one day counts once that day, and once more on
each other day it is opened. A click counts as an open too, since the person
saw the message. Unsubscribed counts each message someone unsubscribed
from, through its unsubscribe link or the mailbox's one-click button, once, on
the day they did. For one campaign (filter[campaign]=) the totals match the
unique opens, unique clicks and unsubscribes on that campaign's Analytics tab.
Days, weeks, months and years are in your organization's time zone, UTC
unless you set one under Settings > General
(organization settings). With
America/Los_Angeles set, a sign-up at 20:00 in Los Angeles on 29 October
(03:00 UTC on the 30th) falls on 29 October; on UTC it falls on 30 October.
The counts' days start and end at midnight in the same zone.
GET /api/organizations/settings/config answers the zone as timezone, and
PATCH on the same path with { "timezone": "America/Los_Angeles" } sets it.
It takes an IANA zone name as the tz database spells it; any other value is a
400.
Where to find each
| Module | Endpoints |
|---|---|
| Users | /api/users/chart, /comparison-chart, /counts, /heatmap, /world-map-data |
| Audience | /api/audience/chart, /counts, /heatmap, /world-map-data, /:id/tab-counts |
| Audience lists | /api/audience-lists/chart, /:id/world-map-data |
/api/emails/chart, /counts, /stacked-chart, /history/stacked-chart | |
| Short links | /api/links-analytics/chart, /counts |
| Collections | /api/collections/chart |
| Forms | /api/forms/:id/submissions/chart |
| Workflows | /api/workflows/:id/metrics, /api/workflows/instances/counts |
| Workspaces | /api/workspaces/chart, /counts, /:id/users/world-map-data |
| Subscriptions | /api/subscriptions/chart |
| Stripe webhooks | /api/organizations/payment/stripe/webhooks-data/chart |
| Web analytics | /api/analytics/web/overview, /breakdown/:dim, /customers, /visitors, /visitors/:vid, /acquisition/user/:id, /acquisition/workspace/:id |
Chart shapes
Three response shapes, depending on which handler backs the endpoint:
| Shape | Used for |
|---|---|
| Line | One series over time - signups per day |
| Stacked | Several series over the same buckets - email sent vs opened |
| Comparison | Two modules over the same buckets - users vs audience |
The comparison shape backs /api/users/comparison-chart. It takes the same
groupBy and filter as a line chart and returns one row per bucket, with a
0 where a module had nothing in that bucket:
[{ "time": "2026-06-01", "users": 5, "audience": 12 }]counts endpoints are not charts. They return totals for a period and take no
groupBy. Both parameters below are required:
| Parameter | Type | Notes |
|---|---|---|
filter | object | filter[from] and filter[to], as for charts |
previous | boolean | true adds the period of the same length just before from, to compare |
curl -G https://api.console.buildbase.app/api/users/counts \
-H "Authorization: $BUILDBASE_TOKEN" \
--data-urlencode 'filter[from]=2026-07-01T00:00:00Z' \
--data-urlencode 'filter[to]=2026-08-01T00:00:00Z' \
--data-urlencode 'previous=false'heatmap is not a map: it counts records by day of the week and hour of the
day of createdAt, in the organization's time zone, as rows such as
{ "row": "Fri", "col": "11", "value": 7 }. It takes an optional filter and
no dates, so it covers every record unless you narrow it.
world-map-data counts records by the country stored on each one, as
{ "country": "US", "value": 12 }.
Web analytics
The web analytics reports have a query of their own. None of it is required:
| Parameter | Type | Default | Notes |
|---|---|---|---|
from | string | 30 days before to | A date-time. At most 400 days before to |
to | string | now | A date-time |
hostname | string | every site | One host, such as www.example.com, or *.example.com for every host of that site |
filters | string | none | A JSON object of up to 5 filters, dimension to value, such as {"channel":"Paid"} |
touch | string | last | last or first: which visit a payment's revenue is credited to |
Unlike the module charts, from and to keep their time, and filters is a
JSON string. The one exception is the form the console sends for the days
picked: from at T00:00:00.000Z is the start of that day and to at
T23:59:59.999Z its end, in the organization's time zone, never later than
now. The series is by the hour or day in the same zone. An unknown key is a 400, and so is a filter on a dimension that
cannot be filtered on (page, goal and outbound, which are read from
events rather than visits).
curl -G https://api.console.buildbase.app/api/analytics/web/breakdown/source \
-H "Authorization: $BUILDBASE_TOKEN" \
--data-urlencode 'from=2026-10-01T00:00:00Z' \
--data-urlencode 'to=2026-10-31T23:59:59Z' \
--data-urlencode 'filters={"channel":"Paid"}' \
--data-urlencode 'limit=10'| Endpoint | Returns |
|---|---|
/api/analytics/web/overview | The period's totals, the previous period's, and a series by hour (two days or less) or day |
/api/analytics/web/breakdown/:dim | The top values of one dimension, limit 1 to 100 (default 10) |
/api/analytics/web/customers, /visitors | Pages of paying customers and of visitors, page and limit 1 to 100 (default 25) |
/api/analytics/web/visitors/:vid | One visitor and their visits |
/api/analytics/web/acquisition/user/:id, /acquisition/workspace/:id | Where one customer came from: first and last touch, visits and revenue |
:dim is one of channel, source, referrer, utm_source, utm_medium,
utm_campaign, utm_term, utm_content, ref, hostname, entry_page,
exit_page, page, country, region, browser, os, device, goal and
outbound. A token whose role cannot read users gets visitor ids without the
people behind them. What each report means is on
Analytics.
Freshness
Some figures are served from rollups computed by a background job that runs every 10 minutes, rather than aggregated per request.
Warning
Rolled-up numbers are eventually consistent. A signup from two minutes ago may not appear in a chart yet, and a chart can disagree with a live list endpoint for up to ten minutes.
For "is this exactly right now", read the underlying records. Charts are for trends.
Building your own
The chart endpoints are shaped for the console's widgets. For anything else,
read the records and aggregate yourself - every list endpoint supports filter,
sort, and pagination=false, which is usually enough. filter and sort
take brackets, as here, or one JSON object (filter={"unsubscribed":false});
a filter that is not a JSON object is a 400, never an unfiltered list.
curl -G https://api.console.buildbase.app/api/audience \
-H "Authorization: $BUILDBASE_TOKEN" \
--data-urlencode 'filter[unsubscribed]=false' \
--data-urlencode 'pagination=false'Watch the response size - pagination=false returns everything matching. See
the admin API for the full list-query contract.
Next Steps
- Admin API - tokens, pagination, and error shapes.
- Workflows monitoring - instance counts and health.