Suggestions

close search

Insights REST API — Beta

This guide will help programmatically obtain information about your Projects with the Insights API. It will cover:

You must be either on our Growth or Enterprise plans to use this API. If you aren't, and would still like to get access, contact us. The API is currently Beta and subject to change. Check back here for the latest info. If you see any discrepencies in these docs contact us at insightsbeta@tokbox.com

Base URL and Authentication

The base URL for the API is:

https://insights.opentok.com/

All Responses are authenticated using X-OPENTOK-AUTH

From there, there are three different resources that can be queried:

Making Requests

Each endpoint includes the your project's API_KEY as a path parameter. Additionally, they take the following required query parameters:

The /project/{API_KEY}/quality endpoint also has the required parameter:

additionally, all endpoints have the following optional query parameters that can be used as filters. These will filter out for the values you specify

As an example, try pasting the following curl command in your terminal. Make sure you replace {YOUR_JWT_TOKEN} and {API_KEY}. Check out our authentication page for the JWT and your Account Dashboard for the API Key.

curl --header "X-OPENTOK-AUTH:{YOUR_JWT_TOKEN}" 'https://insights.opentok.com/project/{API_KEY}/usage?start=1514793600&end=1523342588&groupBy=monthly&country=us&sdkType=js&browser=chrome'

Response Objects

All responses have the same base response object:


{
    totalCount:    integer indicating the total count matching this request,
    accountId:    integer matching your account ID,
    projectId:    integer matching your OpenTok API key,
    start:        integer epoch time of the start date in seconds,
    end:        integer epoch time of the end date in seconds,
    filters:     Object containing the filters on the response,
    groupBy:     Object containing the interval grouping of the response,
    items:         Array containing the data returned
}
    

From there each response has a different set of data in the items object.

Usage Endpoint

The items in the usage endpoint contain your usage data in minutes, which will look like:


[
    {
        "intervalStart": "2018-01-01T08:00:00.000Z",
        "intervalEnd": "2018-01-31T08:00:00.000Z",
        "usageAmount": {
            "streamedSubscribed": 203.5,
            "streamedPublished": 100.7,
            "broadcastCompositionMinutes": 15.7,
            "hlsMinutes": 480.5,
            "sipUserMinutes": 10.2,
            "composedArchiveMinutes": 80.9,
            "individualArdchiveMinutes": 14
        }
    }
]

Quality Endpoint

The items in the quality endpoint returns your quality data. This will be different mattering on if you passed in average or distribution in your dataType query parameter. Bitrates are in kbps, while latency is in milliseconds.

If you passed in average you will receive an object that looks like:


[
    {
        "intervalStart": "2018-01-01T08:00:00.000Z",
        "intervalEnd": "2018-01-31T08:00:00.000Z",
        "widgetType": "Publisher",
        "videoBitrateAvg": "757.47",
        "latencyAvg": "73.57"
    },
    {
        "intervalStart": "2018-01-01T08:00:00.000Z",
        "intervalEnd": "2018-01-31T08:00:00.000Z",
        "widgetType": "Subscriber",
        "videoBitrateAvg": "500.88"
    }
]

If you passed in distribution you will receive an object that looks like the code snippet blow. Just like the average, the bitrates are in kbps and latencies in milliseconds. Note that each bucket refers to streams with the listed quality down to the bucket below it. As an example the video_vitrate_600 bucket shows how many streams had bitrates between 500kbps and 600kbps.


[
    {
        "intervalStart": "2018-01-01T08:00:00.000Z",
        "intervalEnd": "2018-01-31T08:00:00.000Z",
        "widgetType": "Publisher",
        "videoBitrateDistribution": {
            "video_bitrate_100": "82",
            "video_bitrate_200": "41",
            "video_bitrate_300": "68",
            "video_bitrate_400": "32",
            "video_bitrate_500": "41",
            "video_bitrate_600": "56",
            "video_bitrate_700": "17",
            "video_bitrate_800": "17",
            "video_bitrate_900": "44",
            "video_bitrate_1000": "42",
            "video_bitrate_1200": "26",
            "video_bitrate_1400": "29",
            "video_bitrate_1600": "25",
            "video_bitrate_1800": "12",
            "video_bitrate_2000": "16",
            "video_bitrate_2250": "44",
            "video_bitrate_2500": "15",
            "video_bitrate_2750": "0",
            "video_bitrate_3000": "0",
            "video_bitrate_3000_plus": "0"
        },
        "latencyDistribution": {
            "latency_ms_50": "1442",
            "latency_ms_100": "893",
            "latency_ms_200": "330",
            "latency_ms_300": "64",
            "latency_ms_400": "26",
            "latency_ms_500": "19",
            "latency_ms_600": "6",
            "latency_ms_700": "4",
            "latency_ms_800": "3",
            "latency_ms_900": "3",
            "latency_ms_1000": "3",
            "latency_ms_1000_plus": "6"
        }
    }
]

Errors Endpoint

The items in the errors endpoint contain your error data. GUIDS are unique endpoints, like a browser or mobile device, while widgets correspond to instances of an action. This means is that if in a given day a user on a mobile device has 5 connection attempts and 2 connection errors, they will have 1 guid_connect_attempts and 1 guid_connect_failures. On the other hand, they will have 5 widget_connect_attempts and 2 widget_connect_failures. A sample response will look like:


[
    {
        "intervalStart": "2018-01-01T08:00:00.000Z",
        "intervalEnd": "2018-01-31T08:00:00.000Z",
        "errorMetrics": {
            "guid_connect_attempts": "240",
            "guid_connect_failures": "6",
            "guid_publish_attempts": "22",
            "guid_publish_failures": "1",
            "guid_subscribe_attempts": "208",
            "guid_subscribe_failures": "8",
            "widget_connect_attempts": "395",
            "widget_connect_failures": "12",
            "widget_publish_attempts": "64",
            "widget_publish_failures": "0",
            "widget_subscribe_attempts": "843",
            "widget_subscribe_failures": "17"
        }
    }
]