Skip to content
Developers

Stats API

Read your sites and analytics from scripts, spreadsheets, internal dashboards and AI agents with a personal API token. The API is read-only, versioned and returns JSON.

Quick start

  1. In the dashboard, open Settings → API tokens and create a token. Copy it right away — it is only shown once.
  2. List your sites to find the numeric id of the site you want:
curl https://api.invoker.app/api/v1/sites \
  -H "Authorization: Bearer YOUR_API_TOKEN"
  1. Ask for stats:
curl "https://api.invoker.app/api/v1/sites/42/stats/aggregate?period=30d&compare=previous" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Base URL

https://api.invoker.app/api/v1

All endpoints are GET requests and return JSON. In paths, {site} is the numeric site id from GET /sites (also shown under Site settings → API access), not the tracking ID in your snippet.

Authentication

Send your personal API token as a bearer token in the Authorization header of every request:

Authorization: Bearer YOUR_API_TOKEN

When you create a token you choose:

  • Permissions — sites:read (list and read sites) and/or stats:read (aggregate, timeseries, breakdowns and realtime).
  • Sites — every site you can access (including ones added later), or only selected sites.
  • Expiration — 30 days, 90 days, 1 year or never.

Tokens are stored hashed, show when they were last used, and can be revoked at any time from the same page. API tokens only work with the /api/v1 endpoints on this page: they can't change your account, billing, team or sites. Keep them secret — use them from servers and scripts, never in browser code or public repositories.

Responses

Successful responses have a data member with the result and a meta member that echoes how the request was interpreted — the resolved period, date_from, date_to, timezone and filters for stats, and pagination for lists. Timestamps are ISO 8601, dates are YYYY-MM-DD, durations are seconds and rates are percentages.

{
  "data": { "visitors": 1840, "visits": 2311, "pageviews": 5120, ... },
  "meta": {
    "site_id": 42,
    "period": "30d",
    "date_from": "2026-10-11",
    "date_to": "2026-11-09",
    "timezone": "Europe/Berlin",
    "filters": {}
  }
}

Date ranges and timezones

All stats endpoints accept the same parameters. Periods are whole days in the requested timezone and include today where relevant, so 7d is today and the 6 days before it.

ParameterDescription
periodtoday, yesterday, 7d, 14d, 30d (default), 90d, 6mo, 12mo, month (this month so far), last_month, year (this year so far) or custom.
date_from, date_toCustom range as YYYY-MM-DD, both inclusive, at most 366 days. Sending them implies period=custom.
timezoneIANA timezone for day boundaries and buckets, e.g. Europe/Berlin. Defaults to the site's timezone (see timezone in the site object), else UTC.
filters[name]Only count matching hits, e.g. filters[country]=US. See Filters.

Filters

Narrow any stats endpoint with filters[name]=value. Separate several values with | to match any of them, and combine different filters to match all of them. Filters apply to individual hits: with filters[page]=/pricing, pageviews and visitors only count hits on /pricing.

curl -G "https://api.invoker.app/api/v1/sites/42/stats/aggregate" \
  --data-urlencode "filters[page]=/blog/*" \
  --data-urlencode "filters[country]=US|CA" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
