Spoar
Reads

Top values of a dimension

GET
/v2/projects/{project}/breakdown/{dimension}

Any dimension from the registry, prop:<key> or trait:<key>, with the metrics list and each value's share of visitors.

Authorization

AuthorizationBearer <token>

An API token from POST /v2/tokens (at_live_...), or a project's secret key (sk_...) for server-side ingest.

In: header

Path Parameters

project*string

The project id, as listed by GET /v2/projects.

Length1 <= length
dimension*string

A registered dimension such as page, referrer_domain, country, browser, device or utm_source, or prop:<key>, trait:<key> and group:<type>.

Length1 <= length

Query Parameters

from?string

Start of the range; send with to.

Formatdate-time
to?string

End of the range, exclusive.

Formatdate-time
period?string

A range ending at the start of today in UTC (24h ends at the start of this hour). Ignored when from and to are sent; 30d by default.

Value in

  • "24h"
  • "7d"
  • "30d"
  • "90d"
  • "12mo"
  • "all"
traffic?string

Which traffic is counted. human (the default) leaves out bot scores of 50 and up, your own visits and localhost; bots keeps only scores of 50 and up; internal keeps only your own visits; all keeps everything.

Value in

  • "human"
  • "bots"
  • "internal"
  • "all"
environment?string

production (the default) leaves preview deployments out, preview keeps only them, all keeps both.

Value in

  • "production"
  • "preview"
  • "all"
filter?

Sent as filter[<dimension>]=value, or !value to exclude; repeatable across dimensions.

metrics?string

Comma-separated metrics, the same names as timeseries takes; default visitors,pageviews, and for page also bounce_rate,time_on_page. Rows sort by the first two.

Length1 <= length
limit?|

Rows per page, 1 to 100 (default 20), or up to 1000 with format.

Range1 <= value <= 1000
cursor?string

The opaque nextCursor of the previous page.

Length1 <= length
format?string

Returns every row as one download instead of a page, up to 1,000,000 rows: csv with a header row and nested fields as dotted columns, json as the normal answer with all rows in data, sql as CREATE TABLE and INSERT statements for Postgres or SQLite. Accept: text/csv also asks for CSV.

Value in

  • "csv"
  • "json"
  • "sql"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v2/projects/string/breakdown/string"
{  "data": [    {      "value": "/",      "visitors": 702,      "pageviews": 1011,      "bounceRate": 0.52,      "avgTimeMs": 38000,      "share": 0.583    },    {      "value": "/blog/rebuilding-analytics",      "visitors": 412,      "pageviews": 530,      "bounceRate": 0.71,      "avgTimeMs": 142000,      "share": 0.342    },    {      "value": "/projects",      "visitors": 188,      "pageviews": 240,      "bounceRate": 0.33,      "avgTimeMs": 51000,      "share": 0.156    }  ],  "dimension": "page",  "total": 64,  "nextCursor": "eyJvIjozfQ",  "range": {    "from": "2026-09-20T00:00:00.000Z",    "to": "2026-09-27T00:00:00.000Z"  },  "traffic": "human",  "environment": "production",  "filters": {}}