> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://fastpix.com/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://fastpix.com/docs/_mcp/server.

# Find out why viewers drop off

**Business question:** Identify causes of viewer churn.

Here's the API workflow below:

\


## Step 1: Identify low-engagement segments

Use the [list breakdown values](/video-data-api/metrics/list-breakdown-values) endpoint with the `playing_time` metric to find regions/devices with poor engagement:

**`Request Example`**

```bash Request Example
curl --request GET \
     --url 'https://api.fastpix.io/v1/data/metrics/playing_time/breakdown?timespan[]=7:days&limit=10&offset=1&groupBy=country&orderBy=views&sortOrder=asc' \
     --header 'accept: application/json' \
     --user '{Access_Token}:{Secret_Key}'
```

\


The response data shows India (IN) as a low-engagement region because of low total content playing time.

**`Response`**

```json Response
{
  "success": true,
  "metadata": {
    "aggregation": "view_end"
  },
  "data": [
    {
      "views": 500,
      "value": 57165,
      "totalWatchTime": 83208,
      "totalPlayingTime": 57165,
      "field": "IN"
    },
    {
      "views": 4980,
      "value": 2624467,
      "totalWatchTime": 913048,
      "totalPlayingTime": 2624467,
      "field": "US"
    }
  ],
  "pagination": {
    "totalRecords": 2,
    "currentOffset": 1,
    "offsetCount": 1
  },
  "timespan": [
    1712915263,
    1713520063
  ]
}
```

\


## Step 2: Fetch views from the low-engagement region

Use [list video views](/video-data-api/views/list-video-views) endpoint with a `country=IN` filter to retrieve all views from the region "India":

\


**`Request Example`**

```bash Request Example
curl --request GET \
     --url 'https://api.fastpix.io/v1/data/viewlist?timespan[]=7:days&filterBy[]=country:IN&limit=10&offset=1&orderBy=view_end&sortOrder=asc' \
     --header 'accept: application/json' \
     --user '{Access_Token}:{Secret_Key}'
```

\


This API request returns views with `viewWatchTime` included in each entry (even if not filterable).

\


**`Response`**

```json Response
{
  "success": true,
  "data": [
    {
      "viewId": "92752c49-1bce-4cf8-bea4-5c2c2ac7575d",
      "operatingSystem": "MacOS",
      "application": "Chrome",
      "viewStartTime": "2024-04-15T04:43:44",
      "viewEndTime": "2024-04-15T04:44:05",
      "videoTitle": "Champion Engagement Model: Best practices for identifying and engaging your champion",
      "errorCode": null,
      "errorMessage": null,
      "errorId": null,
      "country": "IN",
      "viewWatchTime": 10016,
      "QoeScore": 0.9559243591134252
    },
    {
      "viewId": "aa3f20e4-6065-4c7c-aed5-c7f8d127bcba",
      "operatingSystem": "MacOS",
      "application": "Chrome",
      "viewStartTime": "2024-04-15T11:31:48",
      "viewEndTime": "2024-04-15T11:32:30",
      "videoTitle": "How to reduce time-to-value for your customers",
      "errorCode": null,
      "errorMessage": null,
      "errorId": null,
      "country": "IN",
      "viewWatchTime": 31926,
      "QoeScore": 0.9585203020685126
    },
    {
      "viewId": "687b3a54-6646-4343-bfbe-459742042f54",
      "operatingSystem": "MacOS",
      "application": "Chrome",
      "viewStartTime": "2024-04-16T09:20:34",
      "viewEndTime": "2024-04-16T09:21:24",
      "videoTitle": "How to Approach an Irate Customer With Mimecast's Alice Jeffery",
      "errorCode": null,
      "errorMessage": null,
      "errorId": null,
      "country": "IN",
      "viewWatchTime": 13493,
      "QoeScore": 0.47256304495379314
    },
    {
      "viewId": "c1464fdb-f3f8-4ccd-8914-94e1851e8459",
      "operatingSystem": "MacOS",
      "application": "Chrome",
      "viewStartTime": "2024-04-16T09:22:42",
      "viewEndTime": "2024-04-16T09:22:45",
      "videoTitle": "How to Approach an Irate Customer With Mimecast's Alice Jeffery",
      "errorCode": null,
      "errorMessage": null,
      "errorId": null,
      "country": "IN",
      "viewWatchTime": 1,
      "QoeScore": 0.5
    }
  ],
  "pagination": {
    "totalRecords": 500,
    "currentOffset": 1,
    "offsetCount": 25
  },
  "timespan": [
    1712915263,
    1713520063
  ]
}
```

\


## Step 3: Client-side filtering for short sessions

Manually filter the response to isolate sessions with low `viewWatchTime` (e.g., \<30 seconds).

Example client-side filtering:

```python
low_engagement_views = [
  view for view in response["data"]
  if view["viewWatchTime"] < 30000
]
```

\


## Step 4: Diagnose issues in short view sessions

You can use the [get video view details](/video-data-api/views/get-video-view-details) endpoint to inspect individual sessions:

```bash
curl --request GET \
     --url https://api.fastpix.io/v1/data/viewlist/92752c49-1bce-4cf8-bea4-5c2c2ac7575d \
     --header 'accept: application/json' \
     --user '{Access_Token}:{Secret_Key}'
```

