> 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/accessing-the-api.md).

# Overview

MediaMelon SmartSight provides a REST API for programmatic access to video and ad analytics.

Use these APIs to build dashboards, integrate with your data pipelines, generate reports, and investigate QoE issues.

### What the API Does

The SmartSight API lets you query aggregated set of metrics across any combination of dimensions, time ranges with multiple dimension filters and metric-level conditions — returning exactly the data you need in a single call.

<table><thead><tr><th width="292.01171875">Capability</th><th>Description</th></tr></thead><tbody><tr><td>Metric queries</td><td>Retrieve any video session or ad related metric, such as startup time, buffering ratio, ad impressions, and many others aggregated by time, dimension, or both</td></tr><tr><td>Dimension breakdowns</td><td>Break down any metric by combination of dimension including country, device, CDN, player, content, subscriber, and more. </td></tr><tr><td>Time-series trends</td><td>Get bucketed time-series data at minute, hour, or day granularity</td></tr><tr><td>Session-level data</td><td>Retrieve metrics and dimension values set on individual sessions along with the complete list of player sent events and errors for root-cause investigation. </td></tr><tr><td>Filtered queries</td><td>Scope any query to a subset of video sessions using dimension filters or metric-level conditions</td></tr></tbody></table>

### Getting Started

#### Step 1 — Get your Customer ID

Login to the MediaMelon SmartSight dashboard and navigate to `User Icon > Settings > Environments > Env Details`. Find the customer ID for the environment you want to make API requests.&#x20;

<figure><img src="/files/u2BuHKnuZC8JJqAUO2f1" alt=""><figcaption></figcaption></figure>

#### Step 2 — Obtain your API Key

Contact MediaMelon support or your account team to obtain your API key.

#### Step 3 — Choose an Endpoint

Use the metric query endpoint for aggregated analytics.

Use the session list endpoint for per-session video investigation.

#### Step 4 — Build Your Query

Every query must include `period` and `metrics`.

Add `aggby`, `filter`, `qoefilter`, `orderby`, and `limit` as needed.

#### Step 5 — Make the Request

**Base API Hostname** - `https://smartsight.mediamelon.com`&#x20;

**Authentication** - Add your API key to each request for authentication.

```http
X-API-Key: <your-api-key>
```

Use `curl` or similar tools to make the API request with the `X-API-Key` header. Below is an example of the API request to get Startup Time and Started Views count metrics over time to show these metrics in a time-series graph.&#x20;

{% code overflow="wrap" %}

```bash
curl --request GET \
  --url 'https://smartsight.mediamelon.com/mm-apis/metricquery/199493832?period=start=1775749920,end=1775836379&metrics=latency,viewercount&aggby=timestamp&granularity=hour&orderby=timestamp&order=asc' \
  --header 'X-API-Key: <your-api-key>'
```

{% endcode %}

### API Endpoints at a Glance

{% hint style="warning" %}
As of July 2025, `/mm-apis/qbrData/vod` and `/mm-apis/session` are deprecated. Use `/mm-apis/metricquery` instead. Backward compatibility remains available, but `/mm-apis/metricquery` provides access to newer features.
{% endhint %}

<table><thead><tr><th width="171.578125">Method</th><th width="330.71875">Endpoint</th><th width="159.15234375">Scope</th><th>Description</th></tr></thead><tbody><tr><td><code>GET</code></td><td><code>/mm-apis/metricquery/{customerId}</code></td><td>Video Sessions + Ad</td><td>Aggregated metrics for video sessions and ads for trend graphs, tables, KPI tiles, and comparisons.</td></tr></tbody></table>

### Common Query Parameters

<table><thead><tr><th width="162.0859375">Parameter</th><th width="116.8203125">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>period</code></td><td>Yes</td><td><code>start=&#x3C;epoch_seconds>,end=&#x3C;epoch_seconds></code></td></tr><tr><td><code>metrics</code></td><td>Yes</td><td>Comma-separated metric field names</td></tr><tr><td><code>aggby</code></td><td>No</td><td>Breakdown by a combination of dimension or <code>timestamp</code> for time-series</td></tr><tr><td><code>filter</code></td><td>No</td><td>Dimension filters, such as <code>[country=US|Canada][platform=Android]</code></td></tr><tr><td><code>qoefilter</code></td><td>No</td><td>Metric-level conditions to filter, such as <code>latency>3 AND bufferingratio>5</code></td></tr><tr><td><code>orderby</code></td><td>No</td><td>Sort by metric or dimension name</td></tr><tr><td><code>order</code></td><td>No</td><td>Sorting order - <code>asc</code> or <code>desc</code></td></tr><tr><td><code>limit</code></td><td>No</td><td>Number of records to include in the response, aka Page size. Default is <code>1000</code></td></tr><tr><td><code>offset</code></td><td>No</td><td>Record offset to include from in the response. Default is <code>0</code></td></tr></tbody></table>

### Response Structure

{% code lineNumbers="true" %}

```json
{
  "totalcount": 25,
  "pagecount": 4,
  "totalrecords": 100,
  "response": [
    {
      "country": "US",
      "latency": 1.82,
      "concurviewavg": 412
    },
    {
      "country": "GB",
      "latency": 2.14,
      "concurviewavg": 187
    }
  ]
}
```

{% endcode %}

<table><thead><tr><th width="201.2734375">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>totalcount</code></td><td>Number of records in the current response</td></tr><tr><td><code>pagecount</code></td><td>Total number of pages in the full result set</td></tr><tr><td><code>totalrecords</code></td><td>Total matching records across all pages</td></tr><tr><td><code>response</code></td><td>Array of result objects that includes values for <code>metrics</code> and dimensions requested. Use the <a href="/spaces/-MdvF6AnMWuH7LB6LAsd/pages/-Mk1DfF5B_DcsmhRR1Mz">Metric and Dimensions Dictionary</a> for the list video and ad related metrics, dimensions, and aggregate variants available such as <code>p95_latency</code>.</td></tr></tbody></table>

### Timestamps

Use Unix epoch seconds in UTC for all request time ranges and response timestamps.