Skip to content

Insights Orbit event API

Read every page view and event a site collected, and send events from your servers.

Two endpoints for your own servers and tools: the raw event API reads what a site collected, and the server API sends events that happen on a server. Both take an Insights Orbit key (ins_live_) as Authorization: Bearer, with the scope to read or to send events. Keep keys on a server, never in a web page or an app.

Each key may read events 60 times a minute and send events 600 times a minute. Over that, the answer is 429 with Retry-After: 60. No other rate limit headers are sent.

Errors are error with a code and a message. No visitor is identified: there is no visitor id, address or browser string in the answers.

Read the guideOpenAPI 3.1 document

Try it settings

https://api.bifrostorbit.com/insights/v1

Insights Orbit keys are secret and belong on a server, so nothing here is sent from the docs.

Try it sends each request straight from your browser to the API. The key stays in this page's memory: it is never saved, never sent to docs.bifrostorbit.com and gone when you leave or reload the page. Only reads are run; anything that changes data is described and never sent.

Raw eventsPage views and events, for your own tools.

Read raw events

GET/eventsKey required

Every page view and event a site collected, oldest first, for a data warehouse or your own tools. Needs a key that reads events and the Growth plan. 60 requests a minute per key. The newest events can take a few seconds to show up.

Parameters

  • sitestringquery, required

    The site's key, from Install.

  • fromstringquery

    A date or a time, such as 2026-10-01. Counts. Without from and to, the last 24 hours.

  • tostringquery

    A date or a time. Doesn't count.

  • namestringquery

    Only events with this name, such as Signed up.

  • typestringquery

    pageview or event.

    One of pageview, event.
  • limitintegerquery

    100 unless you say, at most 1,000.

    At least 1. At most 1000.
  • cursorstringquery

    next from the page before.

Responses

  • 200OKA page of events, oldest first. When next isn't null there are more: ask again with cursor set to it.
    • dataEvent[]

      Fields of data
      • idstring

      • typestring

        One of pageview, event.
      • namestring

        pageview for a page view.

      • atstring

        When it happened.

      • hoststring

      • pathstring

      • referrerstring or null

      • channelstring

        Such as Search.

      • utmmap of string

        The campaign tags, when there were any.

      • countrystring or null

      • devicestring

        desktop, mobile, tablet, or server for server events.

      • browserstring

      • osstring

      • propertiesmap of any or null

        Text, numbers or true or false.

      • revenuenumber or null

      • currencystring or null

      • contentIdstring or null

        The CMS Orbit entry the page belongs to.

      • labelstring or null

      • visitstring

        Events of one visit share it. No visitor is identified.

      • personstringsometimes

        With known users on: a scrambled form of the user id, the same for every event of that person.

    • nextstring or null

      Ask again with cursor set to it until it is null.

  • 400Bad requestA date, type or cursor isn't valid (invalid or invalid_cursor).
    • errorobject

      Fields of error
      • codestring

        unauthorized, wrong_scope, not_in_plan, unknown_site, invalid, invalid_cursor, invalid_json, invalid_events, too_large, rate_limited, not_available or internal.

      • messagestring

  • 401UnauthorisedNo key, or a key that is wrong or removed.
    • errorobject

      Fields of error
      • codestring

        unauthorized, wrong_scope, not_in_plan, unknown_site, invalid, invalid_cursor, invalid_json, invalid_events, too_large, rate_limited, not_available or internal.

      • messagestring

  • 403ForbiddenThe key may only send events (wrong_scope), or the plan doesn't include the API (not_in_plan).
    • errorobject

      Fields of error
      • codestring

        unauthorized, wrong_scope, not_in_plan, unknown_site, invalid, invalid_cursor, invalid_json, invalid_events, too_large, rate_limited, not_available or internal.

      • messagestring

  • 404Not foundNo site with that key in your organisation.
    • errorobject

      Fields of error
      • codestring

        unauthorized, wrong_scope, not_in_plan, unknown_site, invalid, invalid_cursor, invalid_json, invalid_events, too_large, rate_limited, not_available or internal.

      • messagestring

  • 429Too many requestsMore than 60 requests a minute with one key.
    • errorobject

      Fields of error
      • codestring

        unauthorized, wrong_scope, not_in_plan, unknown_site, invalid, invalid_cursor, invalid_json, invalid_events, too_large, rate_limited, not_available or internal.

      • messagestring

  • 500Server errorSomething went wrong on our side. Try again in a moment.
    • errorobject

      Fields of error
      • codestring

        unauthorized, wrong_scope, not_in_plan, unknown_site, invalid, invalid_cursor, invalid_json, invalid_events, too_large, rate_limited, not_available or internal.

      • messagestring

  • 503UnavailableThe event API isn't switched on for this server.
    • errorobject

      Fields of error
      • codestring

        unauthorized, wrong_scope, not_in_plan, unknown_site, invalid, invalid_cursor, invalid_json, invalid_events, too_large, rate_limited, not_available or internal.

      • messagestring

