API Overview

Welcome to MediaMelon's SmartSight Analytics API developer documentation. This guide outlines how to access the these APIs and use them to access real-time and historical data.

The MediaMelon SmartSight Analytics APIs provide programmatic access to all the data which is currently visualized in the Smartsight web portal. You can use these RESTful API endpoints to build custom dashboards, extract data for warehouse purposes, or ingest data into third-party tools. MediaMelon APIs can be easily integrated into your applications and provide HTTP response codes to indicate API errors. The APIs are secured via OAuth2 authentication.

There are 2 sets of MediaMelon APIs as mentioned down here :

1. SmartSight Metrics and Dimensions APIs

   • Metrics

   • Dimensions

2. SmartSight Smartquery APIs

   • Subscriber Insights

Prerequisites

To fetch data from the backend, Smarthsight Analytics API authenticates users via an OAuth Token. To obtain this token, you need these prerequisites:

1. Username - Your SmartSight username

2. Password - Your SmartSight password

Contact your MediaMelon representative in case you're not aware of the above mentioned prerequisites

Fetch Auth Token POST

Updated SmartSight token for authentication based off Keycloak integration.

curl 'https://identity.mediamelon.com/realms/mediamelon/protocol/openid-connect/token'\
-x POST
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username=<email-ID>' \
--data-urlencode 'password=<password>' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'client_id=smartsight-backend' \
--data-urlencode 'scope=openid'

Required request body parameters

username string

A body parameter in form of a string with Smartsight Username value

password string

A body parameter in form of a string with Smartsight Password value

grant_type string

A body parameter in form of a string with "password" as value

client_id string

A body parameter in form of a string set to smartsight-backend

scope string

A body parameter in form of a string set to openid

Response

POST 201

