Suggestions

close search

Add Messaging, Voice, and Authentication to your apps with Vonage Communications APIs

Visit the Vonage API Developer Portal

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

Note: Please click here for information on data retention and latency.

The Insights Dashboard widget provides data at the project level. You can navigate to it by logging into your Vonage Video API 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 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

Notes:
  • Please click here for information on data retention and latency.
  • Insights does not currently support multiple API keys in the same query. Please make a separate Insights query for each project in order to obtain information for multiple projects / API keys. To programmatically obtain project-level API keys and secrets for an account, please refer to our documentation on getting information about projects. Using this method, users with an account-level API key and secret can obtain the project details object for a single project or all projects across the account.

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.

Note: Region, SDK, and Browser filtering is not available for Participant and Archiving Minutes.

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.

Important — known issue: The browser name and browser version data is null or empty in some daily results prior to September 14, 2023. Values are included for September 14, 2023 and later.

Obtaining Session Data (Advanced Insights)

Note: Please click here for information on data retention and latency.

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.

Session detail information

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:

Example session detail query

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
                                    connectionId
                                    stream {
                                      streamId
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }	
}

Getting stream statistics

Note: Stream statistics is available to Advanced Insights customers only.

The resources property of the MeetingPublishers object is an array of Publisher objects. And the Publisher object includes PublisherStreamStatsCollection object. This object is a resource collection, and its resources property is an array of PublisherStats objects. Each PublisherStats includes stream statistics for the publisher taken periodically (every 30 seconds) during the course of the publisher's streaming. These statistics include data about the audio and video latency, audio and video bitrate, audio and video packet loss ratio, the video resolution, the audio and video codecs, and whether the stream included audio and video at the time of the stream statistics snapshot.

The following query requests the periodic audio and video bitrate statistics for publishers in an OpenTok session:

{
  project(projectId: 12345678) {
    sessionData {
      sessions(sessionIds: [
        "1_MX4xMDB-fjE1Mzg4NzA0MjExNDd-VjRuSWhpn4",
      ]) {
        resources {
          sessionId
          meetings {
            resources {
              createdAt
              publishers {
                resources {
                  createdAt
                  connectionId
                  stream {
                    streamId
                  }
                  streamStatsCollection {
                    resources {
                      createdAt
                      audioBitrateKbps
                      videoBitrateKbps
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Similarly, the resources property of the MeetingSubscribers object is an array of Subscriber objects, and each of these include a SubscriberStreamStatsCollection resource collection, which includes similar stream statistics for a subscriber.

Session Summary information

Note: Session Summary is available to Advanced Insights customers only.

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.

Both the SessionSummary object and MeetingSummary objects include publisherMinutes, subscriberMinutes, and participantMinutes properties. These report the total number of minutes streamed for all publishers and subscribers in the session or meeting. Including participantMinutes reports minutes separated by publisher tiers in the session or meeting. Note that including publisherMinutes, subscriberMinutes, or participantMinutes in a query will slow down results.

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 Insights 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
        }
      }
    }
  }
}

Data Retention and Latency

Insights / Insights Dashboard

Data retention:

Notes:

  • Daily aggregation data is calculated based on 00:00 - 23:59 PST/PDT.
  • Daily aggregation retention period for Insights API and Insights Dashboard was updated to 90 days (from 60 days) as of August 12, 2021. Daily aggregated data for video sessions after this date will be available for 90 days.

Expected Latency: 36 - 48 hours

Advanced Insights retention period

Advanced Insights

Data retention: 21 days

Note: The retention period is based on the created-at time of a meeting within the session.

Expected Latency: 5 minutes

Advanced Insights retention period

Note: A single session may have multiple meetings. A new meeting is set when the session is out of use for 10 minutes. Please refer to our documentation on Sessions vs. Meetings for more information.

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.
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 Vonage Video API account.

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

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

Calculating participant minutes

What is the accurate method for calculating the participants' minutes for a specific period when reflecting on billing?

To know the exact number of minutes generated in a time range, use Project Data. When using session summaries to specify a time range in the query, results include all sessions created within that time interval. If a session is reused, results include all the sessions that contain at least one meeting created within the specified time interval, displaying the total number of minutes for the entire session and not only this interval.

That is, when using a session summary query, in the case of reusing a session during the provided interval, the minutes are not only for that specific period but for the entire session, which can include results that are out of the time range.

When using project data query, the results include daily data from 00:00 PST to 00:00 PST of the following day. You may have to consider the fact that the query should start at 00:00 PST, otherwise it will always return 1 more day of data than expected.

For example, consider these two project data queries:

projectData(
  start: "2023-12-30T08:00:00.00Z",
  end: "2023-12-31T08:00.00.00Z"
  interval: AUTO
)
projectData(
  start: "2023-12-30T08:00:00.00Z",
  end: "2023-12-31T03:00.00.00Z"
  interval: AUTO
)

For those two requests, the results include only 1 day of data in the results.

In this case, the time zone adjustment effectively shifts "2023-12-30T08:00:00.00Z" to the beginning of December 30th in PST (midnight PST). Since the end time in PST is midnight on the 31st, the results only include one day.

But consider this project data query:

projectData(
  start: "2023-30-30T07:00:00.00Z",
  end: "2023-01-31T08:00.00.00Z"
  interval: AUTO
)

The request will return data from December 30 and 31, 2023.

The timestamp "2023-12-30T07:00:00.00Z" is in (UTC), in PST this will give us "2023-12-29T11:00:00.00PST”, which falls on in December 29th. Due to time zone difference with PST, when the request includes data from "2023-12-30T07:00:00.00Z," UTC, it effectively covers the period from December 30th to December 31st thus including both days in the result.

So, the results will include data for December 30th and 31st, 2023.

{
  project(projectId: XXXX) {
    projectData(
      start: "2022-11-28T15:57:07.529Z"
      interval: AUTO
    ) {
      resources {
        intervalStart
        intervalEnd
        sdkType
        usage {
          participantMinutes {
            from1To2Publishers
            from3To6Publishers
            from7To8Publishers
            from1To4Publishers
            from5To8Publishers
            from1To8Publishers
            from1To10Publishers
            from9To10Publishers
            from11To35Publishers
            from11To20Publishers
            from11To35Publishers
            from36PlusPublishers
            from21To35Publishers
            from36To40Publishers
            from41PlusPublishers
            from1To25Publishers
            from3To25Publishers
            from26To35Publishers
          }
          streamedPublishedMinutes
        }
      }
    }
  }
}

For these reasons, it is better to use the meeting level to obtain a more accurate result:

{
  project(projectId: 47521921) {
    sessionData {
      sessionSummaries(start: "2019-05-01T07:00:00.000Z") {
        resources {
          sessionId
          meetings {
            resources {
              maxConcurrentStreams
              maxConcurrentStreams
              maxConcurrentSubscribers
              totalStreams
              totalConnections
              participantMinutes {
                from1To2Publishers
                from3To6Publishers
                from7To8Publishers
                from1To4Publishers
                from5To8Publishers
                from1To8Publishers
                from1To10Publishers
                from9To10Publishers
                from11To35Publishers
                from11To20Publishers
                from11To35Publishers
                from36PlusPublishers
                from21To35Publishers
                from36To40Publishers
                from41PlusPublishers
                from1To25Publishers
                from3To25Publishers
                from26To35Publishers
              }
            }
          }
        }
      }
    }
  }
}

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.