FilterMatches
pagePage path. A trailing * matches a prefix: /blog/*
hostnameHostname, case-insensitive
sourceReferrer domain as returned by the sources breakdown (e.g. google.com, Direct / None)
referrerFull referrer URL
utm_source, utm_medium, utm_campaign, utm_term, utm_contentUTM values
countryISO 3166-1 alpha-2 code, e.g. US
region, cityRegion / city name as returned by the breakdowns
device, browser, osCase-insensitive, e.g. mobile, Chrome, iOS

Pagination

GET /sites takes page and per_page (max 100). Breakdowns take page and limit (default 100, max 1000). Both return meta.pagination with the total number of rows and has_more; keep requesting the next page while has_more is true.

Rate limits

Requests are limited per token per minute, depending on your plan. Every response includes X-RateLimit-Limit and X-RateLimit-Remaining. Over the limit you get a 429 with a Retry-After header (seconds): wait that long, then retry. Results are cached for up to a minute (longer for ranges that have ended), so polling faster than that doesn't return fresher data.

async function invoker(path) {
  for (let attempt = 0; attempt < 5; attempt++) {
    const res = await fetch(`https://api.invoker.app/api/v1${path}`, {
      headers: { Authorization: `Bearer ${process.env.INVOKER_API_TOKEN}` },
    })
    if (res.status !== 429) {
      const body = await res.json()
      if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`)
      return body
    }
    const wait = Number(res.headers.get("Retry-After") ?? 60)
    await new Promise((resolve) => setTimeout(resolve, wait * 1000))
  }
  throw new Error("Rate limited")
}

Errors

Errors use one shape. Branch on error.code; error.message is meant for humans.

HTTP/1.1 422 Unprocessable Content

{
  "error": {
    "status": 422,
    "code": "validation_failed",
    "message": "The selected period is invalid.",
    "errors": { "period": ["The selected period is invalid."] }
  }
}
StatusCodeMeaning
401unauthenticatedMissing, malformed, expired or revoked token
403missing_abilityThe token lacks the ability the endpoint needs (sites:read / stats:read)
403site_not_allowedThe token is restricted to other sites
403plan_without_api_accessYour plan does not include API access
404not_foundUnknown endpoint, or a site that doesn't exist or you can't access
422validation_failedInvalid parameters; details per parameter in error.errors
429rate_limitedToo many requests; wait Retry-After seconds
500server_errorSomething went wrong on our side; retry later

Endpoints

GET/sites
Sites you own or were invited to (only the token's sites if it is restricted), ordered by name. Requires sites:read.
ParameterDescription
pagePage number (default 1)
per_pageSites per page (default 50, max 100)
curl https://api.invoker.app/api/v1/sites \
  -H "Authorization: Bearer YOUR_API_TOKEN"
GET/sites/{site}
A single site. Requires sites:read.
curl https://api.invoker.app/api/v1/sites/42 \
  -H "Authorization: Bearer YOUR_API_TOKEN"
GET/sites/{site}/stats/aggregate
Headline metrics for a date range: unique visitors, visits (sessions), pageviews, views per visit, bounce rate (% of visits with one pageview) and average visit duration in seconds. Requires stats:read.
ParameterDescription
periodtoday, yesterday, 7d, 14d, 30d (default), 90d, 6mo, 12mo, month (this month so far), last_month, year (this year so far) or custom.
date_from, date_toCustom range as YYYY-MM-DD, both inclusive, at most 366 days. Sending them implies period=custom.
timezoneIANA timezone for day boundaries and buckets, e.g. Europe/Berlin. Defaults to the site's timezone (see timezone in the site object), else UTC.
filters[name]Only count matching hits, e.g. filters[country]=US. See Filters.
compareprevious adds the same number of days right before the range, and the % change per metric (null when the previous value is 0).
curl "https://api.invoker.app/api/v1/sites/42/stats/aggregate?period=30d&compare=previous" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
GET/sites/{site}/stats/timeseries
Visitors, visits, pageviews and custom events per time bucket. Every bucket in the range is returned; empty ones are zeros. Requires stats:read.
ParameterDescription
periodtoday, yesterday, 7d, 14d, 30d (default), 90d, 6mo, 12mo, month (this month so far), last_month, year (this year so far) or custom.
date_from, date_toCustom range as YYYY-MM-DD, both inclusive, at most 366 days. Sending them implies period=custom.
timezoneIANA timezone for day boundaries and buckets, e.g. Europe/Berlin. Defaults to the site's timezone (see timezone in the site object), else UTC.
filters[name]Only count matching hits, e.g. filters[country]=US. See Filters.
intervalhour, day, week (starting Monday) or month. Defaults to hour for ranges up to 2 days, else day. Hourly series are limited to 7 days. Hourly dates are ISO 8601 datetimes with the timezone offset.
curl "https://api.invoker.app/api/v1/sites/42/stats/timeseries?period=7d&interval=day&timezone=America/New_York" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
GET/sites/{site}/stats/breakdown/{property}
Top values of a property, sorted by visitors (entry/exit pages by visits, events by count, goals by conversions). Requires stats:read.
propertyRow keyValues
pagespagePages by visitors, with visits and pageviews
entry_pagespageFirst page of each visit (visitors, visits)
exit_pagespageLast page of each visit (visitors, visits)
hostnameshostnameHostnames (useful when one site spans several domains)
sourcessourceReferrer domains, with Direct / None for visits without a referrer
referrersreferrerFull referrer URLs
utm_sourcesutm_sourceutm_source values (also utm_mediums, utm_campaigns, utm_terms, utm_contents)
countriescountryISO 3166-1 alpha-2 country codes, with country_name
regionsregionRegions, with their country code
citiescityCities, with region and country code
devicesdeviceDesktop, Mobile, Tablet or Bot
browsersbrowserBrowser names
operating_systemsosOperating systems
eventseventCustom event names (events, visitors)
goalsgoalGoal codes (conversions, visitors, revenue in currency units)
ParameterDescription
periodtoday, yesterday, 7d, 14d, 30d (default), 90d, 6mo, 12mo, month (this month so far), last_month, year (this year so far) or custom.
date_from, date_toCustom range as YYYY-MM-DD, both inclusive, at most 366 days. Sending them implies period=custom.
timezoneIANA timezone for day boundaries and buckets, e.g. Europe/Berlin. Defaults to the site's timezone (see timezone in the site object), else UTC.
filters[name]Only count matching hits, e.g. filters[country]=US. See Filters.
limitRows per page (default 100, max 1000)
pagePage number (default 1)
curl "https://api.invoker.app/api/v1/sites/42/stats/breakdown/sources?period=30d&limit=5" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
GET/sites/{site}/realtime/visitors
Unique visitors seen in the last 5 minutes (cached for up to 15 seconds). Requires stats:read.
curl https://api.invoker.app/api/v1/sites/42/realtime/visitors \
  -H "Authorization: Bearer YOUR_API_TOKEN"

More examples

Top pages last month (Python)

import os, requests

res = requests.get(
    "https://api.invoker.app/api/v1/sites/42/stats/breakdown/pages",
    params={"period": "last_month", "limit": 10},
    headers={"Authorization": f"Bearer {os.environ['INVOKER_API_TOKEN']}"},
    timeout=30,
)
res.raise_for_status()
for row in res.json()["data"]:
    print(row["page"], row["visitors"])

Mobile visitors from the US this week

curl -G "https://api.invoker.app/api/v1/sites/42/stats/aggregate" \
  --data-urlencode "period=7d" \
  --data-urlencode "filters[country]=US" \
  --data-urlencode "filters[device]=mobile" \
  -H "Authorization: Bearer YOUR_API_TOKEN"