> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zype.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Viewers

The viewers endpoint provides insights on how many unique viewers have watched content. It returns data on how many unique viewers have watched content, which can be filtered by various parameters such as date range, content type, and more. This is useful for understanding viewer engagement and content performance.

# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "Analytics (V3)",
    "version": "1.0.0",
    "description": ""
  },
  "servers": [
    {
      "url": "https://analytics.zype.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "api_key": {
        "type": "apiKey",
        "name": "api_key",
        "in": "query"
      }
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "paths": {
    "/v3/engagement/viewers": {
      "get": {
        "x-server-name": "analytics-api",
        "summary": "Viewers",
        "description": "The viewers endpoint provides insights on how many unique viewers have watched content. It returns data on how many unique viewers have watched content, which can be filtered by various parameters such as date range, content type, and more. This is useful for understanding viewer engagement and content performance.",
        "tags": [
          "Engagement"
        ],
        "operationId": "viewers-v3",
        "parameters": [
          {
            "name": "filters[start_date_gt]",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter records created after the specified `start_date`."
          },
          {
            "name": "filters[start_date_gte]",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter records created on or after the specified `start_date`. If no `start_date` filter is specified, then data returned will date back two weeks ago."
          },
          {
            "name": "filters[start_date_lt]",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter records created before the specified `start_date`."
          },
          {
            "name": "filters[start_date_lte]",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter records created on or before the specified `start_date`."
          },
          {
            "name": "filters[start_date_eq]",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter records created on the specified `start_date`."
          },
          {
            "name": "filters[start_time_gt]",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter records created after the specified `start_time`. Comparison is date and time specific. If no time values are submitted, 00:00:00 UTC is assumed."
          },
          {
            "name": "filters[start_time_gte]",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter records created on or after the specified `start_time`. If no `start_time` filter is specified, then data returned will date back two weeks ago. Comparison is date and time specific. If no time values are submitted, 00:00:00 UTC is assumed."
          },
          {
            "name": "filters[start_time_lt]",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter records created before the specified `start_time`. Comparison is date and time specific. If no time values are submitted, 00:00:00 UTC is assumed."
          },
          {
            "name": "filters[start_time_lte]",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter records created on or before the specified `start_time`. Comparison is date and time specific. If no time values are submitted, 00:00:00 UTC is assumed."
          },
          {
            "name": "filters[start_time_eq]",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter records created on the specified `start_time`. Comparison is date and time specific. If no time values are submitted, 00:00:00 UTC is assumed."
          },
          {
            "name": "filters[played_gt]",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter records where `played` is greater than the specified value."
          },
          {
            "name": "filters[video_id_eq]",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter records by `video_id`"
          },
          {
            "name": "filters[video_title_eq]",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter records by `video_title`"
          },
          {
            "name": "filters[platform_eq]",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter records by `platform` (e.g., Web, etc.)"
          },
          {
            "name": "filters[consumer_id_eq]",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter records by `consumer_id`"
          },
          {
            "name": "filters[subscription_id_eq]",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter records by `subscription_id`"
          },
          {
            "name": "filters[transaction_id_eq]",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter records by `transaction_id`"
          },
          {
            "name": "filters[monetization_type_eq]",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter records by `monetization_type` (e.g., subscription, etc.)"
          },
          {
            "name": "filters[playlist_id_eq]",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter records by `playlist_id`"
          },
          {
            "name": "filters[playlist_name_eq]",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter records by `playlist_name`"
          },
          {
            "name": "filters[app_id_eq]",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter records by `app_id`"
          },
          {
            "name": "filters[app_name_eq]",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter records by `app_name`"
          },
          {
            "name": "filters[app_version_eq]",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter records by `app_version`"
          },
          {
            "name": "filters[player_name_eq]",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter records by `player_name`"
          },
          {
            "name": "filters[player_version_eq]",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter records by `player_version`"
          },
          {
            "name": "filters[content_type_eq]",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter records by `content_type` (e.g., video, audio, etc.)"
          },
          {
            "name": "filters[playout_channel_id_eq]",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter records by `playout_channel_id`"
          },
          {
            "name": "filters[playout_channel_name_eq]",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter records by `playout_channel_name`"
          },
          {
            "name": "filters[playout_destination_id_eq]",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter records by `playout_destination_id`"
          },
          {
            "name": "filters[playout_destination_name_eq]",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter records by `playout_destination_name`"
          },
          {
            "name": "filters[platform_source_eq]",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter records by `platform_source`"
          },
          {
            "name": "filters[external_user_id_eq]",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter records by `external_user_id`"
          },
          {
            "name": "filters[domain_eq]",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter records by `domain`"
          },
          {
            "name": "filters[country_eq]",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter records by `country` (e.g., US, CA, etc.)"
          },
          {
            "name": "interval",
            "in": "query",
            "schema": {
              "type": "string",
              "nullable": true,
              "default": "day",
              "enum": [
                null,
                "hour",
                "day",
                "month"
              ]
            },
            "description": "Group records by time intervals. Accepted values: `hour`, `day`, `month`."
          },
          {
            "name": "group_by",
            "in": "query",
            "schema": {
              "type": "array",
              "items": {
                "nullable": true,
                "type": "string",
                "enum": [
                  null,
                  "video_id",
                  "video_title",
                  "platform",
                  "subscription_id",
                  "transaction_id",
                  "monetization_type",
                  "playlist_id",
                  "playlist_name",
                  "app_id",
                  "app_name",
                  "app_version",
                  "player_name",
                  "player_version",
                  "content_type",
                  "playout_channel_id",
                  "playout_channel_name",
                  "playout_destination_id",
                  "playout_destination_name",
                  "platform_source",
                  "external_user_id",
                  "domain",
                  "country"
                ]
              }
            },
            "description": "Group records by one or more properties of the data returned"
          },
          {
            "name": "sort_by",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "day_desc",
              "enum": [
                null,
                "hour_asc",
                "hour_desc",
                "day_asc",
                "day_desc",
                "month_asc",
                "month_desc",
                "video_id_asc",
                "video_id_desc",
                "video_title_asc",
                "video_title_desc",
                "platform_asc",
                "platform_desc",
                "subscription_id_asc",
                "subscription_id_desc",
                "transaction_id_asc",
                "transaction_id_desc",
                "monetization_type_asc",
                "monetization_type_desc",
                "playlist_id_asc",
                "playlist_id_desc",
                "playlist_name_asc",
                "playlist_name_desc",
                "app_id_asc",
                "app_id_desc",
                "app_name_asc",
                "app_name_desc",
                "app_version_asc",
                "app_version_desc",
                "player_name_asc",
                "player_name_desc",
                "player_version_asc",
                "player_version_desc",
                "content_type_asc",
                "content_type_desc",
                "playout_channel_id_asc",
                "playout_channel_id_desc",
                "playout_channel_name_asc",
                "playout_channel_name_desc",
                "playout_destination_id_asc",
                "playout_destination_id_desc",
                "playout_destination_name_asc",
                "playout_destination_name_desc",
                "platform_source_asc",
                "platform_source_desc",
                "external_user_id_asc",
                "external_user_id_desc",
                "domain_asc",
                "domain_desc",
                "country_asc",
                "country_desc"
              ]
            },
            "description": "Sort results by value of a specific property + '_' + sort direction (Example - sort_by=start_time_asc, or sort_by=video_id_desc)"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Limit the number of records returned"
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Offset the number of records returned by the specified value. For example, if you have 100 records and you set offset=10, then the first 10 records will be skipped and the next 90 will be returned."
          }
        ],
        "responses": {
          "200": {
            "description": "See below for example responses",
            "content": {
              "application/json": {
                "schema": {
                  "title": "ViewersResponse",
                  "type": "object",
                  "properties": {
                    "response": {
                      "title": "Viewer",
                      "type": "object",
                      "properties": {
                        "date": {
                          "type": "string",
                          "format": "date-time",
                          "description": "The date of the viewer count."
                        },
                        "value": {
                          "type": "number",
                          "format": "float",
                          "description": "The number of viewers on the given date."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable entity",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/paths/~1v3~1engagement~1plays/get/responses/422/content/application~1json/schema"
                }
              }
            }
          }
        }
      }
    }
  }
}
```