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.

The Usage tab is available for all users, while the Quality and Errors tabs require the Advanced Insights add-on.

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.

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 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:

Obtaining Project Data

The projectData field of the project object returns the ProjectData object, which provides aggregate report data at the project level.

You must include a start date for the query. This value can be an ISO-8601 format string (such as "2019-10-15T23:43:34.023Z") or an Int value representing an epoch timestamp. Integers of 10 digits or less represent epoch seconds. Integers of more than 10 digits represent epoch milliseconds.

The ProjectData object includes a resources property, which is an array of Metric objects. You have the option to filter and group data by the SDK type, SDK version, country, region, browser, or browser version. Additionally, you have the option to change the Interval in which you want to segment the data (either DAILY, WEEKLY, or MONTHLY). Note that if you set the Interval, you will only see time intervals that have data. Currently, all data under this object is updated nightly, so you won't see live changes to the data.

The Metric object includes information on the country, region (US state, if applicable), OpenTok SDK type and version, as well browser and browser version (if applicable) for the results. The Metric object also includes the following properties:

The following query requests ProjectData results that include streamed published minutes and streamed subscribed minutes for clients using the OpenTok JavaScript, Android, and iOS SDKs:

{
  project(projectId: 12345678) {
    projectData(
      start: "2019-05-01T07:00:00.000Z",
      interval: MONTHLY,
      sdkType: [JS, ANDROID, IOS],
      groupBy: SDK_TYPE
    ) {
      resources {
        intervalStart,
        intervalEnd,
        usage {
          streamedPublishedMinutes,
          streamedSubscribedMinutes
        }
      }
    }
  }
}

Note that by setting the start parameter to 0, you will query for results starting with the earliest records available.

Obtaining Session Data (Advanced Insights)

Important: Session data queries are available to Advanced Insights customers only.

The sessionData field of the project object returns the SessionData object. This object includes two fields: sessions and sessionSummaries.

The sessions field returns a Sessions object. Pass in the session IDs as the sessionIds argument (an array of matching strings). The Sessions object includes a resources property, which is an array of Session objects. The Session object has the following properties:

The following query requests some publisher details on two OpenTok sessions:

{
    project(projectId: 12345678) {
      sessionData {
            sessions(sessionIds: [
                "1_MX4xMDB-fjE1Mzg4NzA0MjExNDd-VjRuSWhpn4",
                "2_MX4xMDB-fjE1Mzg4NzA0OTQzOTN-RFFxeXfcn4"
            ]) {
                resources {
                    sessionId
                    meetings {
                        totalCount
                        resources {
                            createdAt
                            publisherMinutes
                            destroyedAt
                            publishers {
                                resources {
                                    createdAt
                                    destroyedAt
                                }
                            }
                        }
                    }
                }
            }
        }
    }    
}

The sessionSummaries field is an array of SessionSummary objects (one for each session matching the query). The SessionSummary object includes a resources property, which is an array of MeetingSummary objects (one for each meeting in the session). The MeetingSummary object includes information on the number of total and concurrent streams, connections, and subscribers in the meeting.

The following query requests partial SessionSummary results:

 {
     project(projectId: 12345678) {
         sessionData {
             sessionSummaries (
                 start: "2019-05-01T07:00:00.000Z",
             ) {
                 resources {
                     sessionId
                     meetings {
                         resources {
                             maxConcurrentStreams
                             maxConcurrentStreams
                             maxConcurrentSubscribers
                             totalStreams
                             totalConnections
                         }
                    }
                }
            }
        }
    }
}

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 OpenTok GraphiQL explorer, and observing the response.

Using Pagination in Queries

Both the projectData() and sessionData() APIs accept pagination options for all the methods that return lists (arrays). All of these methods implement a ResourceCollection interface that contain the following optional properties:

The pageInfo object (returned for each list) includes the following properties:

For example, the following query returns pagination info along with the first 10 matching ProjectData resources:

{
  project(projectId: 100) {
    projectData(
      start: "2019-05-01T07:00:00.000Z",
      first: 10,
      interval: MONTHLY,

    ) {
      pageInfo {
        hasNextPage
        endCursor
      }
      resources {
        usage {
          streamedPublishedMinutes
        }
      }
    }
  }
}

The response includes pagination information:

{
  "data": {
    "project": {
      "projectData": {
        "pageInfo": {
          "hasNextPage": true,
          "endCursor": "aW5zaWdodHMtcmVzb3VyY2U6MTA="
        },
        "resources": [
          {
            "usage": {
              "streamedPublishedMinutes": 56554.83333333332
            }
          },
                    ...

Use the endCursor value from this response ("aW5zaWdodHMtcmVzb3VyY2U6MTA==") as the endCursor input used in the query to obtain the next page of matching records:

{
  project(projectId: 100) {
    projectData(
      start: 0,
      first: 10,
      interval: MONTHLY,
      endCursor: "aW5zaWdodHMtcmVzb3VyY2U6MTA"

    ) {
      pageInfo {
        hasNextPage
        endCursor
      }
      resources {
        usage {
          streamedPublishedMinutes,
          streamedSubscribedMinutes
        }
      }
    }
  }
}

Error codes

Errors are included in the response, in an errors array, like the following:

"errors": [
  {
    "message": "You must provide a valid project ID.",
    "locations": [
      {
        "line": 2,
        "column": 3
      }
    ],
    "path": [
      "project"
    ],
    "errorCode": 1008
  }
]

The following table lists the error codes and descriptions. See the message property of the error for more details.

Error code Error description
1000 Invalid API key provided.
1001 No valid authentication was provided.
1002 Invalid date range.
1003 Invalid parameter. Only one date interval is allowed.
1004 Invalid parameters.
1005 Invalid parameter.
1006 Invalid parameter. The value must be an integer.
1007 Invalid parameter for specifying an OpenTok SDK version number. The format required is 0.0.0.
1008 You must provide a valid project ID.
1009 Invalid parameter.
1010 Invalid parameter passed in. The parameter accepts only one value.
1011 Invalid token.
1012 Internal server error.
1013 A mandatory parameter is missing.
1014 The specified query requires the Advanced Insights add-on. See OpenTok pricing.
1015 The specified project ID was not found.
1016 The session has expired.
1017 The specified session was not found.
1018 You must provide at least one session ID in the input array.
1019 The token does not match the API key.
1020 Unable to validate the token.
1021 You are not authorized to view data from this project.
1022 Type error. See details in the message string.

Making POST Requests to the OpenTok GraphQL API

All OpenTok GraphQL requests are made to https://insights.opentok.com/graphql.

Set the content-type to application/json.

All requests require authentication using an X-OPENTOK-AUTH header. Set this header to a JWT token with project as the ist and the the OpenTok project ID as the iss. Sign the token the OpenTok project secret. See Authentication.

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 GraphQL string (such as one) you construct using the GraphiQL tool).

The following curl command makes a GraphQL query to obtain streamed subscribed minutes:

YOUR_OT_PROJECT_API_KEY=12345678         # Enter your project API key
YOUR_OT_JWT=ValidJwtToken                # Enter a valid JWT token corresponding
                                         # to your project API key

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

# GraphQL query to obtain streamed subscribed minutes from the start date
GRAPHQL_QUERY='{project
  (projectId:'${YOUR_OT_PROJECT_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 '{"query":"$GRAPHQL_QUERY"}' \
'https://insights.opentok.com/graphql'

Replace values for the YOUR_OT_JWT and YOUR_OT_PROJECT_API_KEY variables. To obtain these, see the REST API authentication documentation and log into your TokBox account.

The example above will result in a response object like the following:

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

Sample App and More Sample Queries

The insights-dashboard-sample project at GitHub is a Node application that uses the OpenTok Insights API to graphically display information on OpenTok projects. It also includes a number of sample GraphQL queries.