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","to":"2026-08-01T00:00:00Z"}'Before you start
/api/analytics is not a reporting endpoint. It mounts third-party
integrations only. Use the per-module endpoints below.
The shared query shape
Every chart endpoint validates 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 |
from and to are required inside filter. No other properties are accepted —
the schema sets additionalProperties: false, so an extra key is a 400 rather
than being ignored.
Buckets are computed in the organization's timezone, not UTC, so a day
bucket lines up with the calendar day your users see.
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 |
| Organizations | /api/organizations/chart |
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 | The current period against the preceding one |
counts endpoints are not charts. They return totals for the current state and
take no groupBy.
heatmap and world-map-data are geographic, derived from the IP recorded on
the underlying event.
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:
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.