{
    "access_token": "eyW50LWxpbmtzIiwidmlldy1wcm9maWxlIl19fSwic2NvcGUiOiJvcGVuaWQgZW1haWwgcHJvZmlsZSIsImVt0eXAiOiJCZWFyZXIiLCJhenAiOiJzbWFydHNpZ2h0LWJhY2tlbmQiLCJzaWQiOiI5NjdjMDJlNS1hOTYyLTRmY2QtYTEyNC1lMjU1ZDA5NmM3NzgiLCJhY3IiOiIxIiwiYWxsb3dlZC1vcmlnaW5zIjpbIioiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwiZGVmYXVsdC1yb2xlcy1tZWRpYW1lbG9uIiwidW1hX2F1dGhvcml6YXRpb24iLCJVU0VSIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsIm1hbmFnZS1hY2NvddXN0SWQiOiIxOTk0OTM4MzIiLCJncm91cHMiOlsib2ZmbGluZV9hY2Nlc3MiLCJkZWZhdWx0LXJvbGVzLW1YWlsX3ZlcmlmaWVkIjp0cnVlLCJsZXZlbCI6IjI3MzUiLCJhY2NvdW50VHlwZSI6Ik1NQ1VTVE9NRVIiLCJuYW1lIjoiTWVkaWFtZWxvbiBUZXN0IiwiY3VzdElkIjoiMTk5NDkzODMyIiwiZ3JvdXBzIjpbIm9mZmxpbmVfYWNjZXNzIiwiZGVmYXVsdC1yb2xlcy1tZWRpYW1lbG9uIiwidW1hX2F1dGhvcml6YXRpb24iLCJVU0VSIl0sInByZWZlcnJlZF91c2VybmFtZSI6Im1tc3N0ZXN0YWRtaW5AbW0uY29tIiwiZ2l2ZW5fbmFtZSI6Ik1lZGlhbWVsb24iLCJmYW1pbHlfbmFtZSI6IlRlc3QiLCJlbWFpbCI6Im1tc3N0ZXN0YWRtaW5AbW0uY29tIiwiZ3JvdXAiOlsiL0EmRSAoMTk5NDkzODMyKSJdfQ.e5Kxbss5pK1Miwc9v0615ADjxAIsQWjT99kliRoJwdUTpDhd6fhj1SpZGpDg_-4zOo0BVlJ_TeMvlY9MEtnEp-RWoV4-2CNMWV8b2QEgPGkEkqF_WmNKikPGiIyJju9ulqnGT2EPGdqvwrkOgb9IYzzTIEv-0OVwSeKVG-vs3EZ03_b-p2Hs8TwD2mx8EfV_6ABf1x1tQPT8wEdvjzl91_WiHWxS4JAsvCLFwG8AHksdiHfSP247qn-3yjKDXvCXJWAVhfFor2RjJPRoDmZ-urhLi2QKRDqofBq_RiqO_b4schdMbaUPhgHMN_oSBrOx94yHK9i0jsBFM5FiGwrQsw",
    "expires_in": 900,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJhbGciOyb2xlcy1tZWRpYW1lbG9uIiwidW1hX2F1dGhvcml6YXRpb24iLCJVU0VSIl0sInByZWZlcnJlZF91c2VybmFtZSI6Im1tc3N0ZXN0YWRtaW5AbW0uY29tIiwiZ2l2ZW5fbmFtZSI6Ik1lZGlhbWVsb24iLCJmYW1pbHlfbmFtZSI6IlRlc3QiLCJlbWFTRkMDQtYWFjNS0xY2UxNmIyN2JlYjAiLCJ0eXAiOiJSZWZyZXNoIiwiYXpwIjoic21hcnRzaWdodC1iYWNrZW5kIiwic2lkIjoiOTY3YzAyZTUtYTk2Mi00ZmNkLWExMjQtZTI1NWQwOTZjNzc4Iiwic2NvcGUiOiJvcGVuaWQgYWNyIGJhc2ljIHdlYi1vcmlnaW5zIGVtYWlsIHByb2ZpbGUgcm9sZXMifQ.-RZa2S4WTypphnlhb6SLQx080yrBRfGF8FsJvT6m1GZ3sKYBf23CMx_XfYJZjXVkrkb74XcyAIezLABmLp-H_Q",
    "token_type": "Bearer",
    "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhWTI2aG12YmczSm1ESzVRNDFFcJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhWTI2aG12YmczSm1ESzVRNDFFc2UyZkJoeFNRRExXSUtYbnYwM3gtekNRIn0.eyJleHAiOjE3MzEzMTc4OTIsImlhdCI6MTczMTMxNjk5MiwianRpIjoiMWYwZTkwZTQtNzkzNy00ZjQ1LTk5YTUtNGI1MWQzY2M3NjA4IiwiaXNzIjoiaHR0cHM6Ly9pZGVudGl0eS5tZWRpYW1lbG9uLmNvbS9yZWFsbXMvbWVkaWFtZWxvbiIsImF1ZCI6ImFj05NTM5NjRiMTYzMzUifQ.eyJleHAiOjE3MzEzMTg3OTIsImlhdCI6MTczMTMxNjk5MiwianRpIjoiZWYxMDdjZDMtMzViMS00NDRlLWJmZjEtODkyOWMyNzBjMDVhIiwiaXNzIjoiaHR0cHM6Ly9pZGVudGl0eS5tZWRpYW1lbG9uLmNvbS9yZWFsbXMvbWVkaWFtZWxvbiIsImF1ZCI6Imh0dHBzOi8vaWRlbnRpdHkubWVkaWFtZWxviVGVzdCIsImVtYWlsIjoibW1zc3Rlc3RhZG1pbkBtbS5jb20iLCJncm91cCI6WyIvQSZFICgxOTk0OTM4MzIpIl19.xtbrf27jUiCpUrwenPp19GZEGOazjYkdo0KVoFsrdeyiF4MB2YDzU963tw6FXetys9Qty-HKelD-pskhjb8sYzpBYCtKp9iQnC-7lNNsJXxsYnfS4reffVy2kH4NgXtQvSxUzZEXKJ1zr2BcWGOpBhIf2yzQubE4OyzoRwFH5I0TFNiXTr_fwVXoZPzPNvrr1M-E6HPAyLEBE1t8vkUOPTN6s25TW7ZHO4agSNfI_MhLw7i8bt-ocIpsfBwzPi83R90rq9qWQeFFVm53AzlDzXTqLSYEkQWZE1KXNTmu0XhQeLMJrUyfM6FcJKWzvfyi7Lgjvi3jVUNzO938_4cU0w",
    "not-before-policy": 0,
    "session_state": "967c02e5-a962-4fcd-a124-e255d096c778",
    "scope": "openid email profile"
}