Shell
curl 'https://api.bifrostorbit.com/insights/v1/events?site=nw7k2q9x' \  -H 'Authorization: Bearer ins_live_…'

Try it

Insights Orbit keys are secret and belong on a server.

Example answer

200 OKJSON
{  "data": [    {      "id": "6720f1c2a9e4b1d2c3f40b11",      "type": "pageview",      "name": "pageview",      "at": "2026-11-09T08:14:22.000Z",      "host": "northwilds.com",      "path": "/trips/lofoten-sea-kayaking/",      "referrer": "google.com",      "channel": "Search",      "utm": {},      "country": "NO",      "device": "mobile",      "browser": "Safari",      "os": "iOS",      "properties": null,      "revenue": null,      "currency": null,      "contentId": "6650f1c2a9e4b1d2c3f40a21",      "label": null,      "visit": "c1f9a2e4"    },    {      "id": "6720f1c2a9e4b1d2c3f40b12",      "type": "event",      "name": "Booking started",      "at": "2026-11-09T08:16:05.000Z",      "host": "northwilds.com",      "path": "/trips/lofoten-sea-kayaking/",      "referrer": "google.com",      "channel": "Search",      "utm": {},      "country": "NO",      "device": "mobile",      "browser": "Safari",      "os": "iOS",      "properties": {        "trip": "lofoten-sea-kayaking"      },      "revenue": null,      "currency": null,      "contentId": "6650f1c2a9e4b1d2c3f40a21",      "label": null,      "visit": "c1f9a2e4"    }  ],  "next": "MTc2MjY3NjE2NTAwMF82NzIwZjFjMmE5ZTRiMWQyYzNmNDBiMTI"}

Server eventsEvents from your servers.

Send events from a server

POST/server/eventsKey required

Events that happen on a server, such as a payment your provider confirms, so they count in goals, revenue and monthly events. Needs a key that sends events. Every plan. While the trial or plan has ended, it answers 204 and stores nothing.

Request body

  • sitestringrequired

    Up to 64 characters.
  • eventsobject[]required

    One to 100 events. The whole request can be up to 256 KB.

    Up to 100 items.
    Fields of events
    • idstringoptional

      Your own id, such as the order number. An id already sent for the site in the last eight days is counted once, so you can safely send again.

    • namestringrequired

      The event's name, such as Order paid.

      Up to 120 characters.
    • timestampstring or integeroptional

      When it happened: a time such as 2026-10-21T09:30:00Z or milliseconds since 1970, up to seven days back. Now when left out.

    • urlstringoptional

      The page it belongs to, on one of the site's addresses.

      Up to 2048 characters.
    • propertiesmap of string or number or booleanoptional

      Up to 30 details, each text, a number or true or false.

    • revenuenumberoptional

      Money. Needs currency.

      At least 0.
    • currencystringoptional

      A three-letter code, such as EUR.

    • userIdstringoptional

      Your user id for the person, used only with known users on and kept only scrambled.

      Up to 128 characters.
    • countrystringoptional

      Two letters, such as DE.

