UsherStats Docs Contents usherstats.com Start free

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.

RouteScope
GET /v1/stats/catalogueanalytics:read
GET /v1/sites/{id}/statsanalytics:read
POST /v1/sites/{id}/stats/queryanalytics:read
POST /v1/sites/{id}/stats/batchanalytics:read
GET /v1/sites/{id}/summaryanalytics:read
GET /v1/sites/{id}/top/{dimension}analytics:read
GET /v1/statsanalytics:read
POST /v1/stats/queryanalytics:read
POST /v1/stats/batchanalytics:read
GET /v1/summaryanalytics:read
POST /v1/sites/{id}/internal-linksites: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) or internal (your own team). Each metric set has a default.
  • days (calendar days ending today; 1 is today so far, default 7), or from and to (YYYY-MM-DD).
  • compare: true adds previous, 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 as sessions or pageviews.

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: google on 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 site and hostname, so /about on two sites is two rows;
  • bySite: true keeps every site's rows apart instead, each with site and hostname;
  • sites (a list of ids; sites=id,id in a query string) narrows the read to some of the workspace's sites. Any other site is 404, 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.

View this page as Markdown