Read data

Stats API

Get your site's stats in your own tools, like internal reports or status pages. The API returns the same numbers as your dashboard.

Best for: Developers
Prerequisites: An API key and access to the site.

Create an API key

Every request needs an API key. A key can only read the sites its creator has access to.

Owners and admins can create keys under API keys. Keys are only shown once, so copy yours and store it securely.

Endpoint

Returns visitors, pageviews and time on page for a site and date range.

HTTP

GET https://staging.pebbleanalytics.io/api/v1/stats

Parameters

AuthorizationheaderRequired: Bearer followed by your API key.
sitetextRequired: The site's domain, such as fieldnotes.blog.
rangetoday, 7d, 30d, 12m or 3y: Date range, ending today, in UTC. Defaults to 30d.
filtersJSON: Groups of [dimension, value] pairs. Pairs in a group are combined with OR, and groups with AND. For example, [[["country","DE"],["country","FR"]],[["device","mobile"]]] returns visitors from Germany or France on mobile. Dimensions: page, referrer, country, device, browser, channel, utm_source, utm_medium, utm_campaign, utm_term, utm_content, event and event_property. Defaults to no filters.

Example request

Stats for fieldnotes.blog over the last 7 days.

Shell

curl "https://staging.pebbleanalytics.io/api/v1/stats?site=fieldnotes.blog&range=7d" \
  -H "Authorization: Bearer YOUR_KEY"

JSON200 OK

{
  "site": "fieldnotes.blog",
  "range": { "from": "2026-09-22", "to": "2026-09-28" },
  "visitors": 4739,
  "pageViews": 9012,
  "medianSecondsOnPage": 102
}

Response fields

sitetext: The site's domain.
range{ from, to }: First and last day of the range.
visitorsnumber: Unique visitors, counted once per day.
pageViewsnumber: Total pageviews.
medianSecondsOnPagenumber: Median time on page, in seconds.

Errors

Error responses

401Unauthorized: Missing, invalid or revoked API key.
400Bad Request: Invalid parameter. The response's field names the parameter.
403Forbidden: The key doesn't have access to this site, or the site doesn't exist.
429Too Many Requests: Rate limit reached: 600 requests per key per clock hour (UTC). The Retry-After header gives the seconds until it resets.