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.
OpenAPI reference
Every endpoint, parameter and response schema, with a built-in “Try it” console. The raw OpenAPI 3.1 document works with Postman, Insomnia and client generators.
Quick start
- In the dashboard, open Settings → API tokens and create a token. Copy it right away — it is only shown once.
- List your sites to find the numeric
idof the site you want:
curl https://api.invoker.app/api/v1/sites \ -H "Authorization: Bearer YOUR_API_TOKEN"
- 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/orstats: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.
| Parameter | Description |
|---|---|
period | today, 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_to | Custom range as YYYY-MM-DD, both inclusive, at most 366 days. Sending them implies period=custom. |
timezone | IANA 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"
| Filter | Matches |
|---|---|
page | Page path. A trailing * matches a prefix: /blog/* |
hostname | Hostname, case-insensitive |
source | Referrer domain as returned by the sources breakdown (e.g. google.com, Direct / None) |
referrer | Full referrer URL |
utm_source, utm_medium, utm_campaign, utm_term, utm_content | UTM values |
country | ISO 3166-1 alpha-2 code, e.g. US |
region, city | Region / city name as returned by the breakdowns |
device, browser, os | Case-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."] }
}
}| Status | Code | Meaning |
|---|---|---|
| 401 | unauthenticated | Missing, malformed, expired or revoked token |
| 403 | missing_ability | The token lacks the ability the endpoint needs (sites:read / stats:read) |
| 403 | site_not_allowed | The token is restricted to other sites |
| 403 | plan_without_api_access | Your plan does not include API access |
| 404 | not_found | Unknown endpoint, or a site that doesn't exist or you can't access |
| 422 | validation_failed | Invalid parameters; details per parameter in error.errors |
| 429 | rate_limited | Too many requests; wait Retry-After seconds |
| 500 | server_error | Something went wrong on our side; retry later |
Endpoints
/sitessites:read.| Parameter | Description |
|---|---|
page | Page number (default 1) |
per_page | Sites per page (default 50, max 100) |
curl https://api.invoker.app/api/v1/sites \ -H "Authorization: Bearer YOUR_API_TOKEN"
/sites/{site}sites:read.curl https://api.invoker.app/api/v1/sites/42 \ -H "Authorization: Bearer YOUR_API_TOKEN"
/sites/{site}/stats/aggregatestats:read.| Parameter | Description |
|---|---|
period | today, 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_to | Custom range as YYYY-MM-DD, both inclusive, at most 366 days. Sending them implies period=custom. |
timezone | IANA 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. |
compare | previous 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"
/sites/{site}/stats/timeseriesstats:read.| Parameter | Description |
|---|---|
period | today, 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_to | Custom range as YYYY-MM-DD, both inclusive, at most 366 days. Sending them implies period=custom. |
timezone | IANA 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. |
interval | hour, 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"
/sites/{site}/stats/breakdown/{property}stats:read.| property | Row key | Values |
|---|---|---|
pages | page | Pages by visitors, with visits and pageviews |
entry_pages | page | First page of each visit (visitors, visits) |
exit_pages | page | Last page of each visit (visitors, visits) |
hostnames | hostname | Hostnames (useful when one site spans several domains) |
sources | source | Referrer domains, with Direct / None for visits without a referrer |
referrers | referrer | Full referrer URLs |
utm_sources | utm_source | utm_source values (also utm_mediums, utm_campaigns, utm_terms, utm_contents) |
countries | country | ISO 3166-1 alpha-2 country codes, with country_name |
regions | region | Regions, with their country code |
cities | city | Cities, with region and country code |
devices | device | Desktop, Mobile, Tablet or Bot |
browsers | browser | Browser names |
operating_systems | os | Operating systems |
events | event | Custom event names (events, visitors) |
goals | goal | Goal codes (conversions, visitors, revenue in currency units) |
| Parameter | Description |
|---|---|
period | today, 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_to | Custom range as YYYY-MM-DD, both inclusive, at most 366 days. Sending them implies period=custom. |
timezone | IANA 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. |
limit | Rows per page (default 100, max 1000) |
page | Page 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"
/sites/{site}/realtime/visitorsstats: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"
Sending data instead?
Pageviews and events are recorded by the tracking script, not this API — see Events, Goals and the JavaScript SDK. For full raw exports use Data Export.
/api/v1 responses, but existing fields won't be removed or renamed. Questions or missing endpoints? Contact us.