OrbitsDocs
esc
    Open Orbits
    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.

    GET/v1/teams/{team}/projects/{project}/analytics
    Read or full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    Query parameters

    • rangestring

      One of 24h, 7d, 30d. Defaults to 7d.

    Response 200

    The page's numbers, or { "enabled": false }.
    • enabledbooleanrequired

      Always true.

    • lockedboolean

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

    • rangestring

      One of 24h, 7d, 30d. Defaults to 7d.

    • bucketsarray of object
      Show 3 child fields
      • startstringrequired
      • visitorsintegerrequired
      • pageviewsintegerrequired
    • previous_bucketsarray of object
      Show 3 child fields
      • startstringrequired
      • visitorsintegerrequired
      • pageviewsintegerrequired
    • totalsInsightsVisits
      Show 4 child fields
      • visitorsintegerrequired
      • pageviewsintegerrequired
      • bounce_ratenumber or nullrequired

        Share of visitors with one page view, 0 to 1; null without visitors.

      • views_per_visitnumber or nullrequired
    • previousInsightsVisits
      Show 4 child fields
      • visitorsintegerrequired
      • pageviewsintegerrequired
      • bounce_ratenumber or nullrequired

        Share of visitors with one page view, 0 to 1; null without visitors.

      • views_per_visitnumber or nullrequired
    • pagesarray of object
      Show 3 child fields
      • routestringrequired
      • visitorsintegerrequired
      • pageviewsintegerrequired
    • referrersarray of object
      Show 2 child fields
      • hoststring or nullrequired
      • visitorsintegerrequired
    • countriesarray of object
      Show 2 child fields
      • countrystringrequired

        ISO 3166-1 alpha-2.

      • visitorsintegerrequired
    • devicesarray of object
      Show 2 child fields
      • devicestringrequired

        One of desktop, mobile, tablet.

      • visitorsintegerrequired
    • eventsarray of object
      Show 3 child fields
      • namestringrequired
      • visitorsintegerrequired
      • countintegerrequired

    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"
    Response 200
    {
      "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.

    PUT/v1/teams/{team}/projects/{project}/analytics
    Full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    Body

    application/json
    • enabledbooleanrequired

    Response 200

    The switch as it now is.
    • enabledbooleanrequired

    Errors

    • 402The 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.
    • 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
      }'
    Response 200
    {
      "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.

    GET/v1/teams/{team}/projects/{project}/analytics/event
    Read or full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    Query parameters

    • namestringrequired

      At most 255 characters.

    • rangestring

      One of 24h, 7d, 30d. Defaults to 7d.

    Response 200

    The event, or { "enabled": false }.
    • enabledbooleanrequired

      Always true.

    • rangestring

      One of 24h, 7d, 30d. Defaults to 7d.

    • namestring
    • countinteger
    • visitorsinteger
    • propertiesarray of object
      Show 3 child fields
      • keystringrequired
      • countintegerrequired
      • valuesarray of objectrequired
        Show 2 child fields
        • valuestringrequired
        • countintegerrequired

    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"
    Response 200
    {
      "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.

    GET/v1/teams/{team}/projects/{project}/speed-insights
    Read or full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    Query parameters

    • rangestring

      One of 24h, 7d, 30d. Defaults to 7d.

    • devicestring

      One of mobile, desktop. Defaults to mobile.

    Response 200

    The page's numbers, or { "enabled": false }.
    • enabledbooleanrequired

      Always true.

    • lockedboolean

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

    • rangestring

      One of 24h, 7d, 30d. Defaults to 7d.

    • devicestring

      One of mobile, desktop.

    • visitsinteger

      Page views on the device.

    • scoreinteger or null

      From 0 to 100.

    • vitalsarray of object

      The vitals measured, in the order LCP, INP, CLS, FCP, TTFB.

      Show 3 child fields
      • namestringrequired

        One of LCP, INP, CLS, FCP, TTFB.

      • p75numberrequired
      • samplesintegerrequired
    • lcparray of object
      Show 2 child fields
      • startstringrequired
      • p75number or nullrequired
    • routesarray of object
      Show 5 child fields
      • routestringrequired
      • visitsintegerrequired
      • lcpnumber or nullrequired
      • inpnumber or nullrequired
      • clsnumber or nullrequired
    • targetsarray of object
      Show 4 child fields
      • namestringrequired

        One of LCP, INP, CLS.

      • targetstringrequired
      • samplesintegerrequired
      • p75numberrequired
    • connectionsarray of object
      Show 2 child fields
      • connectionstringrequired

        One 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"
    Response 200
    {
      "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.

    PUT/v1/teams/{team}/projects/{project}/speed-insights
    Full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    Body

    application/json
    • enabledbooleanrequired

    Response 200

    The switch as it now is.
    • enabledbooleanrequired

    Errors

    • 402The 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.
    • 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
      }'
    Response 200
    {
      "enabled": false
    }

    Was this page helpful?

    Updated