openapi: 3.0.3
info:
  title: Wowza Streaming Engine REST advanced_token_authentication analytics_engagement API
  description: Complete REST API for Wowza Streaming Engine. Auto-converted from Swagger 1.2 (http://localhost:8089/swagger.json) to OpenAPI 3.0.3 for public documentation.
  version: 2.0.0
  contact:
    name: Wowza Media Systems
    url: https://www.wowza.com/docs/wowza-streaming-engine-rest-api
  license:
    name: Wowza Media Systems
    url: https://www.wowza.com
servers:
- url: http://localhost:8087
  description: Wowza Streaming Engine Server
security:
- basicAuth: []
tags:
- name: analytics_engagement
  description: Operations related to engagement analytics for a VOD stream.
  x-displayName: Engagement
paths:
  /analytics/engagement/vod_streams/{id}:
    get:
      summary: Fetch engagement analytics data for a VOD stream
      description: "(Available from version 1.11) This operation returns the engagement data for a specific VOD stream. Engagement data provides insight into how many plays your stream received and for how long. \n\nIf you don't send from and to query parameters, the last hour's worth of data is returned. See the **trend** field in the response for information about sample intervals.\n\nIf the time range between **from** and **to** query parameters is:\n\n<ul><li>Less than 60 minutes, the cache time between responses is 10 seconds.</li>\n<li>More than 60 minutes, the cache time between responses is 60 seconds.</li>"
      operationId: analyticsVodStreamEngagement
      tags:
      - analytics_engagement
      x-codeSamples:
      - lang: Shell
        source: "// Using cURL\ncurl -H \"Authorization: Bearer ${WV_JWT}\" \\\n  \n  -H \"Content-Type: application/json\" \\\n  -X \"GET\" \\\n  \"${WV_HOST}/api/v2.0/analytics/popularity/vod_streams/tvctq36g?from=2023-04-14T10:31:54.486Z&to=2023-07-13T10:31:54.486Z&include=trend\"\n"
      - lang: JavaScript
        source: "// Using Node.js\nconst https = require('https');\nconst crypto = require('crypto');\nvar hostname = 'api.video.wowza.com'\nvar path = '/api/v2.0/analytics/engagement/vod_streams/tvctq36g?from=2023-04-14T10:31:54.486Z&to=2023-07-13T10:31:54.486Z&include=trend';\n//For security, never reveal API token in client-side code\nvar wvJWT = 'Bearer [your JWT]';\n\nconst options = {\n  hostname: hostname,\n  path: path,\n  headers: {\n    'Authorization': wvJWT,\n    'Content-Type': 'application/json'\n  }\n};\nhttps.get(options, function(res) {\n  var body = '';\n  res.on('data', function(data){\n    body += data;\n  });\n  res.on('end', function() {\n    console.log(JSON.parse(body));\n  });\n}).on('error', function(e) {\n  console.log(e.message);\n});"
      parameters:
      - name: id
        in: path
        required: true
        description: The unique alphanumeric string that identifies the VOD stream.
        schema:
          type: string
      - name: from
        in: query
        required: false
        description: "Use this parameter, along with **to**, to return historic viewer data. \n\nThe start of the range of time you want to view. Specify **YYYY-DD-MMT HH:MM:SSZ** where **HH** is a 24-hour clock in UTC. The range queried is rounded to the nearest second. If you set the **from** query parameter without setting the **to** query parameter, the data returned will reflect 30 days starting at the **from** date, or data up to to the current day, whichever is shorter.\n\nExample:\n**2023-01-14T10:31:54.486Z**"
        schema:
          type: string
          format: date-time
      - name: to
        in: query
        required: false
        description: "Use this parameter, along with **from**, to return historic viewer data. \n\n\nThe end of the range of time you want to view. Specify **YYYY-DD-MMT HH:MM:SSZ** where **HH** is a 24-hour clock in UTC. The range queried is rounded to the nearest second. If you set the **to** query parameter without setting the **from** query parameter, the data returned will be from the past 30 days.\n\nExample:\n**2023-02-14T10:31:54.486Z**"
        schema:
          type: string
          format: date-time
      - name: include
        in: query
        required: false
        description: 'Specify the data you want returned in the response. The only valid value for this endpoint is **trend**.


          Valid values are: trend


          Example:

          **trend**'
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/analytics_engagement_vod_stream'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '410':
          description: Gone
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error410'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error422'
components:
  schemas:
    Error403:
      type: object
      description: ''
      required:
      - meta
      properties:
        meta:
          type: object
          title: meta
          description: ''
          properties:
            status:
              type: integer
              description: ''
              example: ''
              format: int32
            code:
              type: string
              description: ''
              example: ''
            title:
              type: string
              description: ''
              example: ''
            message:
              type: string
              description: ''
              example: ''
            description:
              type: string
              description: ''
              example: ''
            links:
              type: array
              description: ''
              example: ''
              items: {}
      example:
        Example Response 1:
          meta:
            status: 403
            code: ERR-403-RecordUnaccessible
            title: Record Unaccessible Error
            message: The requested resource isn't accessible.
            description: ''
            links: []
    Error401:
      type: object
      description: ''
      required:
      - meta
      properties:
        meta:
          type: object
          title: meta
          description: ''
          properties:
            status:
              type: integer
              description: ''
              example: ''
              format: int32
            code:
              type: string
              description: ''
              example: ''
            title:
              type: string
              description: ''
              example: ''
            message:
              type: string
              description: ''
              example: ''
            description:
              type: string
              description: ''
              example: ''
            links:
              type: array
              description: ''
              example: ''
              items: {}
      example:
        Example Response 1:
          meta:
            status: 401
            code: ERR-401-NoApiKey
            title: No API Key Error
            message: No API key sent in header.
            description: ''
            links: []
        Example Response 2:
          meta:
            status: 401
            code: ERR-401-NoAccessKey
            title: No Access Key Error
            message: No access key sent in header.
            description: ''
            links: []
        Example Response 3:
          meta:
            status: 401
            code: ERR-401-InvalidApiKey
            title: Invalid Api Key Error
            message: Invalid API key.
            description: ''
            links: []
        Example Response 4:
          meta:
            status: 401
            code: ERR-401-InvalidAccessKey
            title: Invalid Access Key Error
            message: Invalid access key.
            description: ''
            links: []
        Example Response 5:
          meta:
            status: 401
            code: ERR-401-BadAccountStatus
            title: Bad Account Status Error
            message: Your account's status doesn't allow this action.
            description: ''
            links: []
        Example Response 6:
          meta:
            status: 401
            code: ERR-401-FeatureNotEnabled
            title: Feature Not Enabled Error
            message: This feature isn't enabled.
            description: ''
            links: []
        Example Response 7:
          meta:
            status: 401
            code: ERR-401-TrialExceeded
            title: Bad Billing Status Error
            message: Your billing status needs attention. You can't start or add live streams until your billing status is updated.
            description: ''
            links: []
        Example Response 8:
          meta:
            status: 401
            code: ERR-401-ExpiredToken
            title: JWT is expired
            message: Token has exired.
            description: ''
            links: []
        Example Response 9:
          meta:
            status: 401
            code: ERR-401-InvalidToken
            title: JWT is invalid
            message: Token is invalid.
            description: ''
            links: []
    analytics_engagement_vod_stream:
      type: object
      description: ''
      properties:
        vod_stream:
          type: object
          title: vod_stream
          description: ''
          properties:
            id:
              type: string
              description: The unique alphanumeric string that identifies the VOD stream.
              format: int32
            play_rate:
              type: integer
              description: The ratio between displays and plays. For example, 100 displays and 20 plays will result in 0.20 which means that 20% of the displays resulted in a play.
              example: ''
              format: int32
            completion_rate:
              type: integer
              description: The ratio of viewers that watched the last segment of the asset. It is represented in a decimal value.
              example: ''
            duration_ms:
              type: integer
              description: The length of the stream in milliseconds.
              example: ''
            avg_seconds_watched:
              type: integer
              description: The average number of seconds the viewers viewed the stream.
              example: ''
            avg_percentage_watched:
              type: integer
              description: The average time watched represented as a percentage.
              example: ''
            total_seconds_watched:
              type: integer
              description: The total number of seconds the stream was viewed.
              example: ''
            trend:
              type: object
              title: Array of viewer trends
              description: "An array of viewer trend data for an asset in the given time period.\n\n\n <blockquote>Note: Data from the most recent hour data might not be included in the result of a time range that extends beyond the most recent 3 days. </blockquote>\n\n\n<strong>Default</strong>: Last hour"
              properties:
                percent:
                  type: integer
                  description: 'A specific segment of the VOD asset. A VOD asset has 100 segments and each segment represents a completion percentage of the asset. For example, 1 is the data for 0 to 1% of the asset, 2 is the data for 1 to 2% and so on.


                    Trend data is aggregated for each segment.


                    Use _**duration_ms** / 1000 x **percent**_ to calculate a timestamp, in seconds, for the trend data.'
                  format: int32
                viewers:
                  type: integer
                  description: The total number of unique viewers who watched this specific segment of the VOD asset. A unique viewer is a single IP address; multiple users that share the same IP address are counted once.
                  example: ''
                  format: int32
            limits:
              type: object
              description: The time frame represented in the response.
              properties:
                from:
                  type: string
                  description: The start of the range of time represented in the response.
                  example: ''
                  format: date-time
                to:
                  type: string
                  description: The end of the range of time represented in the response.
                  example: ''
                  format: date-time
      example:
        vod_stream:
          id: tvctq36g
          play_rate: 0.2
          completion_rate: 0.42
          duration_ms: 9761000
          avg_seconds_watched: 302
          avg_percentage_watched: 67
          total_seconds_watched: 77699
          trend:
          - percent: 1
            viewers: 7
          - percent: 2
            viewers: 7
          - percent: 3
            viewers: 7
          - percent: 4
            viewers: 7
          - percent: 5
            viewers: 10
          - percent: 6
            viewers: 7
          - percent: 7
            viewers: 7
          - percent: 8
            viewers: 25
          - percent: 9
            viewers: 25
          - percent: 10
            viewers: 25
          - percent: 11
            viewers: 7
          - spercent: 12
            viewers: 7
          - percent: 13
            viewers: 7
        limits:
          from: '2024-03-14T10:31:54.000Z'
          to: '2024-04-13T10:31:54.000Z'
    Error422:
      type: object
      description: ''
      required:
      - meta
      properties:
        meta:
          type: object
          title: meta
          description: ''
          properties:
            status:
              type: integer
              description: ''
              example: ''
              format: int32
            code:
              type: string
              description: ''
              example: ''
            title:
              type: string
              description: ''
              example: ''
            message:
              type: string
              description: ''
              example: ''
            description:
              type: string
              description: ''
              example: ''
            links:
              type: array
              description: ''
              example: ''
              items: {}
      example:
        Example Response 1:
          meta:
            status: 422
            code: ERR-422-RecordInvalid
            title: Record Invalid Error
            message: The request couldn't be processed. ... can't be blank
            description: ''
            links: []
        Example Response 2:
          meta:
            status: 422
            code: ERR-422-RecordInvalid
            title: Record Invalid Error
            message: The request couldn't be processed. Provider wowza_video is not allowed
            description: ''
            links: []
        Example Response 3:
          meta:
            status: 422
            code: ERR-422-InvalidStateChange
            title: Invalid State Change Error
            message: The request couldn't be processed. There must be at least one WebRTC output for this transcoder.
            description: ''
            links: []
        Example Response 4:
          meta:
            status: 422
            code: ERR-422-RecordInvalid
            title: Record Invalid Error
            message: API cannot remove the primary Output Stream Target with the ID of <output id> from the Live Stream <livestream id><livestream name>.
            description: ''
            links: []
        Example Response 5:
          meta:
            status: 422
            code: ERR-422-InvalidStateChange
            title: Invalid State Change Error
            message: The request couldn't be processed. The broadcast location can't be updated when using autostart.
            description: ''
            links: []
    Error410:
      type: object
      description: ''
      required:
      - meta
      properties:
        meta:
          type: object
          title: meta
          description: ''
          properties:
            status:
              type: integer
              description: ''
              example: ''
              format: int32
            code:
              type: string
              description: ''
              example: ''
            title:
              type: string
              description: ''
              example: ''
            message:
              type: string
              description: ''
              example: ''
            description:
              type: string
              description: ''
              example: ''
            links:
              type: array
              description: ''
              example: ''
              items: {}
      example:
        Example Response 1:
          meta:
            status: 410
            code: ERR-410-RecordDeleted
            title: Record Deleted Error
            message: The requested resource has been deleted.
            description: ''
            links: []
    Error404:
      type: object
      description: ''
      required:
      - meta
      properties:
        meta:
          type: object
          title: meta
          description: ''
          properties:
            status:
              type: integer
              description: ''
              example: ''
              format: int32
            code:
              type: string
              description: ''
              example: ''
            title:
              type: string
              description: ''
              example: ''
            message:
              type: string
              description: ''
              example: ''
            description:
              type: string
              description: ''
              example: ''
            links:
              type: array
              description: ''
              example: ''
              items: {}
      example:
        Example Response 1:
          meta:
            status: 404
            code: ERR-404-RecordNotFound
            title: Record Not Found Error
            message: The requested resource couldn't be found.
            description: ''
            links: []
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication using Wowza Streaming Engine admin credentials
    digestAuth:
      type: http
      scheme: digest
      description: HTTP Digest Authentication