Skip to content
tracing.toolstracing.tools

Breakdown

GET /api/v1/sites/:id/breakdown?dimension=path

Parameters

Section titled “Parameters”
Parameter Values Default
dimension one of the 21 dimensions path
limit 1–500 20
range the nine range keys 30d
any filter key none

limit is clamped, not rejected: limit=9000 returns 500 rows and limit=0 returns one.

Request

Section titled “Request”
Terminal window
curl -s -H "Authorization: Bearer tk_live_…" \
  "https://tracing.tools/api/v1/sites/pk_live_a91c3f04/breakdown?dimension=referrer&range=30d&limit=5"

Response

Section titled “Response”
{
  "dimension": "referrer",
  "data": [
    { "name": "Direct / none",             "value": 2841, "events": 6902 },
    { "name": "google.com",                "value": 1109, "events": 2418 },
    { "name": "news.ycombinator.com",      "value": 402,  "events": 1044 },
    { "name": "github.com",                "value": 188,  "events": 371 },
    { "name": "reddit.com",                "value": 97,   "events": 210 }
  ]
}
Field Meaning
name The dimension value
value Unique visitors with that value — what the rows are ranked by
events Raw hits behind them. Larger whenever one visitor triggered the value more than once

Rows whose value is null are dropped, so a dimension never returns an empty label.

Dimensions

Section titled “Dimensions”
Dimension Groups by
path Pathname
entryPath First page of the visit (per session)
exitPath Last page of the visit (per session)
title document.title
hostname Host
query The query string left after tracking parameters are stripped
referrer Referrer domain, with Direct / none for null
utmSource utm_source, or the ref/source/via fallback
utmMedium utm_medium
utmCampaign utm_campaign
utmTerm utm_term
utmContent utm_content
country ISO-3166 alpha-2
region First subdivision
city City
language navigator.language
browser Browser name
os Operating system
device desktop, mobile, tablet, bot, unknown
screen One of six width buckets
event Event name — custom and outbound only

event never includes plain pageviews, which have no name. For revenue events and full event analytics use /events.

Drilling

Section titled “Drilling”

The row’s name is exactly the value you pass back as that dimension’s filter, which is how the dashboard’s click-to-filter works:

Terminal window
# top pages for visitors who came from Hacker News
curl -s -H "Authorization: Bearer tk_live_…" \
  "https://tracing.tools/api/v1/sites/pk_live_a91c3f04/breakdown?dimension=path&referrer=news.ycombinator.com"

The literal string Direct / none selects the rows with no referrer.

Errors

Section titled “Errors”
Status Body
400 {"error":"unknown dimension","allowed":["path","entryPath", …]}
401 {"error":"Missing or invalid API key"}
404 {"error":"site not found"}

The 400 response lists every accepted dimension, so a client can discover them at runtime.

Section titled “Related”