Turn viewer engagement data into plain-language insights for a Mux video asset using the Mux Robots API.
Experimental
The generate-engagement-insights workflow is experimental. The API shape, parameters, behavior, and pricing may change. If we make changes to this workflow while you're using it, we'll let you know via email.
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.
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/v0/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.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/v0/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.job.generate_engagement_insights.completed webhook (recommended), or you can fetch it with GET /robots/v0/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_ms | number | Moment start time in milliseconds. |
moment_insights[].end_ms | number | Moment end time in milliseconds. |
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 payload delivered to the robots.job.generate_engagement_insights.completed webhook, and the same shape you get from GET /robots/v0/jobs/generate-engagement-insights/{JOB_ID}:
{
"data": {
"id": "rjob_eng123",
"workflow": "generate-engagement-insights",
"status": "completed",
"units_consumed": 1,
"parameters": {
"asset_id": "YOUR_ASSET_ID"
},
"outputs": {
"moment_insights": [
{
"start_ms": 30000,
"end_ms": 60000,
"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"
]
}
}
}
}