Turn viewer engagement data into plain-language insights for a Mux video with the Mux Robots API. Use the insights to learn where viewers drop off and why.
Generate plain-language insights from how viewers watched a video. This workflow analyzes the engagement patterns Mux Data has collected for an asset (which moments held attention and which lost it) and returns per-moment insights for the most notable moments plus an overall summary and trends. It's useful for explaining retention to non-analysts, prioritizing edits, and surfacing what's working across a library. See the Generate Engagement Insights API referenceAPI for the full endpoint specification. See Mux Robots pricing for unit costs.
Check the shared workflow prerequisites before creating a job.
Generate engagement insights builds on Mux Data engagement metrics, so the asset needs accumulated viewing data before there's anything to analyze. You'll need:
generate-engagement-insights jobcurl https://api.mux.com/robots/v1/jobs/generate-engagement-insights \
-H "Content-Type: application/json" \
-X POST \
-d '{
"parameters": {
"asset_id": "YOUR_ASSET_ID"
}
}' \
-u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}This request is asynchronous. The POST returns immediately with the job in pending status and does not include results. We strongly recommend listening for the robots.v1.job.generate_engagement_insights.completed webhook. The payload contains the full completed job, so no follow-up API call is needed. If webhooks aren't an option, you can poll GET /robots/v1/jobs/generate-engagement-insights/{JOB_ID} with the id from the response until the status is completed.
| Parameter | Type | Description |
|---|---|---|
asset_id | string | Required. The Mux asset ID of the video to analyze engagement for. |
The outputs object is included in the job once its status is completed. You'll receive it on the robots.v1.job.generate_engagement_insights.completed webhook (recommended), or you can fetch it with GET /robots/v1/jobs/generate-engagement-insights/{JOB_ID}. It contains:
| Field | Type | Description |
|---|---|---|
moment_insights | array | Per-moment engagement insights for the most notable moments. |
moment_insights[].start_time | number | Moment start time in seconds on the asset timeline. Fractional seconds are supported. |
moment_insights[].end_time | number | Moment end time in seconds on the asset timeline. Fractional seconds are supported. |
moment_insights[].engagement_score | number | Normalized engagement score from 0 to 1. |
moment_insights[].insight | string | Primary insight explaining the engagement pattern for the moment. |
overall_insight | object | Overall engagement analysis across the video. |
overall_insight.summary | string | Summary of overall engagement patterns. |
overall_insight.trends | array of strings | Key trends identified across the video. |
This is the job delivered in the robots.v1.job.generate_engagement_insights.completed webhook's data field and returned by GET /robots/v1/jobs/generate-engagement-insights/{JOB_ID}:
{
"data": {
"id": "rjob_eng123",
"workflow": "generate-engagement-insights",
"status": "completed",
"units_consumed": 2000,
"created_at": 1746403200,
"updated_at": 1746403260,
"parameters": {
"asset_id": "YOUR_ASSET_ID"
},
"outputs": {
"moment_insights": [
{
"start_time": 30.0,
"end_time": 60.0,
"engagement_score": 0.89,
"insight": "Viewers are highly engaged during the product demo, with minimal drop-off."
}
],
"overall_insight": {
"summary": "Engagement peaks during hands-on demonstrations and drops during introductory segments.",
"trends": [
"Product demos drive the highest retention",
"Viewers skip past the first 15 seconds of intro"
]
}
}
}
}