> For the complete documentation index, see [llms.txt](https://docs.mediamelon.com/mediamelon/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mediamelon.com/mediamelon/smartsight-apis/copy-of-video-session-list-api.md).

# Copy of Video Session List API

Returns a paginated list of individual video sessions. Use it for drill-down analysis and root-cause investigation.

### Endpoint

`GET /mm-apis/listsessions/{customerId}`

{% hint style="info" %}
This endpoint is exclusive to Video Analysis. There is no session-list endpoint for ad analytics.
{% endhint %}

{% hint style="info" %}
Authenticate each request with `X-API-Key`.
{% endhint %}

### Query parameters

| Parameter     | Type    | Required | Default     | Description                                                                                                                        |
| ------------- | ------- | -------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `period`      | string  | Yes      | —           | `start=<epoch>,end=<epoch>`                                                                                                        |
| `metrics`     | string  | Yes      | —           | Lead with the metric under investigation. Include fields such as `starttime`, `endtime`, `assetname`, `watchtime`, and `sessionid` |
| `aggby`       | string  | Yes      | `sessionid` | Must be `sessionid`                                                                                                                |
| `sessiontype` | string  | No       | `ended`     | `ended` or `started`                                                                                                               |
| `allstatus`   | integer | No       | `0`         | `0` or `1`                                                                                                                         |
| `filter`      | string  | No       | —           | Dimension-level filters                                                                                                            |
| `qoefilter`   | string  | No       | —           | Metric-level session filters                                                                                                       |
| `orderby`     | string  | No       | —           | Sort by metric                                                                                                                     |
| `order`       | string  | No       | `desc`      | `asc` or `desc`                                                                                                                    |
| `limit`       | integer | No       | `1000`      | Max records per page                                                                                                               |
| `offset`      | integer | No       | `0`         | Pagination offset                                                                                                                  |

{% hint style="info" %}
Use any metric or dimension from [Metric and Dimensions Dictionary](/mediamelon/smartsight-apis/metrics.md) as the first field in `metrics`. Then add the session fields you want returned.
{% endhint %}

{% tabs %}
{% tab title="Common session metrics" %}

| Metric                        | API value             | Description                                                     |
| ----------------------------- | --------------------- | --------------------------------------------------------------- |
| Startup time (sec)            | `latency`             | Time from play attempt to first frame rendered for this session |
| Rebuffering percentage (%)    | `cirrbufferingratio`  | Percentage of this session's watch time spent rebuffering       |
| Buffering time percentage (%) | `bufferingratio`      | Percentage of watch time in any buffering state                 |
| Playback score                | `qualityofexperience` | QoE score from `0` to `100` for this individual session         |
| Playtime (mins)               | `playdur`             | Total content viewing time for this session                     |
| CDN change rate               | `cdn_change_rate`     | Frequency of CDN switches during this session                   |
| Errors                        | `errors`              | Number of errors that occur during this session                 |
| Fatal errors                  | `fatalerrors`         | Number of fatal errors during this session                      |
| {% endtab %}                  |                       |                                                                 |

{% tab title="Common session dimensions" %}

| Dimension        | API value       | Description                                        |
| ---------------- | --------------- | -------------------------------------------------- |
| Country          | `country`       | Country derived from the viewer's IP address       |
| Device type      | `device`        | Device category, such as mobile, TV, or desktop    |
| Operating system | `platform`      | OS name, such as Android, iOS, or Windows          |
| Player name      | `player`        | Video player library name                          |
| CDN              | `cdn`           | CDN that serves the session                        |
| Asset name       | `assetname`     | Name of the content asset                          |
| Source format    | `sourcetype`    | Streaming format, such as HLS or DASH              |
| Is live stream   | `islive`        | `true` for live streams and `false` for VOD        |
| View status      | `status`        | Final session status, such as `ended` or `dropped` |
| Subscriber ID    | `subscriberid`  | Specific subscriber to look up sessions for        |
| Error code       | `errorcode`     | Sessions that produce a specific error code        |
| DRM              | `drmprotection` | DRM system used during the session                 |
| {% endtab %}     |                 |                                                    |
| {% endtabs %}    |                 |                                                    |

### Standard session fields

| Field        | Description                                       |
| ------------ | ------------------------------------------------- |
| `starttime`  | Session start time in epoch seconds               |
| `endtime`    | Session end time in epoch seconds                 |
| `assetname`  | Name of the video asset played                    |
| `watchtime`  | Total session watch time in seconds               |
| `sessionid`  | MediaMelon unique session identifier              |
| `sourcetype` | Streaming format, such as `HLS`, `DASH`, or `MP4` |

### Example requests

#### Sessions with highest startup delay

```bash
curl --request GET \
  --url 'https://smartsight3.mediamelon.com/mm-apis/listsessions/199493832?period=start=1775749962,end=1775836362&metrics=latency,starttime,endtime,assetname,watchtime,sessionid,sourcetype&aggby=sessionid&orderby=latency&order=desc&limit=25' \
  --header 'X-API-Key: <your-api-key>'
```

#### Sessions with severe buffering on Android

```bash
curl --request GET \
  --url 'https://smartsight3.mediamelon.com/mm-apis/listsessions/199493832?period=start=1775749962,end=1775836362&metrics=cirrbufferingratio,starttime,endtime,assetname,watchtime,sessionid,sourcetype&aggby=sessionid&filter=[platform=Android]&qoefilter=cirrbufferingratio>10&orderby=cirrbufferingratio&order=desc&limit=25' \
  --header 'X-API-Key: <your-api-key>'
```

#### Sessions for a specific subscriber

```bash
curl --request GET \
  --url 'https://smartsight3.mediamelon.com/mm-apis/listsessions/199493832?period=start=1775749962,end=1775836362&metrics=qualityofexperience,starttime,endtime,assetname,watchtime,sessionid,sourcetype&aggby=sessionid&filter=[subscriberid=user-12345]&orderby=starttime&order=desc' \
  --header 'X-API-Key: <your-api-key>'
```