Once you run this POSTrequest, make note of the access_token which needs to be used for making other subsequent POST, GET, PUT, PATCH, and DELETE requests to the MediaMelon APIs. This token needs to be included in every request as :

--header 'Authorization: Bearer eyW50LWxpbmtzIiwidmlldy1wcm9maWxlIl19fSwic2NvcGUiOiJvcGVuaWQgZW1haWwgcHJvZmlsZSIsImVt0eXAiOiJCZWFyZXIiLCJhenAiOiJzbWFydHNpZ2h0LWJhY2tlbmQiLCJzaWQiOiI5NjdjMDJlNS1hOTYyLTRmY2QtYTEyNC1lMjU1ZDA5NmM3NzgiLCJhY3IiOiIxIiwiYWxsb3dlZC1vcmlnaW5zIjpbIioiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwiZGVmYXVsdC1yb2xlcy1tZWRpYW1lbG9uIiwidW1hX2F1dGhvcml6YXRpb24iLCJVU0VSIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsIm1hbmFnZS1hY2NvddXN0SWQiOiIxOTk0OTM4MzIiLCJncm91cHMiOlsib2ZmbGluZV9hY2Nlc3MiLCJkZWZhdWx0LXJvbGVzLW1YWlsX3ZlcmlmaWVkIjp0cnVlLCJsZXZlbCI6IjI3MzUiLCJhY2NvdW50VHlwZSI6Ik1NQ1VTVE9NRVIiLCJuYW1lIjoiTWVkaWFtZWxvbiBUZXN0IiwiY3VzdElkIjoiMTk5NDkzODMyIiwiZ3JvdXBzIjpbIm9mZmxpbmVfYWNjZXNzIiwiZGVmYXVsdC1yb2xlcy1tZWRpYW1lbG9uIiwidW1hX2F1dGhvcml6YXRpb24iLCJVU0VSIl0sInByZWZlcnJlZF91c2VybmFtZSI6Im1tc3N0ZXN0YWRtaW5AbW0uY29tIiwiZ2l2ZW5fbmFtZSI6Ik1lZGlhbWVsb24iLCJmYW1pbHlfbmFtZSI6IlRlc3QiLCJlbWFpbCI6Im1tc3N0ZXN0YWRtaW5AbW0uY29tIiwiZ3JvdXAiOlsiL0EmRSAoMTk5NDkzODMyKSJdfQ.e5Kxbss5pK1Miwc9v0615ADjxAIsQWjT99kliRoJwdUTpDhd6fhj1SpZGpDg_-4zOo0BVlJ_TeMvlY9MEtnEp-RWoV4-2CNMWV8b2QEgPGkEkqF_WmNKikPGiIyJju9ulqnGT2EPGdqvwrkOgb9IYzzTIEv-0OVwSeKVG-vs3EZ03_b-p2Hs8TwD2mx8EfV_6ABf1x1tQPT8wEdvjzl91_WiHWxS4JAsvCLFwG8AHksdiHfSP247qn-3yjKDXvCXJWAVhfFor2RjJPRoDmZ-urhLi2QKRDqofBq_RiqO_b4schdMbaUPhgHMN_oSBrOx94yHK9i0jsBFM5FiGwrQsw

SmartSight Metrics and Dimensions API

This endpoint with combinations of path/query/body parameters will help you fetch the data in any combination (metrics and dimensions). Following dashboards use this API endpoint to fetch required data and present it on the platform :

1. KPIs Dashboard

2. Video Experience Dashboard/s

3. Ad Experience Dashboard/s

4. Content Insights

5. Content Analysis

Endpoint :