\


**`Response`**

```json Response
{
  "success": true,
  "data": {
    "asnId": 18209,
    "asnName": "AS18209 Atria Convergence Technologies Ltd.,",
    "averageBitrate": 2807994,
    "browserName": "Chrome",
    "cdn": "Cloudflare",
    "city": "Hyderābād",
    "continent": "AS",
    "country": "India",
    "countryCode": "IN",
    "deviceManufacturer": "Apple",
    "deviceModel": "Macintosh",
    "deviceType": "Desktop",
    "errorCode": "networkError",
    "errorMessage": "fragLoadError",
    "exitBeforeVideoStart": false,
    "playbackScore": 0,
    "qualityOfExperienceScore": 0,
    "region": "Telangana",
    "stabilityScore": 1,
    "startupScore": 0.9247485839787308,
    "videoTitle": "Knives Out",
    "viewHasError": true,
    "viewId": "b910582b-d0ef-49c6-9219-2d7f5c622ec2",
    "watchTime": 23338,
    "events": [
      { "event_name": "playerReady", "player_playhead_time": 0 },
      { "event_name": "viewBegin", "player_playhead_time": 0 },
      { "event_name": "play", "player_playhead_time": 0 },
      { "event_name": "playing", "player_playhead_time": 0 },
      {
        "event_name": "requestFailed",
        "event_details": {
          "hostname": "cdn.fastpix.io",
          "error": "fragLoadError",
          "type": "manifest"
        },
        "player_playhead_time": 408009
      },
      {
        "event_name": "error",
        "event_details": {
          "player_error_message": "fragLoadError",
          "player_error_code": "networkError"
        },
        "player_playhead_time": 585000
      },
      { "event_name": "viewCompleted", "player_playhead_time": 413988 }
    ]
  }
}
```

\


## Step 5: Segment the error for deeper analysis

Based on the diagnosis of individual sessions, network errors are rampant. So the best idea would be to filter these views. To apply appropriate filter one can use listing the dimensions and it will [list all the available dimensions](/video-data-api/dimensions/list-dimensions).

\


**`Request`**

```bash Request
curl --request GET \
     --url https://api.fastpix.io/v1/data/dimensions \
     --header 'accept: application/json'
```

\


**`Response`**

```json Response
{
  "success": true,
  "data": [
    "browser_name",
    "browser_version",
    "os_name",
    "device_type",
    "player_name",
    "video_title",
    "video_id",
    "fp_playback_id",
    "asn_name",
    "cdn",
    "video_source_hostname",
    "country",
    "region",
    "viewer_id",
    "error_code",
    "exit_before_video_start",
    "video_startup_failed",
    "playback_failed"
  ]
}
```

\


From the response, you have all the dimensions to segment the data further. But, since you might want to further drill into the errors, you would need the `error_code` dimension for the next steps.

\


> **PLEASE NOTE**
>
> If you are already aware of the dimensions, then you can ignore this step or restrain from repeating this step again.

\


## Step 6: Comparing error percentages by ASN

Since we already know that the issue is **network errors** we will check which ASN is facing more issue by breaking the error percentages across the ASN values using the [list breakdown values](/video-data-api/metrics/list-breakdown-values) API.

Here you can use the `playback_failure_percentage` metric ID and get the breakdown values for all the views with `error_code` as `network_error`. Further to know the error percentage across different ASN, use `groupBy=asn`.

\


**`Request`**

```bash Request
curl --request GET \
     --url 'https://api.fastpix.io/v1/data/metrics/playback_failure_percentage/breakdown?filterby[]=error_code:network_error&limit=10&offset=1&groupBy=asn&orderBy=views&sortOrder=asc' \
     --header 'accept: application/json'
```

\


**`Response`**

```json Response
{
  "success": true,
  "metadata": {
    "aggregation": "view_end"
  },
  "data": [
    {
      "views": 6,
      "value": 0.6,
      "totalWatchTime": 255397,
      "totalPlayingTime": 1190975,
      "field": "AS18209 Atria Convergence Technologies Ltd.,"
    },
    {
      "views": 4,
      "value": 0.4,
      "totalWatchTime": 296827,
      "totalPlayingTime": 1290034,
      "field": "US23207 LB Network Technologies,"
    }
  ],
  "pagination": {
    "totalRecords": 2,
    "currentOffset": 1,
    "offsetCount": 1
  },
  "timespan": [
    1740393396,
    1742985396
  ]
}
```

\


This response shows two ASN names with the error percentages as 60% (0.6) and 40% (0.4) along with the total number of views affected by the error.

**Outcome:** If `fragLoadError` rises from missing files, encoding issues, or server misconfigurations, fixing those problems should take priority over CDN optimization. However, if network-related issues like latency, congestion, or routing inefficiencies are contributing factors, then optimizing your CDN setup for ASN AS18209 Atria Convergence Technologies Ltd., can help mitigate these problems and improve playback reliability.

\


## See also

* [Build workflows with the API](/video-data/build-workflows-with-the-api) — overview of API-driven workflows
* [Identify top-performing content](/video-data/identify-top-performing-content) — another worked example
* [What Video Data do we capture](/video-data/what-video-data-do-we-capture) — every dimension, event, and metric we capture