Skip to main content
TroopyDocs
GuidesSet up and use TroopyAppsConnect your servicesAPIThe API, the CLI and MCPChangelogEach update to Troopy

Developers

Account

Troop

Skills

Tasks and projects

Needs you

Routines and triggers

Brain

Docs

Canvas

Email

CRM

Outreach

Customers

Analytics

Sessions

Surveys

Support Agent

Tests and incidents

Disputes

Apps

Vault

Computer

Open Troopy
Troopy

API reference / Analytics

Get a breakdown of visitors

A period's visitors in groups by one dimension, most visitors first. The dimensions are sources (channels, referrers, campaigns, utm_*, ref, source, via), pages (pages, entry_pages, exit_pages, exit_links, hostnames), location (countries, regions, cities, languages), devices (browsers, os, devices, screens), goals, properties and weekday_hours. Sources, location and device come from the first page of each session. An exit page is the last page of a session. A screen is mobile, tablet, laptop or desktop, by its width. A language is a code such as en. Pages also give the average time in view and the depth of reading. properties gives the names of the properties of goals, and with property, the values of one. weekday_hours groups the sessions by the time they started, in the time zone of the workspace: 1-09 is Monday from 9:00 to 10:00, and 7-23 is Sunday from 23:00.

get/api/v1/analytics/breakdown/{dimension}

Authorization

HeaderAuthorization: Bearer <API key>
Or the headerX-API-Key: <API key>
API keyMake one in Troopy under Settings > API keys. It acts as you, in its workspace.
Scopesanalytics:read

Other ways to call it

CLItroopy analytics breakdown
MCP tooltroopy_get_analytics_breakdown
Rate limit240 calls in 60 seconds, for each key

Path parameters

dimension*enum<string>

channelsreferrerscampaignsutm_sourceutm_mediumutm_termutm_contentrefsourceviapagesentry_pagesexit_pagesexit_linkshostnamescountriesand 10 more

Query parameters

periodenum<string>

now is the last 10 minutes. 7d and 30d end today. 3m, 6m and 12m are whole months that end with this month. week starts on Monday. custom needs from and to

nowtodayyesterday24h7d30d3m6m12mweekmonthyearallcustom

Default "30d"

fromstring

YYYY-MM-DD, in the workspace's time zone

date

tostring

YYYY-MM-DD. The period includes this day

date

compareenum<string>

Also gives another window: previous is the window just before, with the same length. year is the same days a year before. custom is compare_from to compare_to

previousyearcustom

compare_fromstring

With compare custom: the first day of the other window

date

compare_tostring

With compare custom: the last day of the other window

date

filter_channelstring

channel: op:value[,value]. The op is is, is_not, contains, does_not_contain, matches (a regular expression) or does_not_match. No op means is. More values mean any of them. (none) matches an empty value, as for direct traffic

At most 500 characters

filter_referrerstring

referrer: op:value[,value]. The op is is, is_not, contains, does_not_contain, matches (a regular expression) or does_not_match. No op means is. More values mean any of them. (none) matches an empty value, as for direct traffic

At most 500 characters

filter_utm_sourcestring

utm source: op:value[,value]. The op is is, is_not, contains, does_not_contain, matches (a regular expression) or does_not_match. No op means is. More values mean any of them. (none) matches an empty value, as for direct traffic

At most 500 characters

filter_utm_mediumstring

utm medium: op:value[,value]. The op is is, is_not, contains, does_not_contain, matches (a regular expression) or does_not_match. No op means is. More values mean any of them. (none) matches an empty value, as for direct traffic

At most 500 characters

filter_utm_campaignstring

utm campaign: op:value[,value]. The op is is, is_not, contains, does_not_contain, matches (a regular expression) or does_not_match. No op means is. More values mean any of them. (none) matches an empty value, as for direct traffic

At most 500 characters

filter_utm_termstring

utm term: op:value[,value]. The op is is, is_not, contains, does_not_contain, matches (a regular expression) or does_not_match. No op means is. More values mean any of them. (none) matches an empty value, as for direct traffic

At most 500 characters

filter_utm_contentstring

utm content: op:value[,value]. The op is is, is_not, contains, does_not_contain, matches (a regular expression) or does_not_match. No op means is. More values mean any of them. (none) matches an empty value, as for direct traffic

At most 500 characters

filter_refstring

ref: op:value[,value]. The op is is, is_not, contains, does_not_contain, matches (a regular expression) or does_not_match. No op means is. More values mean any of them. (none) matches an empty value, as for direct traffic

At most 500 characters

filter_sourcestring

source: op:value[,value]. The op is is, is_not, contains, does_not_contain, matches (a regular expression) or does_not_match. No op means is. More values mean any of them. (none) matches an empty value, as for direct traffic

At most 500 characters

filter_viastring

via: op:value[,value]. The op is is, is_not, contains, does_not_contain, matches (a regular expression) or does_not_match. No op means is. More values mean any of them. (none) matches an empty value, as for direct traffic

