API reference · ObserveAnalytics
Analytics and Speed Insights
Read a project's visitors and Web Vitals, and turn collection on or off.
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 and Speed Insights.
A project's visitors and page views
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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.
Query parameters
rangestringOne of
24h,7d,30d. Defaults to7d.
Response 200
The page's numbers, or{ "enabled": false }.enabledbooleanrequiredAlways
true.lockedbooleanPresent when the team's plan doesn't include this page (Free). Show the upgrade state; nothing is read, and what was collected is kept for when the team is on Pro.
Always
true.rangestringOne of
24h,7d,30d. Defaults to7d.bucketsarray of objectShow 3 child fieldsHide child fields
startstringrequiredvisitorsintegerrequiredpageviewsintegerrequired
previous_bucketsarray of objectShow 3 child fieldsHide child fields
startstringrequiredvisitorsintegerrequiredpageviewsintegerrequired
totalsInsightsVisitsShow 4 child fieldsHide child fields
visitorsintegerrequiredpageviewsintegerrequiredbounce_ratenumber or nullrequiredShare of visitors with one page view, 0 to 1; null without visitors.
views_per_visitnumber or nullrequired
previousInsightsVisitsShow 4 child fieldsHide child fields
visitorsintegerrequiredpageviewsintegerrequiredbounce_ratenumber or nullrequiredShare of visitors with one page view, 0 to 1; null without visitors.
views_per_visitnumber or nullrequired
pagesarray of objectShow 3 child fieldsHide child fields
routestringrequiredvisitorsintegerrequiredpageviewsintegerrequired
referrersarray of objectShow 2 child fieldsHide child fields
hoststring or nullrequiredvisitorsintegerrequired
countriesarray of objectShow 2 child fieldsHide child fields
countrystringrequiredISO 3166-1 alpha-2.
visitorsintegerrequired
devicesarray of objectShow 2 child fieldsHide child fields
devicestringrequiredOne of
desktop,mobile,tablet.visitorsintegerrequired
eventsarray of objectShow 3 child fieldsHide child fields
namestringrequiredvisitorsintegerrequiredcountintegerrequired
Errors
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 422Validation failed, or the Idempotency-Key was reused with a different body.
- 503A store this endpoint reads is unreachable. Try again shortly.
Every code is explained in Errors.
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/analytics" \
-H "Authorization: Bearer $ORBITS_TOKEN"{
"enabled": false,
"locked": true
}Turn Analytics on or off
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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.
Body
application/jsonenabledbooleanrequired
Response 200
The switch as it now is.enabledbooleanrequired
Errors
- 402The team's plan doesn't include this (see
GET /v1/plans).codeisplan_required,required_planisproandfeaturenames what is missing; show the upgrade dialog. - 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 422Validation failed, or the Idempotency-Key was reused with a different body.
Every code is explained in Errors.
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
}'{
"enabled": false
}One custom event and its properties
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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.
Query parameters
namestringrequiredAt most 255 characters.
rangestringOne of
24h,7d,30d. Defaults to7d.
Response 200
The event, or{ "enabled": false }.enabledbooleanrequiredAlways
true.rangestringOne of
24h,7d,30d. Defaults to7d.namestringcountintegervisitorsintegerpropertiesarray of objectShow 3 child fieldsHide child fields
keystringrequiredcountintegerrequiredvaluesarray of objectrequiredShow 2 child fieldsHide child fields
valuestringrequiredcountintegerrequired
Errors
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 422Validation failed, or the Idempotency-Key was reused with a different body.
- 503A store this endpoint reads is unreachable. Try again shortly.
Every code is explained in Errors.
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/analytics/event?name=my-app" \
-H "Authorization: Bearer $ORBITS_TOKEN"{
"enabled": false
}A project's Web Vitals from real visits
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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.
Query parameters
rangestringOne of
24h,7d,30d. Defaults to7d.devicestringOne of
mobile,desktop. Defaults tomobile.
Response 200
The page's numbers, or{ "enabled": false }.enabledbooleanrequiredAlways
true.lockedbooleanPresent when the team's plan doesn't include this page (Free). Show the upgrade state; nothing is read, and what was collected is kept for when the team is on Pro.
Always
true.rangestringOne of
24h,7d,30d. Defaults to7d.devicestringOne of
mobile,desktop.visitsintegerPage views on the device.
scoreinteger or nullFrom 0 to 100.
vitalsarray of objectThe vitals measured, in the order LCP, INP, CLS, FCP, TTFB.
Show 3 child fieldsHide child fields
namestringrequiredOne of
LCP,INP,CLS,FCP,TTFB.p75numberrequiredsamplesintegerrequired
lcparray of objectShow 2 child fieldsHide child fields
startstringrequiredp75number or nullrequired
routesarray of objectShow 5 child fieldsHide child fields
routestringrequiredvisitsintegerrequiredlcpnumber or nullrequiredinpnumber or nullrequiredclsnumber or nullrequired
targetsarray of objectShow 4 child fieldsHide child fields
namestringrequiredOne of
LCP,INP,CLS.targetstringrequiredsamplesintegerrequiredp75numberrequired
connectionsarray of objectShow 2 child fieldsHide child fields
connectionstringrequiredOne of
4g,3g,2g,slow-2g.samplesintegerrequired
Errors
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 422Validation failed, or the Idempotency-Key was reused with a different body.
- 503A store this endpoint reads is unreachable. Try again shortly.
Every code is explained in Errors.
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/speed-insights" \
-H "Authorization: Bearer $ORBITS_TOKEN"{
"enabled": false,
"locked": true
}Turn Speed Insights on or off
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.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.
Body
application/jsonenabledbooleanrequired
Response 200
The switch as it now is.enabledbooleanrequired
Errors
- 402The team's plan doesn't include this (see
GET /v1/plans).codeisplan_required,required_planisproandfeaturenames what is missing; show the upgrade dialog. - 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 422Validation failed, or the Idempotency-Key was reused with a different body.
Every code is explained in Errors.
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
}'{
"enabled": false
}