OCT-103 Gumlet outreach
POST/insights/breakdown-data

Get viewer analytics breakdowns

Retrieves viewer metrics grouped by selected breakdown fields for one workspace and a date range. Supply workspace_id, date_range, and between one and three breakdowns; use filters to narrow the viewer data. The date range can span no more than 60 days.

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

4 body fields

Viewer analytics breakdown query for a workspace and date range, with optional filters.

breakdownsarray<object>required

Breakdown fields and metrics to retrieve data for. Supports 1 to 3 breakdowns per request.

date_rangeobjectrequired

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

filtersarray<object>optional

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

workspace_idstringrequired

The five to ten character unique identifier of the Gumlet workspace ID available on the Video Workspaces.

6 status codes
200Returns paginated breakdown results, including the current page, result data, and whether another page is available.
viewsobjectoptional
400Returned when the request is invalid, such as when required fields, valid dates, or the allowed number of breakdowns are not supplied.

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 workspace_id, date_range, and breakdowns; workspace_id must be 5 to 10 characters, the date range must use yyyy-MM-dd dates and span no more than 60 days, and breakdowns must contain 1 to 3 entries.