At most 500 characters

filter_pagestring

page: op:value[,value]. The op is is, is_not, contains, does_not_contain, matches (a regular expression) or does_not_match. No op means is. More values mean any of them. (none) matches an empty value, as for direct traffic

At most 500 characters

filter_entry_pagestring

entry page: op:value[,value]. The op is is, is_not, contains, does_not_contain, matches (a regular expression) or does_not_match. No op means is. More values mean any of them. (none) matches an empty value, as for direct traffic

At most 500 characters

filter_exit_pagestring

exit page: op:value[,value]. The op is is, is_not, contains, does_not_contain, matches (a regular expression) or does_not_match. No op means is. More values mean any of them. (none) matches an empty value, as for direct traffic

At most 500 characters

filter_hostnamestring

hostname: op:value[,value]. The op is is, is_not, contains, does_not_contain, matches (a regular expression) or does_not_match. No op means is. More values mean any of them. (none) matches an empty value, as for direct traffic

At most 500 characters

filter_countrystring

country: op:value[,value]. The op is is, is_not, contains, does_not_contain, matches (a regular expression) or does_not_match. No op means is. More values mean any of them. (none) matches an empty value, as for direct traffic

At most 500 characters

filter_regionstring

region: op:value[,value]. The op is is, is_not, contains, does_not_contain, matches (a regular expression) or does_not_match. No op means is. More values mean any of them. (none) matches an empty value, as for direct traffic

At most 500 characters

filter_citystring

city: op:value[,value]. The op is is, is_not, contains, does_not_contain, matches (a regular expression) or does_not_match. No op means is. More values mean any of them. (none) matches an empty value, as for direct traffic

At most 500 characters

filter_languagestring

language: op:value[,value]. The op is is, is_not, contains, does_not_contain, matches (a regular expression) or does_not_match. No op means is. More values mean any of them. (none) matches an empty value, as for direct traffic

At most 500 characters

filter_browserstring

browser: op:value[,value]. The op is is, is_not, contains, does_not_contain, matches (a regular expression) or does_not_match. No op means is. More values mean any of them. (none) matches an empty value, as for direct traffic

At most 500 characters

filter_osstring

os: op:value[,value]. The op is is, is_not, contains, does_not_contain, matches (a regular expression) or does_not_match. No op means is. More values mean any of them. (none) matches an empty value, as for direct traffic

At most 500 characters

filter_devicestring

device: op:value[,value]. The op is is, is_not, contains, does_not_contain, matches (a regular expression) or does_not_match. No op means is. More values mean any of them. (none) matches an empty value, as for direct traffic

At most 500 characters

filter_screenstring

screen: op:value[,value]. The op is is, is_not, contains, does_not_contain, matches (a regular expression) or does_not_match. No op means is. More values mean any of them. (none) matches an empty value, as for direct traffic

At most 500 characters

filter_goalstring

goal: op:value[,value]. The op is is, is_not, contains, does_not_contain, matches (a regular expression) or does_not_match. No op means is. More values mean any of them. (none) matches an empty value, as for direct traffic

At most 500 characters

filter_propertystring

Visitors who sent a goal with a property: op:name=value[,name=value], such as is:plan=pro. The op is one of is, is_not, contains, does_not_contain, matches and does_not_match

At most 500 characters

filter_visit_countstring

Sessions by the visitor's visit number: is:1 (new), gte:2 (returning), lte, is_not

At most 500 characters

propertystring

With dimension properties: the property whose values to give, such as plan

attributionenum<string>

Sources only. last credits the source of each visit. first credits the source of the first visit of each visitor

lastfirst

Default "last"

pageinteger

1-based page number

Default 1 · At least 1

limitinteger

Rows per page, at most 1,000

Default 100 · At least 1 · At most 1000

Response

200 · application/json
data*array<object>
7 properties
value*string | null

null when there is no value, for example no referrer (direct traffic) or an unknown country

visitors*integer
count*integer

Pageviews. For goals, completions. For exit links, clicks

revenue*number

Attributed revenue, in minor units

conversionRate*number

Share of the row's visitors who paid, 0 to 1

timeOnPageinteger | null

Pages only: the average time in view of a visitor, in seconds

scrollDepthinteger | null

Pages only: how far down a visitor read the page on average, 0 to 100

pagination*object
4 properties
page*integer
limit*integer
total*integer
pages*integer

Errors

400 invalid_inputFix the field named in detail. Each operation's schema is in /api/v1/openapi.json.
401 unauthorizedSend an API key as `Authorization: Bearer tr_live_...`. Create one in Troopy under Settings.
403 forbiddenThe key lacks a scope this operation needs, or its owner lacks the role. detail says which; create a key with the scope, or ask an organization owner or admin.
404 not_foundCheck the path and any id in it. Every operation is listed in /api/v1/openapi.json.
429 rate_limitedWait the number of seconds in Retry-After, then retry.