As of July 2025 /mm-apis/qbrData/vod endoints are deprecated. Please use session instead. We have maintained backward compatibility so you can still use the old API route. However we strongly suggest to move to /mm-apis/session queries as it provides access to a lot of new features.

GET /mm-apis/session/{customerId}

This FastAPI endpoint fetches data for a given customer based on various query parameters.

• Path Parameters:

  • customerId (int, required): The customer ID for which the data is requested.

• Query Parameters:

  • planlevel (int, required): The plan level of the customer.

  • metrics (str, required): The metrics to retrieve (e.g., viewercount, latency).

  • period (str, required): The time range for the query (in 'start=timestamp,end=timestamp' format).

  • token_info (dict, optional): Token information for authentication, validated using validate_token.

  • limit (int, default=1000): Limit the number of results.

  • offset (int, default=0): Offset for paginated results.

  • aggby (str, optional): Aggregation level for the data.

  • agg (str, optional): Aggregation function to use (e.g., sum, avg).

  • orderby (str, optional): Column to order the results by.

  • order (str, default='desc'): The order direction (ascending or descending).

  • filter (str, optional): Filters to apply on the query.

  • qoefilter (str, default= None): Metric filter. This is used to specify metric filters (eg. bufferingratio > 10 , buffcount > 1 ). The metric filter is applied at a session level. So bufferingratio > 10 will filter all the sessions which have bufferingratio > 10%.

  • granularity (str, default='auto'): The granularity of the data (e.g., minute, 5minute, 30minute,hour, day). Use this to enforce granularity for time-series data.

  • sessiontype (str, default='ended'): Type of sessions to query ("ended" or "started") . This is used for accounting the metric at session start or end.

  • realtime (int, default='0'): Whether to query real-time (concurrent) data (1 for enabled, 0 for disabled). This overrides sessiontype.

  • allstatus (int, default='0'): Whether to include all session statuses. By default ENDED and DROPPED are the session statuses that are considered. Some dashboards use this to track RUNNING sessions.

• Functionality:

  • Validates the customer ID with the token.

  • Parses the period parameter to get the start and end times.

  • Adjusts the granularity based on the time difference in the query.

  • Determines the appropriate table view based on the given dimension and filters.

  • Constructs a query based on the provided parameters.

  • Executes the query asynchronously with a 200-second timeout.

  • Processes the query result, converting the data into a list of dictionaries.

  • Returns the total count, page count, total records, and response data.

• Returns:

  • A JSON response containing:

    • totalcount: The total number of records in the response.

    • pagecount: The total number of pages.

    • totalrecords: The total number of records in the query.

    • response: A list of dictionaries, each representing a row of data.

For further information on how to fetch this data programmatically using API endpoints along with path/query/body parameters, refer to Video Experience and Ad Experience guides.

SmartSight Smartquery API

This endpoint with combinations of path/query/body parameters will help you fetch content insights, engagement behavior data. Following dashboards use this API endpoint to fetch required data and present it on the platform :

1. Content Paths

2. Subscriber Insight

Endpoint :

GET /mm-apis/smartQuery/{customerId}

Executes a Smart Query with various filtering, period, and aggregation options.

• Path Parameters:

  • customerId (int, required): The customer ID for which the data is requested.

• Query Parameters:

  • planlevel (int, required): The plan level of the customer.

  • queryname (str, required): The query to execute.

  • period (str, required): The time range for the query (in 'start=timestamp,end=timestamp' format).

  • filter (str, optional): Filters to apply on the query.

  • limit (int, default=1000): Limit the number of results.

  • offset (int, default=0): Offset for paginated results.

  • granularity (str, default='auto'): The granularity of the data (e.g., minute, hour, day).

  • querycache (str, default='True'): Whether to use query caching.

  • queryId (str, optional): uuid, to track the query.

• Returns:

  • A JSON object containing:

    • totalcount: Total number of records in the response.

    • pagecount: Total number of pages.

    • totalrecords: Total number of records found.

    • response: A list of results based on the query.

For further information on how to fetch data programmatically using above API endpoint along with path/query/body parameters, refer to Smartquery Insights guide.