Filter parameters reference

Every key on this page works as a query parameter on:

/api/v1/sites/:id/stats
/api/v1/sites/:id/series
/api/v1/sites/:id/breakdown
/api/v1/sites/:id/events (shapes 1 and 2 only)
/api/export/:id
and every dashboard URL.

/realtime accepts none of them.

Rules

Every filter is an AND. There is no OR, no negation, no multi-select.
One value per key. A repeated parameter takes the first.
Values are trimmed; an empty value is dropped.
Unknown parameters are ignored, not rejected.
Values are matched exactly and case-sensitively, except where noted.
Remember to URL-encode: path=%2Fpricing, referrer=Direct%20%2F%20none.

The keys

Content

Key	Value	Example
`path`	Exact pathname, leading slash	`/pricing`
`query`	The query string left after `utm_*`, `ref`, `source`, `via` and click ids are stripped	`q=cookies`
`title`	Exact `document.title`	`Pricing — Acme`
`hostname`	Host of the page	`acme.com`
`entryPath`	First page of the visit. Selects visits	`/`
`exitPath`	Last page of the visit. Selects visits	`/checkout/success`

Acquisition

Key	Value	Example
`referrer`	Referrer domain, `www.` stripped. The literal `Direct / none` selects “no referrer”	`news.ycombinator.com`
`utmSource`	`utm_source`, or the `ref`/`source`/`via` fallback	`hn`
`utmMedium`	`utm_medium`	`cpc`
`utmCampaign`	`utm_campaign`	`launch`
`utmTerm`	`utm_term`	`web+analytics`
`utmContent`	`utm_content`	`variant-b`

Location

Key	Value	Example
`country`	ISO-3166 alpha-2 code, not the name	`DE`
`region`	First subdivision, as stored	`Berlin`
`city`	City, as stored	`Berlin`
`language`	`navigator.language` as sent	`en-GB`

Technology

Key	Value	Example
`browser`	Parsed browser name	`Chrome`
`os`	Parsed operating system	`macOS`
`device`	`desktop`, `mobile`, `tablet`, `bot`, `unknown`	`mobile`
`screen`	A bucket label, verbatim	`LG (992-1199px)`

Behaviour

Key	Value	Example
`event`	An event name. Keeps visitors who fired it	`signup_completed`
`propKey`	A property key. Keeps events carrying it	`plan`
`propValue`	Narrows `propKey` to one value. Requires `propKey`	`pro`
`traitKey`	An identify trait key. Keeps everything that visitor did	`plan`
`traitValue`	Narrows `traitKey` to one value. Requires `traitKey`. Matches the string column	`pro`
`goal`	A goal name. Keeps visitors who converted it inside the range	`Signup`

propValue without propKey does nothing. Same for traitValue.

Worked examples

Mobile visitors from Germany, last 7 days:

curl -s -H "Authorization: Bearer tk_live_…" \
  "https://tracing.tools/api/v1/sites/pk_live_a91c3f04/stats?range=7d&country=DE&device=mobile"

Top pages for people who arrived 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&limit=50"

Everything, but only for visitors who converted the Signup goal:

curl -s -H "Authorization: Bearer tk_live_…" \
  --data-urlencode "goal=Signup" \
  --data-urlencode "range=30d" \
  -G "https://tracing.tools/api/v1/sites/pk_live_a91c3f04/stats"

Direct traffic only:

curl -s -H "Authorization: Bearer tk_live_…" \
  --data-urlencode "referrer=Direct / none" \
  -G "https://tracing.tools/api/v1/sites/pk_live_a91c3f04/series?range=30d"

Visitors on the Pro plan, by country:

curl -s -H "Authorization: Bearer tk_live_…" \
  "https://tracing.tools/api/v1/sites/pk_live_a91c3f04/breakdown?dimension=country&traitKey=plan&traitValue=pro"

What a filter does to each metric

Metric	Effect
`visitors`, `pageviews`, `sessions`	Counted over the filtered events
`bounceRate`, `avgVisitMs`, `viewsPerVisit`	Computed over the visits those events belong to
`revenueCents`	Summed over the revenue events among the filtered events

A revenue event belongs to the visit it fired in, so a filter on the visit keeps or drops the event with it. See How attribution works.