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


---

# 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/copy-of-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.