Zype Analytics V2 to 3 Migration Guide

This article explains how to migrate your existing Analytics V2 engagement queries to the new Zype Analytics 3 engagement endpoints.

Analytics 3 introduces a fully redesigned analytics service with dedicated endpoints for each engagement metric. In Analytics V2, engagement aggregations were retrieved through a single Engagement API using sum[]= and average[]= query parameters. In Analytics 3, these aggregations are replaced with more explicit, purpose-specific endpoints—improving clarity, performance, and consistency.

Use this guide to map each V2 aggregation to its corresponding Analytics 3 endpoint, including example requests and responses.

Overview of Changes

Analytics V2 (Legacy)

• Single endpoint:

  • GET /v2/engagement

• Metrics retrieved via aggregation parameters:

  • sum[]=plays

  • sum[]=time_watched_seconds | time_watched_minutes | time_watched_hours

  • average[]=avg_play_length_seconds | avg_play_length_minutes | avg_play_length_hours

• Multiple metrics returned in a single payload.

Analytics 3 (New)

• Multiple, purpose-built endpoints under /v3/engagement:

  • Plays

  • View Time / Hours Watched

• Each endpoint returns a single primary metric with support for:

  • Filters (filters[...])

  • Grouping (group_by[...])

  • Sorting (sort_by[...])

  • Time interval aggregation (interval=day|hour|month, etc.)

• Unit conversions (seconds, minutes, hours) are handled client-side or via query parameters, depending on endpoint.

  • unit (unit=second | minute | hour|)

1. Plays Aggregations

What Changed

In Analytics V2, total plays were accessed using:

sum[]=plays

In Analytics 3, plays are retrieved through the dedicated Plays endpoint. This endpoint provides total play counts for videos and can be segmented by dimensions such as platform, device, browser, and more.

How to Migrate

Replace any V2 requests using sum[]=plays with calls to the Plays endpoint.

Analytics 3 Example

Request

GET https://analytics.zype.com/v3/engagement/plays?api_key=[api_key]&filters[start_date_gte]=2025-11-24&filters[start_date_lte]=2025-11-30&interval=day

Response

{
  "data": [
    { "date": "2025-11-30T00:00:00.000Z", "value": 4742 },
    { "date": "2025-11-29T00:00:00.000Z", "value": 4898 },
    { "date": "2025-11-28T00:00:00.000Z", "value": 4821 },
    { "date": "2025-11-27T00:00:00.000Z", "value": 5067 },
    { "date": "2025-11-26T00:00:00.000Z", "value": 5173 },
    { "date": "2025-11-25T00:00:00.000Z", "value": 5374 },
    { "date": "2025-11-24T00:00:00.000Z", "value": 5551 }
  ],
  "paging": {
    "limit": 200,
    "offset": 0
  },
  "realtime": true
}

API Reference

• Plays: https://docs.zype.com/reference/plays-v3-1#/

2. Watched Time Aggregations

What Changed

Analytics V2 provided time-watched aggregations using:

sum[]=time_watched_seconds
sum[]=time_watched_minutes
sum[]=time_watched_hours

All three represent the same underlying metric (total watch time) expressed at different units.

In Analytics 3, all watched-time-based aggregations are retrieved from the Hours Watched / View Time endpoint. Unit conversions (seconds, minutes, hours) can now be handled client-side (and/or via the unit parameter where supported).

How to Migrate

Replace all V2 time-watched sums—regardless of unit—with calls to the View Time endpoint.

Analytics 3 Example

Request

GET https://analytics.zype.com/v3/engagement/view_time?api_key=[api_key]&unit=second&filters[start_date_gte]=2025-11-24&filters[start_date_lte]=2025-11-30&interval=day

Response

