openapi: 3.2.0
info:
  title: Gumlet Video Usage Analytics API
  description: Gumlet helps developers deliver online video and images. This API encompasses Gumlet Video, Image and Video Analytics functionality to help you build your products better and faster than ever before.
  version: '1.4'
  contact:
    name: Gumlet Support Team
    url: https://www.gumlet.com/contact/
    email: support@gumlet.com
  termsOfService: https://www.gumlet.com/terms/
  license:
    name: Apache 2.0
    url: https://opensource.org/license/apache-2.0
  x-scalar-sdk-installation:
  - lang: TypeScript
    description: '```sh

      npm install @gumlet/nodejs-sdk

      ```'
  - lang: Python
    description: '```sh

      pip install gumlet

      ```'
servers:
- url: https://api.gumlet.com/v1
security:
- API_KEY: []
tags:
- name: Video Usage Analytics
  description: Query video analytics and streaming duration usage data.
paths:
  /video/analytics:
    post:
      summary: Video Usage Analytics
      description: This endpoint gives usage analytics data of your videos. Ex - top assets, bandwidth consumption
      operationId: retrieve-analytics
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - metrics
              - date_range
              properties:
                metrics:
                  type: array
                  description: Define the metric you need the data for. Currently we only support `bandwidth_consumption`, `asset_duration`, `storage_unit`, `top_assets`, `bandwidth_consumption_by_collection`, `errored_videos` and `widget_data`
                  items:
                    type: string
                    enum:
                    - bandwidth_consumption
                    - asset_duration
                    - storage_unit
                    - top_assets
                    - drm_requests
                    - ai_credit_usage
                    - errored_videos
                    x-apidog-enum:
                    - value: bandwidth_consumption
                      name: ''
                      description: ''
                    - value: asset_duration
                      name: ''
                      description: ''
                    - value: storage_unit
                      name: ''
                      description: ''
                    - value: top_assets
                      name: ''
                      description: ''
                    - value: drm_requests
                      name: ''
                      description: ''
                    - value: ai_credit_usage
                      name: ''
                      description: ''
                    - value: errored_videos
                      name: ''
                      description: ''
                date_range:
                  type: object
                  description: The timeframe to get the data for. Currently we only support a maximum of 60 days between `start_at` and `end_at`.
                  properties:
                    start_at:
                      type: string
                      description: The starting date to consider
                      format: date
                    end_at:
                      type: string
                      description: The ending date to consider
                      format: date
                  x-apidog-orders:
                  - start_at
                  - end_at
                  required:
                  - start_at
                  - end_at
                filters:
                  type: object
                  properties:
                    collection_id:
                      type: string
                      description: The ID of the `workspace` you want to filter the data for.
                    source_id:
                      type: string
                      description: The ID of the `workspace` you want to filter the data for. Deprecated.
                      deprecated: true
                  x-apidog-orders:
                  - collection_id
                  - source_id
                top_assets_count:
                  type: string
                  description: Count of video assets that should be returned. Max assets count is 1000 per page.
                  default: '5'
                top_assets_page:
                  type: string
                  default: '0'
                  description: top_assets metric may get paginated response. Iterate this parameter to get more data.
                group_by:
                  type: string
                  description: Group by hourly, daily or monthly. If you don't specify anything it's `hourly` by default.
                  enum:
                  - hourly
                  - daily
                  - monthly
                  x-apidog-enum:
                  - value: hourly
                    name: ''
                    description: ''
                  - value: daily
                    name: ''
                    description: ''
                  - value: monthly
                    name: ''
                    description: ''
                  default: hourly
              x-apidog-orders:
              - metrics
              - date_range
              - group_by
              - filters
              - top_assets_count
              - top_assets_page
            examples:
              Example 1:
                value:
                  metrics:
                  - bandwidth_consumption
                  - asset_duration
                  - storage_unit
                  - top_assets
                  - drm_requests
                  date_range:
                    start_at: '2026-08-01'
                    end_at: '2026-08-20'
                  group_by: daily
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples: {}
              schema:
                type: object
                properties:
                  drm_requests:
                    type: array
                    items:
                      type: object
                      properties:
                        units:
                          type: integer
                          description: Number of DRM requests.
                          format: int64
                        timestamp:
                          type: integer
                          description: Seconds since epoch for the unit given.
                          format: int64
                      x-apidog-orders:
                      - units
                      - timestamp
                      required:
                      - units
                      - timestamp
                  bandwidth_saving_unit:
                    type: string
                    enum:
                    - ''
                    x-apidog-enum:
                    - value: ''
                      name: ''
                      description: ''
                    description: The unit for bandwidth saving data.
                  storage_data_unit:
                    type: string
                    enum:
                    - gb
                    - min
                    x-apidog-enum:
                    - value: gb
                      name: Gigabytes
                      description: ''
                    - value: min
                      name: Minutes
                      description: ''
                    description: The unit for the storage data.
                  bandwidth_consumption:
                    type: array
                    items:
                      type: object
                      properties:
                        units:
                          type: integer
                          format: int64
                          description: The bandwidth consumption data in bytes.
                        timestamp:
                          type: integer
                          format: int64
                          description: Seconds since epoch for the unit given.
                      x-apidog-orders:
                      - units
                      - timestamp
                      required:
                      - units
                      - timestamp
                  storage_unit:
                    type: array
                    items:
                      type: object
                      properties:
                        units:
                          type: integer
                          format: int64
                          description: The storage data in bytes or seconds.
                        timestamp:
                          type: integer
                          format: int64
                          description: Seconds since epoch for the unit given.
                      x-apidog-orders:
                      - units
                      - timestamp
                      required:
                      - units
                      - timestamp
                  asset_duration:
                    type: array
                    items:
                      type: object
                      properties:
                        units:
                          type: integer
                          format: int64
                          description: Total transcoding duration in seconds.
                        timestamp:
                          type: integer
                          format: int64
                          description: Seconds since epoch for the unit given.
                      x-apidog-orders:
                      - units
                      - timestamp
                      required:
                      - units
                      - timestamp
                  top_assets:
                    type: array
                    items:
                      type: object
                      properties:
                        asset_id:
                          type: string
                          description: Asset ID
                        units:
                          type: string
                          description: Bandwidth consumption by this asset in bytes.
                        workspace_id:
                          type: string
                          description: Workspace ID
                        duration:
                          type: string
                          description: Seconds of streaming minutes consumed by this asset.
                        title:
                          type: string
                          description: Asset Title
                        collection_name:
                          type: string
                          description: Workspace Name
                      x-apidog-orders:
                      - workspace_id
                      - asset_id
                      - units
                      - duration
                      - title
                      - collection_name
                      required:
                      - workspace_id
                      - asset_id
                      - units
                      - duration
                      - title
                      - collection_name
                  has_more_top_asset:
                    type: boolean
                    description: Indicates whether the list of top assets is exhaustive or if it has more assets.
                  ai_credit_usage:
                    type: array
                    items:
                      type: object
                      properties:
                        timestamp:
                          type: integer
                          description: Seconds since epoch for the unit given.
                      x-apidog-orders:
                      - timestamp
                      required:
                      - timestamp
                  errored_videos:
                    type: array
                    items:
                      type: object
                      properties:
                        timestamp:
                          type: integer
                          description: Seconds since epoch for the unit given.
                        units:
                          type: integer
                          description: Number of errored videos in the timeframe
                      x-apidog-orders:
                      - timestamp
                      - units
                      required:
                      - timestamp
                      - units
                x-apidog-orders:
                - drm_requests
                - bandwidth_saving_unit
                - storage_data_unit
                - bandwidth_consumption
                - storage_unit
                - asset_duration
                - errored_videos
                - top_assets
                - ai_credit_usage
                - has_more_top_asset
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Result:
                  value:
                    error:
                      code: invalid_parameter_value
                      message: The parameter value is invalid.
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: invalid_parameter_value
                      message:
                        type: string
                        example: The parameter value is invalid.
                    required:
                    - code
                    - message
                required:
                - error
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      deprecated: false
      tags:
      - Video Usage Analytics
      x-codeSamples:
      - label: TypeScript
        lang: TypeScript
        source: "import Gumlet from '@gumlet/nodejs-sdk';\n\nconst client = new Gumlet({\n  apiKey: process.env['API_KEY'], // defaults to the API_KEY env var\n});\n\nconst videoUsageAnalytic = await client.videoUsageAnalytics.retrieve({\n  metrics: ['bandwidth_consumption', 'asset_duration', 'storage_unit', 'top_assets', 'drm_requests'],\n  date_range: { start_at: '2026-08-01', end_at: '2026-08-20' },\n  group_by: 'daily',\n});\n\nconsole.log(videoUsageAnalytic);"
      - label: Python
        lang: Python
        source: "import os\n\nfrom gumlet import Gumlet\n\nclient = Gumlet(\n    api_key=os.environ.get(\"API_KEY\"),\n)\n\nvideo_usage_analytic = client.video_usage_analytics.retrieve(\n    metrics=[\"bandwidth_consumption\", \"asset_duration\", \"storage_unit\", \"top_assets\", \"drm_requests\"],\n    date_range={\"start_at\": \"2026-08-01\", \"end_at\": \"2026-08-20\"},\n    top_assets_count=\"5\",\n    top_assets_page=\"0\",\n    group_by=\"hourly\",\n)\n\nprint(video_usage_analytic)"
  /video/streaming-duration:
    get:
      summary: Top Streamed Assets
      description: This endpoint lists top streamed assets in a video collection
      operationId: top-assets
      parameters:
      - name: start_at
        in: query
        description: Date string in "yyyy-mm-dd" format
        required: true
        schema:
          type: string
          examples:
          - '2026-06-21'
      - name: end_at
        in: query
        description: Date string in "yyyy-mm-dd" format
        required: true
        schema:
          type: string
          examples:
          - '2026-06-30'
      - name: collection_id
        description: Gumlet workspace ID
        in: query
        schema:
          type: string
      - name: page
        description: Page number of the response.
        in: query
        schema:
          type: string
          default: '1'
      - name: page_size
        description: Assets to list per page.
        in: query
        schema:
          type: string
          default: '1000'
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                Result:
                  value:
                    data:
                    - asset_id: 638888010f1a158347ce9842
                      units: 0
                    - asset_id: 6369df88cb5ca27c554bb1f2
                      units: 0
                    - asset_id: 63761f1fbe6f4dea7af3e050
                      units: 0
                    - asset_id: 63761eb6b6648252fc979673
                      units: 0
                    - asset_id: 6385035a3f8d6fa3925c5ae9
                      units: 0
                    - asset_id: 63761e09be6f4dea7af3ddaf
                      units: 0
                    - asset_id: 6322109d046f16b5e0ee63d9
                      units: 0
                    - asset_id: 6405cc5b4d82222f8a2053f2
                      units: 0
                    has_next_page: false
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        asset_id:
                          type: string
                          example: 638888010f1a158347ce9842
                        units:
                          type: integer
                          example: 0
                          default: 0
                  has_next_page:
                    type: boolean
                    example: false
                    default: true
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Result:
                  value:
                    error:
                      code: invalid_parameter_value
                      message: The parameter value is invalid.
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: invalid_parameter_value
                      message:
                        type: string
                        example: The parameter value is invalid.
                    required:
                    - code
                    - message
                required:
                - error
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      deprecated: false
      tags:
      - Video Usage Analytics
      x-stoplight:
        id: difsmxe8e5oaa
      x-codeSamples:
      - label: TypeScript
        lang: TypeScript
        source: "import Gumlet from '@gumlet/nodejs-sdk';\n\nconst client = new Gumlet({\n  apiKey: process.env['API_KEY'], // defaults to the API_KEY env var\n});\n\nconst videoUsageAnalytic = await client.videoUsageAnalytics.topAssets({\n  start_at: '2026-06-21',\n  end_at: '2026-06-30',\n  page: '1',\n  page_size: '1000',\n});\n\nconsole.log(videoUsageAnalytic);"
      - label: Python
        lang: Python
        source: "import os\n\nfrom gumlet import Gumlet\n\nclient = Gumlet(\n    api_key=os.environ.get(\"API_KEY\"),\n)\n\nvideo_usage_analytic = client.video_usage_analytics.top_assets(\n    start_at=\"2026-06-21\",\n    end_at=\"2026-06-30\",\n    page=\"1\",\n    page_size=\"1000\",\n)\n\nprint(video_usage_analytic)"
components:
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: Machine-readable error code
            message:
              type: string
              description: Human-readable error message
            param:
              type: string
              description: Optional parameter name related to the error
  responses:
    Unauthorized:
      description: Unauthorized — missing or invalid API key / bearer token
      content:
        application/json:
          examples:
            Result:
              value:
                error:
                  code: invalid_api_key
                  message: API key supplied with request is invalid
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Forbidden — unpaid account or insufficient role permissions
      content:
        application/json:
          examples:
            Result:
              value:
                error:
                  code: unauthorized
                  message: You don't have access to this feature. Please contact your organization owner.
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    API_KEY:
      type: http
      scheme: bearer
x-tagGroups:
- name: Video on Demand
  tags:
  - Video Assets
  - Global Search
  - Multipart Upload
  - Audio Upload
  - Subtitle Upload
  - Recycle Bin
  - Video Workspaces
  - Folders
  - Video Playlists
  - Channel Viewers
  - Video Usage Analytics
  - Video Profiles
  - Webhooks
- name: Live Streams
  tags:
  - Live Stream Workspaces
  - Live Stream Assets
  - Live Stream Analytics
- name: Image APIs
  tags:
  - Image Sources
  - Image Usage Analytics
- name: Video Analytics
  tags:
  - Video Analytics
- name: Webhooks
  tags:
  - Webhooks
- name: Account Endpoints
  tags:
  - User Data
  - Billing
  - Organization Data
  - Audit Logs
x-ext-urls: {}