Responses

  • 202Taken.
    • dataobject

      Fields of data
      • acceptedinteger

      • repeatedinteger

        Events with an id already sent, counted once.

  • 204No contentThe plan has ended: nothing was stored.
  • 400Bad requestThe body isn't JSON (invalid_json) or the events aren't valid (invalid_events). The message names the field.
    • errorobject

      Fields of error
      • codestring

        unauthorized, wrong_scope, not_in_plan, unknown_site, invalid, invalid_cursor, invalid_json, invalid_events, too_large, rate_limited, not_available or internal.

      • messagestring

  • 401UnauthorisedNo key, or a key that is wrong or removed.
    • errorobject

      Fields of error
      • codestring

        unauthorized, wrong_scope, not_in_plan, unknown_site, invalid, invalid_cursor, invalid_json, invalid_events, too_large, rate_limited, not_available or internal.

      • messagestring

  • 403ForbiddenThe key may only read events.
    • errorobject

      Fields of error
      • codestring

        unauthorized, wrong_scope, not_in_plan, unknown_site, invalid, invalid_cursor, invalid_json, invalid_events, too_large, rate_limited, not_available or internal.

      • messagestring

  • 404Not foundThe site isn't in the key's organisation, or is in the bin.
    • errorobject

      Fields of error
      • codestring

        unauthorized, wrong_scope, not_in_plan, unknown_site, invalid, invalid_cursor, invalid_json, invalid_events, too_large, rate_limited, not_available or internal.

      • messagestring

  • 413Too largeOver 256 KB.
    • errorobject

      Fields of error
      • codestring

        unauthorized, wrong_scope, not_in_plan, unknown_site, invalid, invalid_cursor, invalid_json, invalid_events, too_large, rate_limited, not_available or internal.

      • messagestring

  • 429Too many requestsMore than 600 requests a minute with one key.
    • errorobject

      Fields of error
      • codestring

        unauthorized, wrong_scope, not_in_plan, unknown_site, invalid, invalid_cursor, invalid_json, invalid_events, too_large, rate_limited, not_available or internal.

      • messagestring

  • 500Server errorSomething went wrong on our side. Try again in a moment.
    • errorobject

      Fields of error
      • codestring

        unauthorized, wrong_scope, not_in_plan, unknown_site, invalid, invalid_cursor, invalid_json, invalid_events, too_large, rate_limited, not_available or internal.

      • messagestring

Shell
curl -X POST 'https://api.bifrostorbit.com/insights/v1/server/events' \  -H 'Authorization: Bearer ins_live_…' \  -H 'Content-Type: application/json' \  -d '{"site":"nw7k2q9x","events":[{"id":"order-1042","name":"Order paid","url":"https://northwilds.com/gear/fjell-gtx-boot/","revenue":1890,"currency":"NOK","properties":{"items":2,"shop":"Oslo"}}]}'

Try it

Insights Orbit keys are secret, and it stores real events.

Example answer

202 JSON
{  "data": {    "accepted": 1,    "repeated": 0  }}

SchemasThe shapes the endpoints above answer with and take.

Error

  • errorobject

    Fields of error
    • codestring

      unauthorized, wrong_scope, not_in_plan, unknown_site, invalid, invalid_cursor, invalid_json, invalid_events, too_large, rate_limited, not_available or internal.

    • messagestring

Event

  • idstring

  • typestring

    One of pageview, event.
  • namestring

    pageview for a page view.

  • atstring

    When it happened.

  • hoststring

  • pathstring

  • referrerstring or null

  • channelstring

    Such as Search.

  • utmmap of string

    The campaign tags, when there were any.

  • countrystring or null

  • devicestring

    desktop, mobile, tablet, or server for server events.

  • browserstring

  • osstring

  • propertiesmap of any or null

    Text, numbers or true or false.

  • revenuenumber or null

  • currencystring or null

  • contentIdstring or null

    The CMS Orbit entry the page belongs to.

  • labelstring or null

  • visitstring

    Events of one visit share it. No visitor is identified.

  • personstringsometimes

    With known users on: a scrambled form of the user id, the same for every event of that person.

ServerEvents

  • sitestring

    Up to 64 characters.
  • eventsobject[]

    One to 100 events. The whole request can be up to 256 KB.

    Up to 100 items.
    Fields of events
    • idstringsometimes

      Your own id, such as the order number. An id already sent for the site in the last eight days is counted once, so you can safely send again.

    • namestring

      The event's name, such as Order paid.

      Up to 120 characters.
    • timestampstring or integersometimes

      When it happened: a time such as 2026-10-21T09:30:00Z or milliseconds since 1970, up to seven days back. Now when left out.

    • urlstringsometimes

      The page it belongs to, on one of the site's addresses.

      Up to 2048 characters.
    • propertiesmap of string or number or booleansometimes

      Up to 30 details, each text, a number or true or false.

    • revenuenumbersometimes

      Money. Needs currency.

      At least 0.
    • currencystringsometimes

      A three-letter code, such as EUR.

    • userIdstringsometimes

      Your user id for the person, used only with known users on and kept only scrambled.

      Up to 128 characters.
    • countrystringsometimes

      Two letters, such as DE.