{
  "data": [
    { "date": "2025-11-30T00:00:00.000Z", "value": 1492.37 },
    { "date": "2025-11-29T00:00:00.000Z", "value": 1478.62 },
    { "date": "2025-11-28T00:00:00.000Z", "value": 1441.55 },
    { "date": "2025-11-27T00:00:00.000Z", "value": 1398.21 },
    { "date": "2025-11-26T00:00:00.000Z", "value": 1426.94 },
    { "date": "2025-11-25T00:00:00.000Z", "value": 1412.08 },
    { "date": "2025-11-24T00:00:00.000Z", "value": 1456.73 }
  ],
  "paging": {
    "limit": 200,
    "offset": 0
  },
  "realtime": true
}

API Reference

• Hours Watched: https://docs.zype.com/reference/hours-watched-v3-1#/

3. Average Play Length Aggregations

What Changed

Analytics V2 provided average play-length metrics using:

average[]=avg_play_length_seconds
average[]=avg_play_length_minutes
average[]=avg_play_length_hours

These metrics represented the average amount of time a user viewed content during a playback session.

In Analytics 3, average play-length metrics are retrieved from the View Time endpoint. This endpoint provides average session length and related time-based engagement metrics. Unit conversions (seconds, minutes, hours) can now be handled client-side.

How to Migrate

Replace any usage of average[]=avg_play_length_* with requests to the View Time endpoint.

Analytics 3 Example

Request

GET https://analytics.zype.com/v3/engagement/view_time?api_key=[api_key]&unit=second&filters[start_date_gte]=2025-11-24&filters[start_date_lte]=2025-11-30&interval=day

Response

{
  "data": [
    { "date": "2025-11-30T00:00:00.000Z", "value": 1472.3 },
    { "date": "2025-11-29T00:00:00.000Z", "value": 1448.7 },
    { "date": "2025-11-28T00:00:00.000Z", "value": 1389.5 },
    { "date": "2025-11-27T00:00:00.000Z", "value": 1421.9 },
    { "date": "2025-11-26T00:00:00.000Z", "value": 1455.2 },
    { "date": "2025-11-25T00:00:00.000Z", "value": 1397.8 },
    { "date": "2025-11-24T00:00:00.000Z", "value": 1436.4 }
  ],
  "paging": {
    "limit": 200,
    "offset": 0
  },
  "realtime": true
}

API Reference

• View Time: https://docs.zype.com/reference/view-time-v3#/

Supported Query Parameters

The Analytics 3 engagement endpoints (Plays, View Time / Hours Watched) support a shared set of filters, grouping, sorting, and unit parameters.

Supported Filter Values (filters[...])

You can apply filters using the filters[<attribute>_<operator>] format. Common examples:

• filters[app_id_eq]

• filters[app_name_eq]

• filters[app_version_eq]

• filters[content_type_eq]

• filters[consumer_id_eq]

• filters[country_eq]

• filters[domain_eq]

• filters[external_user_id_eq]

• filters[monetization_type_eq]

• filters[played_gt]

• filters[platform_eq]

• filters[platform_source_eq]

• filters[playlist_id_eq]

• filters[playlist_name_eq]

• filters[playout_channel_id_eq]

• filters[playout_channel_name_eq]

• filters[playout_destination_id_eq]

• filters[playout_destination_name_eq]

• filters[start_date_eq]

• filters[start_date_gt]

• filters[start_date_gte]

• filters[start_date_lt]

• filters[start_date_lte]

• filters[start_time_eq]

• filters[start_time_gt]

• filters[start_time_gte]

• filters[start_time_lt]

• filters[start_time_lte]

• filters[subscription_id_eq]

• filters[transaction_id_eq]

• filters[video_id_eq]

• filters[video_title_eq]

Please visit our API Reference for an updated list of supported filters[...] values.

Supported Group Values (group_by[...])

You can group results by one or more dimensions using group_by[]:

• group_by[]=app_id

• group_by[]=app_name

• group_by[]=app_version

• group_by[]=consumer_id

• group_by[]=content_type

• group_by[]=country

• group_by[]=domain

• group_by[]=external_user_id

• group_by[]=monetization_type

• group_by[]=platform

• group_by[]=platform_source

