# 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](https://analytics.specvista.com/docs/get-a-project-key.md). 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](https://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.

1. Find the property id:

```bash
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`.

2. Read the headline numbers:

```bash
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:

```powershell
Invoke-RestMethod -Uri "https://analyticsapi.specvista.com/api/v1/analytics/42/overview?period=7d" -Headers @{ Authorization = "Bearer $env:SA_TOKEN" }
```

3. Any report in the table below works the same way. For example, the top pages and a signup funnel for the last 7 days:

```bash
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"
```

```powershell
$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 $headers
```

## How 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](https://analytics.specvista.com/docs/api.md) and the [OpenAPI document](https://analyticsapi.specvista.com/api/v1/openapi.json).

## 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.