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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.mediamelon.com/mediamelon/smartsight-apis/video-session-list-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.