• group_by[]=playlist_id

• group_by[]=playlist_name

• group_by[]=playout_channel_id

• group_by[]=playout_channel_name

• group_by[]=playout_destination_id

• group_by[]=playout_destination_name

• group_by[]=subscription_id

• group_by[]=transaction_id

• group_by[]=video_id

• group_by[]=video_title

Please visit our API Reference for an updated list of supported group_by[] values.

Supported Sort Values (sort_by[...] or sort)

You can sort results on a specific attribute:

• day

• hour

• month

• app_id

• app_name

• app_version

• consumer_id

• content_type

• country

• domain

• external_user_id

• monetization_type

• platform

• platform_source

• playlist_id

• playlist_name

• playout_channel_id

• playout_channel_name

• playout_destination_id

• playout_destination_name

• subscription_id

• transaction_id

• video_id

• video_title

Please visit our API Reference for an updated list of supported sort attributes.

Supported Unit Values (unit)

Where applicable (for time-based endpoints like View Time / Hours Watched), you can specify the time unit:

• unit=second

• unit=minute

• unit=hour

Please visit our API Reference for an updated list of supported unit values.

Summary Mapping Table

Use the following table to map Analytics V2 aggregation parameters to Analytics 3 engagement endpoints:

Examples

Example 1: Migrating Plays from Analytics V2 to Analytics 3

Analytics V2 Request

GET https://analytics.zype.com/v2/engagement?api_key=[api_key]&filters%5Bstart_date_gte%5D=2025-11-01&filters%5Bstart_date_lte%5D=2025-11-30&sort=start_date_desc&sums[]=plays

Analytics V2 Response

{
  "data": [
    { "start_date": "2025-11-30", "plays": 587 },
    { "start_date": "2025-11-29", "plays": 603 },
    { "start_date": "2025-11-28", "plays": 568 },
    { "start_date": "2025-11-27", "plays": 552 },
    { "start_date": "2025-11-26", "plays": 575 },
    { "start_date": "2025-11-25", "plays": 590 },
    { "start_date": "2025-11-24", "plays": 601 }
  ]
}

Analytics 3 Request

GET https://analytics.zype.com/v3/engagement/plays?api_key=[api_key]&filters[start_date_gte]=2025-11-24&filters[start_date_lte]=2025-11-30&interval=day

Analytics 3 Response

{
  "data": [
    { "date": "2025-11-30T00:00:00.000Z", "value": 4742 },
    { "date": "2025-11-29T00:00:00.000Z", "value": 4898 },
    { "date": "2025-11-28T00:00:00.000Z", "value": 4821 },
    { "date": "2025-11-27T00:00:00.000Z", "value": 5067 },
    { "date": "2025-11-26T00:00:00.000Z", "value": 5173 },
    { "date": "2025-11-25T00:00:00.000Z", "value": 5374 },
    { "date": "2025-11-24T00:00:00.000Z", "value": 5551 }
  ],
  "paging": {
    "limit": 200,
    "offset": 0
  },
  "realtime": true
}

Example 2: Migrating Watched Time from Analytics V2 to Analytics 3

Analytics V2 Request

GET https://analytics.zype.com/v2/engagement?api_key=[api_key]&filters%5Bstart_date_gte%5D=2025-11-24&filters%5Bstart_date_lte%5D=2025-11-30&sort=start_date_desc&sums[]=time_watched_seconds&interval=day

Analytics V2 Response

{
  "data": [
    { "start_date": "2025-11-30", "time_watched_seconds": 587.3 },
    { "start_date": "2025-11-29", "time_watched_seconds": 601.1 },
    { "start_date": "2025-11-28", "time_watched_seconds": 572.8 },
    { "start_date": "2025-11-27", "time_watched_seconds": 558.6 },
    { "start_date": "2025-11-26", "time_watched_seconds": 594.2 },
    { "start_date": "2025-11-25", "time_watched_seconds": 563.9 },
    { "start_date": "2025-11-24", "time_watched_seconds": 549.7 }
  ]
}

