> 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.


---

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

```
GET https://docs.mediamelon.com/mediamelon/smartsight-apis/accessing-the-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.