Suggestions

close search

Add Messaging, Voice, and Authentication to your apps with Nexmo APIs

Visit Nexmo

Insights Dashboard & API

The OpenTok Insights API is a GraphQL API. You can use the Insights API and the Insights Dashboard to obtain information about your OpenTok projects and sessions.

The Insights Dashboard

The Insights Dashboard widget provides data at the project level. You can navigate to it by logging into your TokBox account and selecting an OpenTok project. It contains three tabs: usage, quality, and errors, as well as filters for date range, location, and endpoints. Quality and error tabs are available for Growth and Enterprise plans, while the usage tab is present for all users.

The usage tab shows different types of minutes that the project generated. You can see a map of where minutes were generated, and stack multiple filters as you please. The quality tab provides a histogram of video bitrate and latency for streams within the project. Finally, the errors tab provides the error rate of connections, publishers, and subscribers. Each tab's data is filtered by the selections made at the top.

Insights API, Base URL, and Authentication

The Insights API is a GraphQL API that allows you to explore your sessions' metadata at the project and session level. GraphQL is an alternative to the typical REST approach of accessing data over HTTP. It was developed by Facebook in 2012, and open-sourced in 2015. Check out GraphQL's getting started guide to learn more.

The Insights API is currently in public beta. In this period, Session APIs are free to use, and Project APIs correspond to the level of access you have in your dashboard. Just like the dashboard, Growth and Enterprise accounts will have access to quality and errors data. Because the API is in Beta it is subject to change. If you see any discrepencies in the documentation or have questions, contact us at insightsbeta@tokbox.com

The base URL for the API is:

https://insights.opentok.com/graphql

All requests are made as HTTP POSTs and authenticated using X-OPENTOK-AUTH

Exploring the API Schema With GraphiQL

Navigating to https://insights.opentok.com/ using your browser takes you to the Insights instance of GraphiQL, a tool that lets you explore the GraphQL API schema. Because the tool can make API requests, you must be logged in to use it.

There are five window panes in this tool:

ProjectData and SessionData Fields

In the GraphiQL Explorer, navigate through the schema to Query > Project. You'll see fields with response types ProjectData and SessionData. These are top-level objects that address different levels of granularity of the API.

The projectData field returns the ProjectData object, which provides aggregate report data at the project level. You have the option to filter and group data by the SDK type, SDK version, country, region, browser, or browser version. Currently, all data under this object is updated nightly, so you won't see live changes to the data.

The sessionData field returns the SessionData object. This provides data at the granularity of each individual session. You can obtain summaries of a session, which includes the number of users connected, publishing, and subscribing. Or you can go deeper into the session to obtain more precise information about these.

A new concept introduced with the Insights API is an OpenTok meetings. If a session is reused, it will have different information for each occurance. To help separate these instances of the session, OpenTok has seperate meetings within the session. The end of a meeting is when there are no connections in the session for at least 10 minutes. Each meeting ID corresponds to one meeting within the session.

Making Requests

All requests are made to the same base URL, https://insights.opentok.com/graphql, as HTTP POSTs with X-OPENTOK-AUTH as the authentication. The content-type is application/json. The POST body will contain a JSON object containing one key and one value. The key will be query, and the value will be the JSON-like string that you constructed using the GraphiQL tool.

As an example, try pasting the following curl command in your terminal. Make sure you replace values for the YOUR_OT_JWT and YOUR_OT_API_KEY variables. To obtain these, see the REST API authentication documentation and log into your TokBox account. For this example, we've used a simple POST body that should return streamed subscribed minutes over the last 10 days.

YOUR_OT_API_KEY=12345678                 # Enter your api key
YOUR_OT_JWT=ValidJwtToken                # Enter a valid JWT token corresponding to your API key

OT_START_DATE=$(($(date +%s)-864000))    # generates epoch time from 10 days ago

# POST body that returns streamed subscribed minutes from the OT_START_DATE
OT_DATA='{"query":"{project(projectId:'${YOUR_OT_API_KEY}'){projectData(start:\"'$OT_START_DATE'\"){resources{usage{streamedSubscribedMinutes}}}}}"}'

curl -X POST \
-H "Content-Type: application/json" \
-H "X-OPENTOK-AUTH:$YOUR_OT_JWT" \
-d $OT_DATA \
'https://insights.opentok.com/graphql'

Response Objects

Response objects adhere to the GraphQL schema and are JSON-formatted, but they only include fields you specify in your requests. The curl example above will result in a response object like the following:


{  
  "data":{  
    "project":{  
      "projectData":{  
        "resources":[  
          {  
            "usage":{  
              "streamedSubscribedMinutes":3189
            }
          }
        ]
      }
    }
  }
}

The easiest way to see a preview of what to expect is by adding different filters, groups, and fields to the GraphiQL explorer, and observing the resonse. If you have any questions or find errors in this guide, email us at insightsbeta@tokbox.com.