Analytics 3 Request

GET https://analytics.zype.com/v3/engagement/view_time?api_key=[api_key]&unit=second&filters[start_date_gte]=2025-11-24&filters[start_date_lte]=2025-11-30&interval=day

Analytics 3 Response

{
  "data": [
    { "date": "2025-11-30T00:00:00.000Z", "value": 1492.37 },
    { "date": "2025-11-29T00:00:00.000Z", "value": 1478.62 },
    { "date": "2025-11-28T00:00:00.000Z", "value": 1441.55 },
    { "date": "2025-11-27T00:00:00.000Z", "value": 1398.21 },
    { "date": "2025-11-26T00:00:00.000Z", "value": 1426.94 },
    { "date": "2025-11-25T00:00:00.000Z", "value": 1412.08 },
    { "date": "2025-11-24T00:00:00.000Z", "value": 1456.73 }
  ],
  "paging": {
    "limit": 200,
    "offset": 0
  },
  "realtime": true
}

Example 3: Migrating Average Play Length from Analytics V2 to Analytics 3

Analytics V2 Request

GET https://analytics.zype.com/v2/engagement?api_key=[api_key]&filters%5Bstart_date_gte%5D=2025-11-24&filters%5Bstart_date_lte%5D=2025-11-30&sort=start_date_desc&averages[]=avg_play_length_seconds&interval=day

Analytics V2 Response

{
  "data": [
    { "start_date": "2025-11-30", "avg_play_length_seconds": 245.6 },
    { "start_date": "2025-11-29", "avg_play_length_seconds": 263.2 },
    { "start_date": "2025-11-28", "avg_play_length_seconds": 251.9 },
    { "start_date": "2025-11-27", "avg_play_length_seconds": 237.4 },
    { "start_date": "2025-11-26", "avg_play_length_seconds": 249.7 },
    { "start_date": "2025-11-25", "avg_play_length_seconds": 260.1 },
    { "start_date": "2025-11-24", "avg_play_length_seconds": 253.8 }
  ]
}

Analytics 3 Request

GET https://analytics.zype.com/v3/engagement/view_time?api_key=[api_key]&unit=second&filters[start_date_gte]=2025-11-24&filters[start_date_lte]=2025-11-30&interval=day

Analytics 3 Response

{
  "data": [
    { "date": "2025-11-30T00:00:00.000Z", "value": 1472.3 },
    { "date": "2025-11-29T00:00:00.000Z", "value": 1448.7 },
    { "date": "2025-11-28T00:00:00.000Z", "value": 1389.5 },
    { "date": "2025-11-27T00:00:00.000Z", "value": 1421.9 },
    { "date": "2025-11-26T00:00:00.000Z", "value": 1455.2 },
    { "date": "2025-11-25T00:00:00.000Z", "value": 1397.8 },
    { "date": "2025-11-24T00:00:00.000Z", "value": 1436.4 }
  ],
  "paging": {
    "limit": 200,
    "offset": 0
  },
  "realtime": true
}

Example Error Response (Invalid Sort Attribute)

If you use an unsupported sort attribute, you may receive a 422 Unprocessable Entity error similar to the following:

{
  "errors": [
    {
      "status": 422,
      "source": {
        "pointer": "v3/view_time"
      },
      "value": [
        "year"
      ],
      "msg": "Your sort attribute must be one of the following: day, hour, month, video_id, video_title, platform, consumer_id, subscription_id, transaction_id, monetization_type, playlist_id, playlist_name, app_id, app_name, app_version, content_type, playout_channel_id, playout_channel_name, playout_destination_id, playout_destination_name, platform_source, external_user_id, domain, country",
      "param": "sort",
      "location": "query"
    }
  ]
}

Update the sort parameter to one of the supported attributes listed above to resolve this error.

If you have any questions about migrating specific queries or need help validating your Analytics 3 implementation, please contact Zype Support and include example requests and responses from both V2 and V3.