> ## 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.

# Plays

The plays endpoint provides insights on the number of times content has been played. It returns data on how many times content has been played, 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/plays": {
      "get": {
        "x-server-name": "analytics-api",
        "summary": "Plays",
        "description": "The plays endpoint provides insights on the number of times content has been played. It returns data on how many times content has been played, 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": "plays-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": "PlaysResponse",
                  "type": "object",
                  "properties": {
                    "response": {
                      "title": "Play",
                      "type": "object",
                      "properties": {
                        "date": {
                          "type": "string",
                          "format": "date-time",
                          "description": "The date of the play count."
                        },
                        "value": {
                          "type": "number",
                          "format": "float",
                          "description": "The number of plays on the given date."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable entity",
            "content": {
              "application/json": {
                "schema": {
                  "title": "AnalyticsNotFound",
                  "type": "object",
                  "properties": {
                    "errors": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```