Insights Dashboard & API

The Vonage Video Insights API is a GraphQL API. You can use the Insights API and the Insights Dashboard to obtain information about your Vonage Video 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 a Vonage Video 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:

All requests are made as HTTP POST.

Exploring the API Schema With GraphiQL

Navigating to https://tools.vonage.com/video/insights-api/ 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:

• On the top-right corner of the tool, you will see a Docs button. Clicking it opens up a pane containing the schema's documentation. Each field and object type in the documentation contains a description. Click through this to explore the schema.
• On the left side of the page is the Query pane. In this pane you can construct queries to run against the API. Going back and forth between the Docs pane and the Query pane allows you to construct the precise query you need for only the information you require. Because you are logged in, authentication for making queries is taken care of for you.
• Below the Query pane is the Query Variables pane. Though not required, you can use this to specify variables for your query. For example, you can define the following variables in this pane:

{
    "PROJECT_ID": 100,
    "START_TIME": "2019-01-01T08:00:00.000Z"
}

Then, in the Query pane, reference any declared variables:

query ($PROJECT_ID: Int!, $START_TIME: Date!) {
    project(projectId: $PROJECT_ID) {
      projectData(
      start: $START_TIME,
      interval: AUTO,
      sdkType: [JS, IOS, ANDROID],
      groupBy: [SDK_TYPE]
          ) {
        resources {
          sdkType
          intervalStart
          intervalEnd
          usage {
            streamedPublishedMinutes
            streamedSubscribedMinutes
          }
        }
      }
    }
}

• To the right of the Query pane is the Response pane. Clicking the Run button in the tool will run the query in the Query pane, and the Response pane displays the results. This is the same response that you would get if you made the query programatically.
• Finally, click the History button above the query pane to view history of your recent queries. Clicking one of the elements displayed populates the Query pane and the Query Variables pane with that data.

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.

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), Vonage Video SDK type and version, as well browser and browser version (if applicable) for the results. The Metric object also includes the following properties:

• usage — Information on stream published minutes, stream subscribed minutes, archive usage, broadcast usage, SIP usage, and usage separated by publisher tiers
• quality — Information about video quality
• errors — The failure rates for connecting to sessions, publishing, and subscribing

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

