Skip to content
BuildBase

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.

Home, titled Dashboard: the All users, All audience, Emails sent and Link clicks tiles, the period picker and the Users, Audience, Emails and Workspaces cards, with the Home rail item highlighted as step 1

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.

The All users, All audience, Emails sent and Link clicks tiles, each with its total and its growth, highlighted as step 2

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".

Platform activity overview: a radar of Users, Audience, Emails, Link clicks and Workspaces, the current period against the previous one, highlighted as step 3

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.

User signup activity: sign-ups by day of the week and hour of the day, with its title highlighted as step 4

Website visitors and revenue, the web analytics card, is explained on Analytics.

Which endpoint each card reads

CardEndpoint
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 overvieweach 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:

ParameterTypeRequiredNotes
groupBystringYesOne of day, week, month, year
filterobjectYes{ 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

ModuleEndpoints
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
Email/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:

ShapeUsed for
LineOne series over time - signups per day
StackedSeveral series over the same buckets - email sent vs opened
ComparisonTwo 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:

ParameterTypeNotes
filterobjectfilter[from] and filter[to], as for charts
previousbooleantrue 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:

ParameterTypeDefaultNotes
fromstring30 days before toA date-time. At most 400 days before to
tostringnowA date-time
hostnamestringevery siteOne host, such as www.example.com, or *.example.com for every host of that site
filtersstringnoneA JSON object of up to 5 filters, dimension to value, such as {"channel":"Paid"}
touchstringlastlast 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'
EndpointReturns
/api/analytics/web/overviewThe period's totals, the previous period's, and a series by hour (two days or less) or day
/api/analytics/web/breakdown/:dimThe top values of one dimension, limit 1 to 100 (default 10)
/api/analytics/web/customers, /visitorsPages of paying customers and of visitors, page and limit 1 to 100 (default 25)
/api/analytics/web/visitors/:vidOne visitor and their visits
/api/analytics/web/acquisition/user/:id, /acquisition/workspace/:idWhere 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