# Analytics and Speed Insights

Read a project's visitors and Web Vitals, and turn collection on or off.

Source: https://docs.orbits.africa/api/insights

Analytics and Speed Insights come from the beacons sent by `@useorbits/analytics` and `@useorbits/speed-insights` in your app. Both are part of the Pro plan: on Free, reads answer `enabled: false` with `locked: true`, and turning one on is `402`. See [Analytics](https://docs.orbits.africa/observe/analytics) and [Speed Insights](https://docs.orbits.africa/observe/speed-insights).

Endpoints:

- `GET /v1/teams/{team}/projects/{project}/analytics`: A project's visitors and page views
- `PUT /v1/teams/{team}/projects/{project}/analytics`: Turn Analytics on or off
- `GET /v1/teams/{team}/projects/{project}/analytics/event`: One custom event and its properties
- `GET /v1/teams/{team}/projects/{project}/speed-insights`: A project's Web Vitals from real visits
- `PUT /v1/teams/{team}/projects/{project}/speed-insights`: Turn Speed Insights on or off

## A project's visitors and page views

```http
GET /v1/teams/{team}/projects/{project}/analytics
```

The Analytics page: page views the project's visitors' browsers sent with `@useorbits/analytics` (the edge's `/_orbits/analytics.js`, which sends beacons to `/_orbits/e` on the project's own host), to its production deployments only (not a preview's), over a range against the span before it. `buckets` are the range's hours (`24h`) or Lagos days (`7d`, `30d`), the last one still filling; `previous_buckets` are the span before, in the same order. A visitor is counted once a Lagos day: nothing identifies them across days, and neither their address nor their browser is kept. A bounce is a visitor with one page view. `pages` are by the route the framework named (`/blog/[slug]`, from the Next.js, SvelteKit and Astro components), or else the path with its ids grouped (`/products/8412` is `/products/[id]`). `referrers` are other sites' hosts; `host: null` is a visit nobody linked to. `countries` is empty until the edge looks them up. `events` are custom events (`track()`), most sent first. Lists keep their top ten.

**Permissions:** Any team member. A non-member gets 404.

Token: any API token (`read` or `full`).

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.

Query parameters:

- `range` (string): One of `24h`, `7d`, `30d`. Defaults to `7d`.

Example:

```sh
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/analytics" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "enabled": false,
  "locked": true
}
```

Errors:

- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
- `503`: A store this endpoint reads is unreachable. Try again shortly.
## Turn Analytics on or off

```http
PUT /v1/teams/{team}/projects/{project}/analytics
```

The Analytics page's Enable switch. While it's off, production's hosts don't serve `/_orbits/analytics.js` and page views and events aren't logged; the edge picks a change up within seconds.

Turning it **on** needs Pro: a team on Free gets 402 `plan_required` (feature `analytics`). Turning it off is always allowed.

**Permissions:** Owners, admins and members. Viewers get 403; a non-member gets 404.

Token: a `full` API token.

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.

Body:

- `enabled` (boolean, required)

Example:

```sh
curl -X PUT "https://api.theorbits.app/v1/teams/my-team/projects/my-app/analytics" \
  -H "Authorization: Bearer $ORBITS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'
```

Response `200`:

```json
{
  "enabled": false
}
```

Errors:

- `402`: The team's plan doesn't include this (see `GET /v1/plans`). `code` is `plan_required`, `required_plan` is `pro` and `feature` names what is missing; show the upgrade dialog.
- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
## One custom event and its properties

```http
GET /v1/teams/{team}/projects/{project}/analytics/event
```

A custom event from the Analytics page's `events` (sent with `track(name, properties)`) over a range, production only: how often it was sent, by how many visitors, and its properties, ten at most, each with its ten commonest values. A value that isn't a string is shown as its JSON (`3`, `true`, `null`).

**Permissions:** Any team member. A non-member gets 404.

Token: any API token (`read` or `full`).

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.

Query parameters:

- `name` (string, required): At most 255 characters.
- `range` (string): One of `24h`, `7d`, `30d`. Defaults to `7d`.

Example:

```sh
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/analytics/event?name=my-app" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "enabled": false
}
```

Errors:

- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
- `503`: A store this endpoint reads is unreachable. Try again shortly.
## A project's Web Vitals from real visits

```http
GET /v1/teams/{team}/projects/{project}/speed-insights
```

The Speed Insights page: Web Vitals the project's visitors' browsers measured and sent with `@useorbits/speed-insights` (the edge's `/_orbits/speed-insights.js`) from its production deployments, on one kind of device (`mobile` counts tablets), at the 75th percentile. LCP, INP, FCP and TTFB are milliseconds, CLS a unitless score. `score` is 0 to 100 from the p75s there are, as Lighthouse scores each metric (90 at its good line, 50 at its median) weighted FCP 15%, LCP 30%, INP 30% and CLS 25%; TTFB is shown but not scored; null without any. `lcp` is LCP's p75 by bucket (null where none was measured). `routes` are the most visited, ten at most, by the route the framework named or the path with its ids grouped, with each vital's p75 or null. `targets` are the elements (CSS selectors) most often behind LCP, INP and CLS, five each, with how often and their p75. `connections` are LCP samples by the connection they were measured on.

**Permissions:** Any team member. A non-member gets 404.

Token: any API token (`read` or `full`).

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.

Query parameters:

- `range` (string): One of `24h`, `7d`, `30d`. Defaults to `7d`.
- `device` (string): One of `mobile`, `desktop`. Defaults to `mobile`.

Example:

```sh
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/speed-insights" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "enabled": false,
  "locked": true
}
```

Errors:

- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
- `503`: A store this endpoint reads is unreachable. Try again shortly.
## Turn Speed Insights on or off

```http
PUT /v1/teams/{team}/projects/{project}/speed-insights
```

The Speed Insights page's Enable switch. While it's off, production's hosts don't serve `/_orbits/speed-insights.js` and vitals aren't logged; the edge picks a change up within seconds.

Turning it **on** needs Pro: a team on Free gets 402 `plan_required` (feature `speed_insights`). Turning it off is always allowed.

**Permissions:** Owners, admins and members. Viewers get 403; a non-member gets 404.

Token: a `full` API token.

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.

Body:

- `enabled` (boolean, required)

Example:

```sh
curl -X PUT "https://api.theorbits.app/v1/teams/my-team/projects/my-app/speed-insights" \
  -H "Authorization: Bearer $ORBITS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'
```

Response `200`:

```json
{
  "enabled": false
}
```

Errors:

- `402`: The team's plan doesn't include this (see `GET /v1/plans`). `code` is `plan_required`, `required_plan` is `pro` and `feature` names what is missing; show the upgrade dialog.
- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
