> 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/video-session-list-api.md).

# 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 by adding  `X-API-Key`  HTTP Request header. 
{% endhint %}

### Query parameters

<table data-first-column-sticky><thead><tr><th width="109.3671875">Name</th><th width="101.72265625">Type</th><th width="92.47265625">Required</th><th width="126.375">Default</th><th>Format / Possible Values</th><th>Description</th></tr></thead><tbody><tr><td><code>period</code></td><td>string</td><td>Yes</td><td>—</td><td><code>start=&#x3C;epoch>,end=&#x3C;epoch></code></td><td>Time range in Unix epoch seconds</td></tr><tr><td><code>metrics</code></td><td>string</td><td>Yes</td><td>—</td><td><code>metric1,metric2,...</code></td><td>Comma-separated metric field names</td></tr><tr><td><code>aggby</code></td><td>string</td><td>No</td><td>—</td><td><code>&#x3C;dimension></code>, <code>timestamp</code></td><td>Group by dimension or time</td></tr><tr><td><code>sessiontype</code></td><td>string</td><td>No</td><td><code>ended</code></td><td><code>ended</code> , <code>started</code></td><td><p>Sessions to include in the response. </p><ul><li><code>started</code>: Add sessions that started in the <code>period</code>  </li><li><code>ended</code>: Add sessions that ended in the <code>period</code> </li></ul></td></tr><tr><td><code>allstatus</code></td><td>integer</td><td>No</td><td><code>0</code></td><td><code>0</code> , <code>1</code></td><td><code>1</code> includes sessions with any <code>viewstatus</code> value including <code>RUNNING</code> and <code>LOADED</code> sessions</td></tr><tr><td><code>granularity</code></td><td>string</td><td>No</td><td><code>auto</code></td><td><code>auto</code>, <code>minute</code>, <code>5minute</code>, <code>10minute</code>, <code>hour</code>, <code>day</code></td><td><p>Time bucket size. <br></p><p>Set this parameter only with <code>aggby=timestamp</code></p></td></tr><tr><td><code>filter</code></td><td>string</td><td>No</td><td>—</td><td><code>[dimension=value]</code></td><td>Dimension-level filters</td></tr><tr><td><code>qoefilter</code></td><td>string</td><td>No</td><td>—</td><td><code>metric1>value1 AND metric2>value2</code></td><td>Session-level metric filters</td></tr><tr><td><code>orderby</code></td><td>string</td><td>No</td><td>—</td><td>metric or dimension</td><td>Sort reocrds by the value of the metric or dimension</td></tr><tr><td><code>order</code></td><td>string</td><td>No</td><td><code>desc</code></td><td><code>asc</code> or <code>desc</code></td><td>Sort direction</td></tr><tr><td><code>limit</code></td><td>integer</td><td>No</td><td><code>1000</code></td><td>integer</td><td>Max records per page/query</td></tr><tr><td><code>offset</code></td><td>integer</td><td>No</td><td><code>0</code></td><td>integer</td><td>Pagination offset</td></tr><tr><td><code>concurrency</code></td><td>integer</td><td>No</td><td><code>0</code></td><td><code>0</code> , <code>1</code></td><td><code>1</code> indicates the metric value calculated is based on the metric related event occurrence in the requested time range. <br><br><code>0</code> indicates the metric value calculated is cumulative of all the occurrences of that metric related events. </td></tr><tr><td><code>businesserror</code></td><td>boolean</td><td>No</td><td><code>false</code></td><td><code>true</code> , <code>false</code></td><td>Include business exception errors in error metrics</td></tr></tbody></table>

<table data-header-hidden="false" data-header-sticky><thead><tr><th width="140.3828125">Name</th><th width="108.06640625">Type</th><th width="106.84765625">Required</th><th width="137.9140625">Default</th><th>Format / Possible Values</th><th>Description</th></tr></thead><tbody><tr><td><code>period</code></td><td>string</td><td>Yes</td><td>—</td><td><code>start=&#x3C;epoch>,end=&#x3C;epoch></code></td><td>Time range in Unix epoch seconds</td></tr><tr><td><code>metrics</code></td><td>string</td><td>Yes</td><td>—</td><td><code>metric1,metric2,...</code></td><td>List of Metrics and Dimensions to include</td></tr><tr><td><code>aggby</code></td><td>string</td><td>Yes</td><td><code>sessionid</code></td><td><code>sessionid</code></td><td>Group response records by <code>sessionid</code></td></tr><tr><td><code>sessiontype</code></td><td>string</td><td>No</td><td><code>ended</code></td><td><code>ended</code>, <code>started</code></td><td><p>Sessions to include in the response. </p><ul><li><code>started</code>: Add sessions that started in the <code>period</code>  </li><li><code>ended</code>: Add sessions that ended in the <code>period</code> </li></ul></td></tr><tr><td><code>allstatus</code></td><td>integer</td><td>No</td><td><code>0</code></td><td><code>0</code> , <code>1</code></td><td></td></tr><tr><td><code>filter</code></td><td>string</td><td>No</td><td>—</td><td></td><td>Dimension-level filters</td></tr><tr><td><code>qoefilter</code></td><td>string</td><td>No</td><td>—</td><td></td><td>Metric-level session filters</td></tr><tr><td><code>orderby</code></td><td>string</td><td>No</td><td>—</td><td></td><td>Sort by metric</td></tr><tr><td><code>order</code></td><td>string</td><td>No</td><td><code>desc</code></td><td><code>asc</code> , <code>desc</code></td><td></td></tr><tr><td><code>limit</code></td><td>integer</td><td>No</td><td><code>1000</code></td><td></td><td>Max records per page</td></tr><tr><td><code>offset</code></td><td>integer</td><td>No</td><td><code>0</code></td><td></td><td>Pagination offset</td></tr></tbody></table>

{% 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 %}

### Example requests

#### Sessions with highest startup delay

{% code overflow="wrap" %}

```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>'
```

{% endcode %}

#### Sessions with severe buffering on Android

{% code overflow="wrap" %}

```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>'
```

{% endcode %}

#### Sessions for a specific subscriber

{% code overflow="wrap" %}

```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>'
```

{% endcode %}

### 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` |

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

<table><thead><tr><th width="241.1328125">Metric</th><th width="186.609375">API value</th><th>Description</th></tr></thead><tbody><tr><td>Startup time (sec)</td><td><code>latency</code></td><td>Time from play attempt to first frame rendered for this session</td></tr><tr><td>Rebuffering percentage (%)</td><td><code>cirrbufferingratio</code></td><td>Percentage of this session's watch time spent rebuffering</td></tr><tr><td>Buffering time percentage (%)</td><td><code>bufferingratio</code></td><td>Percentage of watch time in any buffering state</td></tr><tr><td>Playback score</td><td><code>qualityofexperience</code></td><td>QoE score from <code>0</code> to <code>100</code> for this individual session</td></tr><tr><td>Playtime (mins)</td><td><code>playdur</code></td><td>Total content viewing time for this session</td></tr><tr><td>CDN change rate</td><td><code>cdn_change_rate</code></td><td>Frequency of CDN switches during this session</td></tr><tr><td>Errors</td><td><code>errors</code></td><td>Number of errors that occur during this session</td></tr><tr><td>Fatal errors</td><td><code>fatalerrors</code></td><td>Number of fatal errors during this session</td></tr></tbody></table>
{% 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 %}    |                 |                                                    |