Read-only, programmatic access to your own analytics aggregates: dashboards of dashboards, internal reporting, spreadsheets. Everything the API returns is aggregate data your dashboard already shows; the privacy architecture (no cookies, no visitor identifiers, hour precision) holds by construction.
Create an API key in Settings, then send it as a Bearer token. Keys are account-wide and stored hashed on our side; the full key is shown once, at creation.
curl -H "Authorization: Bearer $ILLUMINO_API_KEY" https://illumino.app/api/v1/sitesSession cookies are ignored on /api/v1 routes, and API keys are not accepted anywhere else. The API is served without CORS headers: call it from your servers, not from browsers, so your key never ships to a client.
| Behaviour | Detail |
|---|---|
| Methods | GET only. Anything else returns 405. |
| Rate limit | 60 requests per minute per key. Over the limit returns 429 with a Retry-After header. |
| Errors | JSON envelope: {"error": "...", "status": 401}. Codes: 400, 401, 403, 404, 405, 429. |
| Date range | from and to are UTC dates (YYYY-MM-DD), both inclusive. Default: the last 7 days. Max range: 365 days. |
| Row limits | List endpoints accept limit (default 20, max 100). |
| Endpoint | Returns |
|---|---|
GET /api/v1/sites | The sites on your account: id, domain, created_at. |
GET /api/v1/sites/{id}/stats | Pageviews, unique visitors, sessions, views per session for the range. |
GET /api/v1/sites/{id}/timeseries | Pageviews over time. interval=day (default) or hour; hourly data exists for the last 7 days only (raw hits are deleted after 7 days by design). |
GET /api/v1/sites/{id}/pages | Top pages by views. |
GET /api/v1/sites/{id}/referrers | Top referrer domains (hostname only, never full URLs). |
GET /api/v1/sites/{id}/countries | Top countries by views. |
GET /api/v1/sites/{id}/devices | Views by device type (desktop, mobile, tablet). |
GET /api/v1/sites/{id}/events | Custom event counts by event name. |
GET /api/v1/sites/{id}/entry-pages | Top entry pages with entry counts. |
GET /api/v1/sites/{id}/exit-pages | Top exit pages with exit counts. |
GET /api/v1/sites/{id}/observation-report | The complete versioned, deduplicated JSON report across all active privacy-safe site datasets. |
curl -H "Authorization: Bearer $ILLUMINO_API_KEY" \
"https://illumino.app/api/v1/sites/YOUR_SITE_ID/observation-report?from=2026-07-01&to=2026-07-31"The response declares its schema version, privacy posture, completeness by source and the unique key for every array. Repeated observations are represented by counts, never duplicate records. The complete JSON is also visible in the Observations dashboard tab.
curl -H "Authorization: Bearer $ILLUMINO_API_KEY" \
"https://illumino.app/api/v1/sites/YOUR_SITE_ID/stats?from=2026-06-01&to=2026-06-30"{
"site_id": "YOUR_SITE_ID",
"domain": "example.com",
"from": "2026-06-01",
"to": "2026-06-30",
"pageviews": 48210,
"visitors": 17904,
"sessions": 21455,
"views_per_session": 2.25
}curl -H "Authorization: Bearer $ILLUMINO_API_KEY" \
"https://illumino.app/api/v1/sites/YOUR_SITE_ID/timeseries?interval=day&from=2026-06-24&to=2026-06-30"{
"metric": "pageviews",
"interval": "day",
"from": "2026-06-24",
"to": "2026-06-30",
"points": [
{ "t": "2026-06-24", "value": 1650 },
{ "t": "2026-06-25", "value": 1721 }
]
}curl -H "Authorization: Bearer $ILLUMINO_API_KEY" \
"https://illumino.app/api/v1/sites/YOUR_SITE_ID/pages?limit=5"{
"from": "2026-07-01",
"to": "2026-07-07",
"pages": [
{ "path": "/", "views": 4210 },
{ "path": "/pricing", "views": 1288 }
]
}The API is versioned in the path. Within v1, changes are additive only: new endpoints and new response fields may appear; nothing is removed or renamed. A breaking change means a new /api/v2 namespace. When a version is ever deprecated, we will announce it on this page well ahead of any change; we do not promise specific support timelines.