{
  project(projectId: "abc1234") {
    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)

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

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:

• mediaMode — The media mode for the session. This is "routed" for sessions routed through the Vonage Video Media Router or "relayed" for direct peer-to-peer streaming.
• publisherMinutes — The total number of minutes streamed for all publishers in the session. Note that including this field will slow down query results.
• subscriberMinutes — The total number of minutes streamed for all subscribers in the session. Note that including this field will slow down query results.
• participantMinutes — The total number of minutes separated by publisher tiers across all meetings in the session.
• meetings — An array of Meeting objects. a Vonage Video session can have multiple meetings. When the first client connects to the session, the first meeting starts. The meeting ends when there are no connections in the session for at least 10 minutes. When a client connects again, a new meeting starts. Each Meeting object includes the following properties:
  • subscriberMinutes — The total number of subscriber minutes in the meeting.
  • publisherMinutes — The total number of publisher minutes in the meeting.
  • participantMinutes — The total number of minutes separated by publisher tiers in the meeting.
  • connections — An array of Connection objects defining each client connected to the session (during the meeting). Properties of the Connection object include information about the Vonage Video client SDK used, the browser used (for web clients), information on publishers and subscribers, and more.
  • publishers — An array of Publisher objects. Properties of the Publisher object include information about the publisher's stream, the subscribers to the stream, stream statistics, and more. (The stream statistics included with the Advanced Insights add-on. See Getting stream statistics.)
  • subscribers — Array of Subscriber objects, providing details about each subscriber. Properties of the Subscriber object include information about the subscribers stream, stream statistics, and more. (The stream statistics included with the Advanced Insights add-on. See Getting stream statistics.)
  • createdAt and destroyedAt — Timestamps for the start and end of the meeting.

Note: If all users are disconnected from a meeting and a new connection to the session is made within the 10 minutes, a new meeting will be created with the same meeting ID as the first meeting. However, if the new connection is made after 10 minutes, the new meeting will get a unique meeting ID.

Example session detail query

The following query requests some publisher details on two Vonage Video sessions:

{
    project(projectId: "abc1234") {
      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 a Vonage Video session:

{
  project(projectId: "abc1234") {
    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: "abc1234") {
         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:

• first (optional) — The number of entries to be returned by page. The limit is 10 for Meetings and 1000 for all other resource collections. The default number of entries returned is 10 for Meetings and 50 for all other resource collections.

• endCursor (optional) — The string cursor used to specify the current page (offset). Obtain this cursor value from the pageInfo property for each returned list. If you do not specify an endCursor value, a query will return the first matching page of results (the start of the list).

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

  • hasNextPage — Boolean property which indicates whether there are more pages available.
  • endCursor — The string to be passed to get the next page.

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

{
  project(projectId: "abc1234") {
    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: "abc1234") {
    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:

• Daily aggregation: 90 days
• Monthly aggregation: 12 months

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

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

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.

Updates

August 9, 2024

The following updates are added to the Insights API:

New ways to query your data -- You can search for session ID without including a project ID in a query.

{
  project(sessionIds: "2_MX4xMDB-fjE3MTMyMTMwNDQ1NDV-Z29CLzhyejNha1N2M2RaV255Sno1RTZNfn5-") {
    sessionData {
      sessions {
        resources {
          mediaMode
          sessionId
          meetings {
            totalCount
            pageInfo {
              hasNextPage
              endCursor
            }
            resources {
              meetingId
              createdAt
              destroyedAt
            }
          }
        }
      }
    }
  }
}

• New not operator for projectData.

{
  project(projectId: "abc1234") {
    projectData(
      start: "2024-04-10T11:37:06.147Z"
      interval: AUTO
      not: {
        sdkType:ANDROID
      }
    ) {
      resources {
        intervalStart
        intervalEnd
        sdkType
        sdkVersion
        browser
        usage {
          streamedPublishedMinutes
          streamedSubscribedMinutes
        }
      }
    }
  }
}

• New location and browser data filters for connections.

{
  project(sessionIds: "2_MX4xMDB-fjE3MTMyMTMwNDQ1NDV-Z29CLzhyejNha1N2M2RaV255Sno1RTZNfn5-") {
    sessionData {
      sessions {
        resources {
          meetings {
            resources {
              connections(country: "US") {
                totalCount
              }
            }
          }
        }
      } 
    }
  }
}

New audio codec and video codec data filters. You can now set an audioCodec filter (to PCMU, VP8, OPUS, TELEPHONE, or OTHER), or set a videoCodec filter (to VP8, H264, VP9, RTX, or OTHER).

{
  project(sessionIds: "2_MX4xMDB-fjE3MTMyMTMwNDQ1NDV-Z29CLzhyejNha1N2M2RaV255Sno1RTZNfn5-") {
    sessionData {
      sessions {
        resources {
          sessionId
          meetings {
            resources {
              meetingId
              createdAt
              publishers {
                resources {
                  createdAt
                  connectionId
                  stream {
                    streamId
                  }
                  streamStatsCollection(filters: { videoCodec: VP8} ) {
                    resources {
                      createdAt
                      audioBitrateKbps
                      videoBitrateKbps
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

New mediaMode filter for at sessionSummaries. You can now set a mediaMode filter to ROUTED or RELAYED).

{
  project(sessionIds: "2_MX4xMDB-fjE3MTMyMTMwNDQ1NDV-Z29CLzhyejNha1N2M2RaV255Sno1RTZNfn5-") {
    sessionData {
      sessionSummaries (
        start: "2024-02-25T20:02:32.345Z"
        filters: { mediaMode: ROUTED } ) {
        resources {
          sessionId
          mediaMode
          meetings  {
            totalCount
            pageInfo {
              hasNextPage
              endCursor
            }
            resources {
              meetingId
              createdAt
              destroyedAt
            }
          }
        }
      }
    }
  }
}