Getting Started with the Analytics 3 API

Overview

The Zype Analytics 3 API gives you powerful, flexible access to real-time and historical data about how viewers engage with your content. This guide will walk you through the essentials of getting started, including authentication, rate limits, and example queries for common use cases.

Authentication and API Keys

Step 1: Obtain Your API Key

• Go to Zype Admin > Gear Menu > API Keys

• Create or use an existing key with the appropriate Analytics 3 scope

Step 2: Send Authenticated Requests

• Use ?api_key={API_KEY} query param appended to any analytics API request

https://analytics.zype.com/v3/engagement/plays?api_key=YOUR_API_KEY

Real-Time vs Historical Data

All data in Analytics 3 is available in real time, with no delay. However, queries are considered:

Use the following query parameters to define your time window:

• filters[start_date_gte]=YYYY-MM-DDTHH:MM:SSZ

• filters[start_date_lte]=YYYY-MM-DDTHH:MM:SSZ

Real-Time & Historical Examples

Real-Time: Plays in the Last Hour by Platform

Query the /engagement/plays endpoint for near real-time data, grouped by platform:

curl "https://analytics.zype.com/v3/engagement/plays?filters[start_date_gte]=2025-07-09T13:00:00Z&filters[start_date_lte]=2025-07-09T14:00:00Z&group_by=platform&api_key=YOUR_API_KEY"

📌 Returns plays by platform (e.g., Web, iOS, Roku) in the last hour. Adjust start_date_gte as needed using ISO 8601 format.

Real-Time: Playlist Plays Today

Query the /engagement/plays endpoint to summarize long-term viewer engagement:

curl "https://analytics.zype.com/v3/engagement/plays?filters[start_date_gte]=2025-07-09T00:00:00Z&filters[start_date_lte]=2025-07-09T23:59:59Z&filters[playlist_name_eq]=My+Playlist&group_by=platform&api_key=YOUR_API_KEY"

📌 Returns all plays for a specific playlist today, grouped by platform.  Adjust start_date_gte as needed using ISO 8601 format.

Historical: Top 10 Videos by Hours Watched (Last 30 Days)

Query the /hours_watched

curl "https://analytics.zype.com/v3/engagement/hours_watched?filters[start_date_gte]=2025-06-09T00:00:00Z&filters[start_date_lte]=2025-07-09T00:00:00Z&group_by=video_id&sort_by=hours_watched_desc&limit=10&api_key=YOUR_API_KEY"

📌 Returns the 10 most-watched videos over the past 30 days by total hours watched.

Filtered Query: Hours Watched for a Specific Video (Last 7 Days)

curl "https://analytics.zype.com/v3/engagement/hours_watched?filters[start_date_gte]=2025-07-02T00:00:00Z&filters[start_date_lte]=2025-07-09T00:00:00Z&filters[video_id_eq]=64c23e9b3f1e8b0001f54a6d&api_key=YOUR_API_KEY"

📌 This returns total hours watched for the video with ID 64c23e9b3f1e8b0001f54a6d over the past 7 days.

Filter & Grouping Options

You can filter and group by various dimensions:

Common filters

• filters[platform_eq]=Web
• filters[video_id_eq]=64c23e9b3f1e8b0001f54a6d
• filters[playlist_name_eq]=My Playlist
• filters[country_eq]=US
• filters[monetization_type_eq]=subscription

Common Grouping

• group_by=platform
• group_by=video_id
• group_by=playlist_name
• group_by=playlist_id
• group_by=country

Common Sorting

• sort_by=hours_watched_desc
• sort_by=played_desc