OCT-103 Gumlet outreach
POST/video/analytics

Retrieve video usage analytics

Retrieves usage analytics for video assets, including metrics such as bandwidth consumption and top assets. Provide metrics and a date_range with start_at and end_at; the date range can span no more than 60 days. Use group_by to select hourly, daily, or monthly aggregation.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

6 body fields

Video analytics query with the requested metrics, date range, and optional filters and grouping.

date_rangeobjectrequired

The timeframe to get the data for. Currently we only support a maximum of 60 days between start_at and end_at.

filtersobjectoptional

Optional filters for the video workspace. Prefer workspace_id; collection_id and source_id are deprecated alternatives.

group_bystringoptional

Group by hourly, daily or monthly. If you don't specify anything it's hourly by default.

Allowed:hourlydailymonthlyDefault:hourly
metricsarray<string>required

Define the metric you need the data for. Supported values: bandwidth_consumption, asset_duration, storage_unit, top_assets, drm_requests, ai_credit_usage, and errored_videos.

top_assets_countstringoptional

Count of video assets that should be returned. Max assets count is 1000 per page.

Default:5
top_assets_pagestringoptional

top_assets metric may get paginated response. Iterate this parameter to get more data.

Default:0

4 status codes
200Returns an object containing the requested metric data, such as timestamped usage values or top asset details, plus top-asset pagination information when applicable.
ai_credit_usagearray<object>optional
asset_durationarray<object>optional
bandwidth_consumptionarray<object>optional
bandwidth_saving_unitstringoptional

The unit for bandwidth saving data.

Allowed:
drm_requestsarray<object>optional
errored_videosarray<object>optional
has_more_top_assetbooleanoptional

Indicates whether the list of top assets is exhaustive or if it has more assets.

storage_data_unitstringoptional

The unit for the storage data.

Allowed:gbmin
storage_unitarray<object>optional
top_assetsarray<object>optional
400Returned when the request is invalid, including when required analytics fields or valid metric values are missing.

One documented failure

  • invalid_parameter_value

    The parameter value is invalid.

errorobjectrequired
401Returned when the API key or bearer token is missing or invalid.

One documented failure

  • invalid_api_key

    API key supplied with request is invalid

errorobjectrequired
403Returned when the account is unpaid or the authenticated user has insufficient role permissions.

One documented failure

  • unauthorized

    You don't have access to this feature. Please contact your organization owner.

errorobjectrequired

Error handling

A 400 indicates an invalid request; a 401 indicates a missing or invalid API key or bearer token. A 403 indicates an unpaid account or insufficient role permissions. metrics and date_range are required; the date range must contain start_at and end_at in yyyy-MM-dd format and span no more than 60 days, and each metric must be an accepted value.