Analytics
Every figure in the dashboard comes from one query catalogue, and the API exposes it as it is: you name a metric set, a dimension and a few numbers, and UsherStats writes the query. There is no SQL to send and nothing to escape. The dashboard reads through these same routes.
All of them need the analytics:read scope. A site in another workspace, or outside a token's site restriction, is
404.
| Route | Scope |
|---|---|
GET /v1/stats/catalogue | analytics:read |
GET /v1/sites/{id}/stats | analytics:read |
POST /v1/sites/{id}/stats/query | analytics:read |
POST /v1/sites/{id}/stats/batch | analytics:read |
GET /v1/sites/{id}/summary | analytics:read |
GET /v1/sites/{id}/top/{dimension} | analytics:read |
GET /v1/stats | analytics:read |
POST /v1/stats/query | analytics:read |
POST /v1/stats/batch | analytics:read |
GET /v1/summary | analytics:read |
POST /v1/sites/{id}/internal-link | sites:write |
The examples assume $US_TOKEN holds a token with account:admin. First, a site to read:
curl https://api.usherstats.com/v1/sites \
-H "Authorization: Bearer $US_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "Field notes", "hostnames": ["fieldnotes.example"]}'The catalogue
Four metric sets: pageviews (confirmed pageviews in a browser), sessions, requests (everything your server or
proxy answered, crawlers included) and events. Each lists its lanes (human, bot, internal), the dimensions
it can be broken down by, the filters it takes and the counts it can sort by.
curl https://api.usherstats.com/v1/stats/catalogue \
-H "Authorization: Bearer $US_TOKEN"One query
A spec is metrics and by, plus any of:
lane:human(People),bot(Crawlers) orinternal(your own team). Each metric set has a default.days(calendar days ending today;1is today so far, default7), orfromandto(YYYY-MM-DD).compare:trueaddsprevious, the period before (a single day is compared with the same weekday a week earlier), or says why it cannot be compared yet.where: filters, such as{"source": "google"}. In a query string,where.source=google.sort: which count a table is ranked by, such assessionsorpageviews.
Analytics Engine keeps 90 days; past that, UsherStats answers from the daily rollups each site keeps for as long as the account exists. Hourly series and page-to-page pairs are not rolled up, so they answer only within 90 days.
curl "https://api.usherstats.com/v1/sites/$SITE_ID/stats?metrics=pageviews&by=source&days=30&sort=sessions" \
-H "Authorization: Bearer $US_TOKEN"The same as JSON (the form an agent's tool call takes):
curl https://api.usherstats.com/v1/sites/$SITE_ID/stats/query \
-H "Authorization: Bearer $US_TOKEN" \
-H "Content-Type: application/json" \
-d '{"metrics": "requests", "by": "bot", "lane": "bot", "days": 7, "compare": true}'A name that is not on the catalogue's lists is 400, and field says which:
curl "https://api.usherstats.com/v1/sites/$SITE_ID/stats?metrics=pageviews&by=blob3" \
-H "Authorization: Bearer $US_TOKEN"Many queries at once
Up to 40 named specs in one call. A spec that is refused answers {"error": {"status": 400, "title": ...}} under
its name; the others still answer.
curl https://api.usherstats.com/v1/sites/$SITE_ID/stats/batch \
-H "Authorization: Bearer $US_TOKEN" \
-H "Content-Type: application/json" \
-d '{"queries": {"byDay": {"metrics": "pageviews", "by": "day", "days": 30}, "crawlers": {"metrics": "requests", "by": "category"}}}'The People summary
The People boxes as numbers: sessions, pageviews, from search, average session, bounce rate, single-page visits and
pages per session, each with the previous period's figure and the change. A change carries a tone: good or bad
where one direction is better (a lower bounce rate is better), flat when nothing moved.
curl "https://api.usherstats.com/v1/sites/$SITE_ID/summary?days=7" \
-H "Authorization: Bearer $US_TOKEN"Top tables
source, medium, referrer, campaign, page, page_type, country and device count People sessions (where
each began) or, with count=pageviews, pageviews. bot, category, kind, network, path, status, cache and
decision count requests; event counts events.
curl "https://api.usherstats.com/v1/sites/$SITE_ID/top/page?days=30&count=pageviews&limit=20" \
-H "Authorization: Bearer $US_TOKEN"curl "https://api.usherstats.com/v1/sites/$SITE_ID/top/bot?days=7" \
-H "Authorization: Bearer $US_TOKEN"All sites
The same reads over every site of the workspace at once -- for a token restricted to some sites, over those. Each site is answered as a single-site read is (its own settings, and its imported history from its rollups), then:
- counts are summed, and every average and rate (seconds per pageview, pages per session, bounce, single-page visits, average session) is worked out again from the summed parts, never averaged across sites;
- a table is merged by its key:
googleon two sites is one row; - a key that belongs to one site (a page path, a page type, a page-to-page pair, a session's depth row, a crawled
path) keeps its site: each such row carries
siteandhostname, so/abouton two sites is two rows; bySite: truekeeps every site's rows apart instead, each withsiteandhostname;sites(a list of ids;sites=id,idin a query string) narrows the read to some of the workspace's sites. Any other site is404, as it is everywhere else.
The answer lists the sites it covers (sites, each with its hostname and which store answered which days), and
with compare the previous period is the sites that have one: a site whose records begin later had no traffic then.
A sessions total carries metrics, the session figures of all the sites together, and each site's own in sites.
An all-sites read costs its query units once per site, at most 1,600 a request; past that, name fewer sites.
curl "https://api.usherstats.com/v1/stats?metrics=pageviews&by=source&days=30" \
-H "Authorization: Bearer $US_TOKEN"curl https://api.usherstats.com/v1/stats/query \
-H "Authorization: Bearer $US_TOKEN" \
-H "Content-Type: application/json" \
-d '{"metrics": "sessions", "by": "total", "days": 7, "compare": true}'curl https://api.usherstats.com/v1/stats/batch \
-H "Authorization: Bearer $US_TOKEN" \
-H "Content-Type: application/json" \
-d '{"queries": {"pages": {"metrics": "pageviews", "by": "page"}, "crawl": {"metrics": "requests", "by": "total", "lane": "bot", "bySite": true}}, "sites": ["'$SITE_ID'"]}'The People summary of every site together, with every site's row for the range -- pageviews, sessions, pages per session, bounce rate, single-page visits, average session and crawl requests, sorted by pageviews. A site with no data is still a row: for a site launched this week, silence is the answer.
curl "https://api.usherstats.com/v1/summary?days=7" \
-H "Authorization: Bearer $US_TOKEN"Marking your own browser
Your team's visits belong in Internal, not People. Tools mark themselves with a signed header; a browser is marked
by opening a link on your site's own first-party path (/_us/, which the Worker SDK and the first-party proxy set
up). The link works for ten minutes, once per browser you open it in, and the mark lasts 90 days. POST /v1/sites/{id}/internal-link/rotate replaces the site's internal key, so every
browser marked before stops counting as yours (mark them again).
The dashboard does this for you. Opening it in a browser marks that browser on every verified hostname of every
site in the workspace, one link after another, and comes back to the page you opened; it renews the mark every 30
days and marks a hostname verified later the next time you open the dashboard. The line under the menu says whether
this browser is marked; its page (/mark) unmarks it on every hostname, and it then stays unmarked until you mark it
again there. It needs the sites:write scope, and a site's Worker SDK or proxy at this release or later (older ones
redeem the link and stop on the site's home page).
The link is made only for a hostname the site has verified (its TXT record, see sites) or serves in proxy mode: it sets a cookie on that domain. Verify it first:
curl -X POST https://api.usherstats.com/v1/sites/$SITE_ID/hostnames/fieldnotes.example/verify \
-H "Authorization: Bearer $US_TOKEN"curl https://api.usherstats.com/v1/sites/$SITE_ID/internal-link \
-H "Authorization: Bearer $US_TOKEN" \
-H "Content-Type: application/json" \
-d '{"hostname": "fieldnotes.example"}'See also goals and experiments, bot protection, search and export.