Read reports
Read a property's numbers from the dashboard, or from the API with a bearer token.
Prerequisites
- An account with at least one property.
- For the API: a bearer token in
SA_TOKEN, from the sign-in step in Get a project key. The person signs in, not the agent, and the token lasts 90 days. There are no read-only or per-property tokens yet, so treat it like the password.
In the dashboard
Sign in at analytics.specvista.com/login. Properties lists every property with live visitors and today's pageviews. Choose a property for charts, top pages, sources, devices, countries, events, funnels and people. Tracking shows which properties have gone quiet.
With the API
Every report is a GET under https://analyticsapi.specvista.com/api/v1 with Authorization: Bearer $SA_TOKEN. period is 24h, 7d or 30d; any other value is treated as 30d. Bot traffic, internal traffic (including requests from Apple's network, 17.0.0.0/8) and development builds are excluded everywhere.
- Find the property id:
curl -s https://analyticsapi.specvista.com/api/v1/projects -H "Authorization: Bearer $SA_TOKEN"Expected result: a JSON array of properties with id, name, type and apiKey.
- Read the headline numbers:
curl -s "https://analyticsapi.specvista.com/api/v1/analytics/42/overview?period=7d" -H "Authorization: Bearer $SA_TOKEN"Expected result: total (every event the property has ever received, excluding bot and internal traffic), pageviews, uniqueSessions, liveVisitors, trend (percentage change in pageviews against the previous 7 days) and previous.
Windows PowerShell:
Invoke-RestMethod -Uri "https://analyticsapi.specvista.com/api/v1/analytics/42/overview?period=7d" -Headers @{ Authorization = "Bearer $env:SA_TOKEN" }- Any report in the table below works the same way. For example, the top pages and a signup funnel for the last 7 days:
curl -s "https://analyticsapi.specvista.com/api/v1/analytics/42/top-pages?period=7d" -H "Authorization: Bearer $SA_TOKEN"
curl -s "https://analyticsapi.specvista.com/api/v1/analytics/42/funnel?period=7d&from=signup.started&to=signup.completed" -H "Authorization: Bearer $SA_TOKEN"$headers = @{ Authorization = "Bearer $env:SA_TOKEN" }
Invoke-RestMethod -Uri "https://analyticsapi.specvista.com/api/v1/analytics/42/top-pages?period=7d" -Headers $headers
Invoke-RestMethod -Uri "https://analyticsapi.specvista.com/api/v1/analytics/42/funnel?period=7d&from=signup.started&to=signup.completed" -Headers $headersHow funnels count
A funnel follows each person by userId, or by sessionId when there is no user id. started is the number of people who sent the from event in the period. converted is how many of them sent the to event at or after their first from event. rate is the percentage, to one decimal place. Because the browser script only sends userId after saIdentify, a funnel from an anonymous web event to a backend event only joins up when the web visitor was identified with the same user id the server sends.
Reports
| Question | Endpoint |
|---|---|
| All properties at a glance | /analytics/global?period=7d |
| Headline numbers | /analytics/{id}/overview |
| Pageviews over time | /analytics/{id}/pageviews?granularity=day (or week, month) |
| Top pages | /analytics/{id}/top-pages |
| Where visits start, with bounce rate | /analytics/{id}/landing-pages |
| Custom events | /analytics/{id}/top-events, /analytics/{id}/event-names |
| Conversion between two events | /analytics/{id}/funnel?from=signup.started&to=signup.completed |
| Traffic sources | /analytics/{id}/referrers, /analytics/{id}/channels, /analytics/{id}/utm-campaigns |
| Audience | /analytics/{id}/countries, /analytics/{id}/cities, /analytics/{id}/devices, /analytics/{id}/browsers, /analytics/{id}/os, /analytics/{id}/sources |
| Engagement | /analytics/{id}/bounce-rate, /analytics/{id}/new-vs-returning |
| Identified people | /analytics/{id}/people |
| Latest events | /analytics/{id}/live-events |
| Raw events as CSV | /analytics/{id}/export?period=30d |
| Properties that stopped sending | /analytics/tracking-health |
Response shapes are in the API reference and the OpenAPI document.
Common errors
| Error code | Meaning | Fix |
|---|---|---|
missing_token | No Authorization header | Send Authorization: Bearer $SA_TOKEN |
invalid_token | The token expired or was changed | Ask the person to sign in again |
project_not_found | No property has that id | List properties with GET /projects |
project_forbidden | The property belongs to another account | Use an id from your own GET /projects |
invalid_funnel_events, same_funnel_events | from or to missing, or the same | Pick two different names from /event-names |
Confirm success
The overview call returns status 200 with numbers. A total of 0 means no events have arrived yet; see the tracking guides.