Skip to content

Data Export API

The data export api is responsible for providing a way of fetching raw data in the form of player events and sessions.

Using the API

The main way of using the API is by providing either a customer or a customer/business unit and a time period. The API will then return a streamed response that can be consumed in any way the user sees fit.

There are five endpoints provided by the API, all accessed using a GET request (or a GET and POST request for the limited sessions endpoint):

/v1/export/customer/{customer_name}/events for raw event data corresponding to an entire customer.
/v1/export/customer/{customer_name}/business_unit/{business_unit}/events for raw event data corresponding to a specific business unit.
/v1/export/customer/{customer_name}/sessions for session summaries corresponding to an entire customer.
/v1/export/customer/{customer_name}/business_unit/{business_unit}/sessions for session summaries corresponding to a specific business unit.
/v1/export/customer/{customer_name}/business_unit/{business_unit}/sessions/limited for a limited session summaries, with some filter functionality.

In order to select the time period the start and end query parameters are provided, these are required in order to make a request and should be provided in ISO 8601 standard.

After making a request to one of the above endpoints the API will return the response as a data stream (for limited export there is also an option for a non-streaming response), and therefore the client fetching the data will need to consume it as a stream in order to avoid any potential memory problems. The data returned by the api will consist json objects separated by a new line. Do note that since the Analytics pipeline at Red Bee is constantly evolving to suit new needs the information in events and session summaries might changed over time. Due to this a exported record might contain several empty fields, this is usually an indcation that these fields are no longer ingested into the analytics database but kept for legacy reasons. In the same vein, due to the evolving nature of the analytics pipeline we do note guarantee any sort of backwards compatability in case the data structure changes.

Limited session export

Sometimes you might not be interested in a complete data dump and instead want to fetch individual sessions from a specific user or asset. In that case you can use the limited sessions export which comes with some basic filtering functionality. In this case you can use the limited sessions export functionality. When sending in filters a POST request should be used instead of a regular GET.

The export takes start and end query paramters in order to select a time period. In addition to this limit can also be provided (default is 10, maximum is 100) which tells the API how many records to return. The order of the records returned will be from newest to oldest. In order to filter for a specific user or asset id, one or more filters can be supplied as a request body.

By putting this together the following request can be made:

/v1/export/customer/FantasticTV/business_unit/FantasticContent/sessions/limited?start=2022-01-01&end=2022-02-01&limit=10
{
    "filters": {
        "user.meta.account_id" : ["user1"]
    }
}

This would fetch the last 10 sessions played for the user with the id user1.

The following filters are available when using the endpoint:

Name Description
content.asset.id String uniquely identifying the content in our system
user.meta.id String uniquely identifying the user in our system
user.meta.account_id String uniquely identifying the account in our system
viewing.meta.started Flag to show only sessions that started playback, as in recieved a frame of video content

The repsonse returned from the limited export will be a json with all the sessions in a list

{
    "data" : [
        records-go-here
    ]
}
The api can also be set to return the data as a streaming response, this is done by including the query parameter as_json (default is True). If this is set to false then the response returned from the api will be sent as a stream of records instead.

Data dumps

By using the API you can retrieve two types of data dumps. Raw Player Events and Session Summaries, these will be described below.

Player Events

These events are the raw events sent in from our player SDK, each event describes some sort of behaviour in the player during a playback session. More information about these events can be found here. In addition to this the events will contain some data added by the backend (usually denoted in lower case).

Session Summaries

Whenever a player starts playing some media (or attempts to start playing) a number of events will be created to describe the players behaviour during that playback, these are the events described above. Those events are then aggregated into a session summary, these session summaries are used as the basis for most of our analytics reports. A single session summary will describe a single playback session by a single user.