Breakdowns

curl --request GET \
  --url 'https://truestat.io/api/v1/sites/{siteId}/breakdowns/{dimension}' \
  --header 'Authorization: Bearer <token>'

{
  "data": [
    {
      "label": "US",
      "views": 412,
      "visitors": 206
    },
    {
      "label": "IN",
      "views": 190,
      "visitors": 136
    }
  ],
  "meta": {
    "page": {
      "limit": 100,
      "offset": 0,
      "has_more": true
    },
    "range": {
      "to": "2026-09-16T13:40:00.000Z",
      "tz": "UTC",
      "from": "2026-08-17T13:40:00.000Z",
      "clamped": false
    },
    "site_id": "6fed8980-a119-4a9c-a4d4-53e448ef9f9e"
  }
}

One endpoint, sixteen dimensions. The dimension is a path segment.

The dimensions

An unknown dimension is a 400 that lists the valid ones, rather than an empty result that reads like "no data".

goal covers both kinds of goal

A conversion reaches TrueStat two ways, and this dimension returns them in one ranked list — the same list the dashboard's card shows:

• Sent goals, recorded as events by the script or POST /goals

• Rule-based goals, defined by a URL and evaluated when you read the report

You cannot tell them apart from a row, and for ranking purposes you do not need to. What matters is that adding a rule changes this breakdown for past windows too, because the rule is applied at read time rather than recorded at visit time.

Every row has the same shape

{ "label": "US", "visitors": 206, "views": 412 }

label is the value grouped by, whatever the dimension. It is deliberately not named after the dimension — a caller looping over several of them writes one loop rather than a switch.

Fields that mean nothing for a dimension are absent, not null: a country has no click count, an exit link has no revenue. Absent keys disappear from JSON; nulls have to be filtered by every caller.

Paging

limit and offset, with meta.page.has_more telling you whether to ask again.

There is no total. Counting every matching row costs as much as the query itself on a wide window, and on live data the number is stale before you read it. has_more is what a pager actually needs.

Filters compose with the dimension

Any filter_* narrows the rows before they are ranked. Breaking down by path with filter_country=DE gives the top pages among German visitors — the same drill-down the dashboard does when you click a row.

Authorizations

Path parameters

Query parameters

Response