OCT-103 Gumlet outreach
POST/insights/viewer-analytics

Get viewer analytics

Retrieves viewer analytics for selected metrics over a specified date range. Provide metrics and date_range to choose the measurements and timeframe, and use filters or chart_dimension to segment or group results. The date range can span no more than 60 days.

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

7 body fields

Viewer analytics query with required metrics and date range, plus optional grouping, filtering, workspace, and download settings.

chart_dimensionobjectoptional

Group metrics by the selected dimension. You can select up to 3 dimensions for nested category results; results follow the selection order.

date_rangeobjectrequired

The timeframe to get the data for. The maximum range between start_at and end_at is 60 days.

downloadbooleanoptional

Whether the request is to download the chart data

filtersarray<object>optional

Build segments of users using multiple filters on the data, value should be an exact match

group_bystringoptional

Data can be grouped by daily, weekly or monthly.

Allowed:dailyweeklymonthlyDefault:daily
metricsarray<string>required

Get data for one or more metrics in the same request. Supported values: views, unique_views, impressions, completion_percent_by_views, playing_time, concurrent_users, widget_form_submitted, and cta_clicks.

workspace_idstringoptional

Gumlet workspace ID

6 status codes
200Returns viewer analytics data, including metric series and breakdown results.
analytics_dataobjectoptional
breakdownsobjectoptional
unique_viewsarray<object>optional
viewsarray<object>optional
400Returned when the request is invalid, such as when required analytics fields or valid date values are missing.

One documented failure

  • parameter_missing

    One or more required values are missing.

errorobjectrequired
401Returned when the request is unauthorized.

One documented failure

  • invalid_property_id

    You don't have access to that property, please select a property id

errorobjectoptional
403Returned for an unpaid account or insufficient role permissions.

One documented failure

  • unauthorized

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

errorobjectrequired
404Returned when a requested resource is not found.

One documented failure

  • property_not_found

    Could not find any video insight property with the specified property_id.

errorobjectrequired
500Returned when an internal server error occurs.

One documented failure

  • internal_server_error

    We have encountered some server error. We have been notified and will fix it soon.

errorobjectrequired

Error handling

A 400 is returned when the request is invalid. A 401 indicates an unauthorized request. A 403 is returned for an unpaid account or insufficient role permissions. A 404 indicates that a requested resource was not found. A 500 indicates an internal server error. The body must include metrics and date_range; the date range must use yyyy-MM-dd dates and span no more than 60 days.