MNTN R2 Reporting Service
R2 is MNTN’s self-service reporting platform. R2 allows MNTN to rapidly build reports for customers. It gives customers a self-service method of customizing those reports and also provides an Application Programming Interface (API) to access data programmatically so that customers and partners can easily move data into their own reporting infrastructure.
In this article, we'll discuss the following:
R2 API 3.0 Overview
The R2 Application Programming Interface (API) is an HTTP service layer that interfaces with the R2 Data Service (R2DS) to retrieve data. It supports both GET and POST requests. Data can be fetched from two endpoints: /list and /data.
The /list endpoint returns a list of available data that can be requested, while the /data endpoint fetches the requested data.
Responses from the API can be returned in multiple formats, including JSON, CSV, Excel, and Human readable. Requests are made using standard HTTP protocols.
R2 currently supports three distinct table types, which results in different levels of data:
1️⃣ Info Tables
2️⃣ Graph Table
3️⃣ Detail Tables
The following is an overview of each table type:
1️⃣ R2 Info Table Type
Info tables are dimensions relevant to your MNTN User Interface setup and Ad Buying strategy. Info tables end with Info in their name. Info tables facilitate your definition of the dimension you wish to group your data by. For example, you can ask for the impressions on a campaign by specifying CampaignInfo.Name to retrieve the campaign name. Then retrieve the Impressions for that Campaign by calling Graph.Impressions.
Info tables include:
AdvertiserInfo
CampaignInfo
ChannelInfo
CityInfo
Creativenfo
AdInfo
DMAInfo
MarketingObjectiveInfo
NetworkInfo
PublisherInfo
StateInfo
2️⃣ R2 Graph Table Type
Graph tables primarily contain numeric data like Visits, impressions, and conversions. They also have a significant number of calculated columns like visit rate, ROAS, eCPA, and others. These tables are grouped by day and can be joined with any Info table.
Summary tables include:
Graph
3️⃣ Detail Table Type
Detail tables provide log level access to data. For example, if you want a list of the conversions that were generated for a campaign you can request data from the Conversions table, which is a detailed table.
Detail tables include:
Conversions
Note: You cannot combine Graph and Detail tables in the same call because the data is inherently different. Graph data is by day, and Detail data is log level, respectively.
R2 API 3.0 List Request
R2 has a /list request, which will return a list of all Tables and Columns you can request data in the API, along with their descriptions. An example list request is:
GET:
POST:
not available via POST
R2 API 3.0 Data Request
The R2 API provides a range of parameters for facilitating data retrieval. Below are basic examples for both GET and POST methods, demonstrating basic use:
GET:
POST:
curl --request POST \
--url https://api3.mountain.com/apidata \
--header 'Content-Type: application/json' \
--data '{
"data": ["impressions","visits","conversions"],
"aid": [22920],
"begin": "2022-10-01",
"end": "2022-11-01",
"sum": ["campaigngroupid"],
"filter": {
"Graph.impressions": {"gt": 2000000}
}
}'
To make a data request, the url in your request should start with https://api3.mountain.com and then append the parameters for the request.
💡Note: Audience Segment data is not supported in our new API endpoint (https://api3.mountain.com/); instead, it is still supported under the original endpoint (https://api.mountain.com/). Please reference our API 1.0 documentation to learn more about retrieving data in this format.
R2 API 3.0 Data Request - Required Parameters
The following parameters are supported, beginning with the mandatory parameters
Key
The key is a unique encrypted key that is assigned to an advertiser. The key is required to issue a valid request to R2 and will only allow access to each advertiser’s specific data.
💡 Note: You can retrieve your key in the Account Settings page of the MNTN user interface.
Begin
This is the Begin time value to get data for. When using a specific date in your begin value, it is required to use an end value as well.
Formatting
✅ Dates must be specified in YYYY-MM-DD format, aka year, then month, then day. For example: 2024-01-31
GET:
POST:
{
"data": [
"graph.day",
"graph.tvcommercialsaired"
],
"key": "<>",
"begin": "2024-01-01",
"end": "2024-01-31",
"format": "human"
}
Predefined Time Ranges
Alternatively, the begin param will accept one of the following predefined time ranges. Please note that all time ranges are configured to exclude the current day's data in the final output unless otherwise specified.
Predefined Time Range Value | Data Pulled |
d | Today's data |
y | The Previous Day's data |
w | The Current Week of data beginning, with Sunday as the first day of the week |
lastweek | The Prior Week of data, with Sunday as the first day of the week |
mtd | The Current Month of data |
lastmonth | The Prior Month of data |
lastthirty | The Last 30 Days of data |
ytd | The Current Year of data |
💡 Note: You don’t need to specify an ‘End’ time argument when you use a predefined time range shortcut.
Here’s an example of the earlier request specifying the current week of data:
GET:
POST:
{
"data": [
"graph.day",
"graph.tvcommercialsaired"
],
"key": "<>",
"begin": "ytd",
"format": "human"
}
End
This is the End time value to get data, which must be used if you also specify a Begin time value. The End parameter is ignored when a begin time shortcut, such as MTD, is used.
End date values include the date specified. For example, specifying an end time of 2024-01-31 will include data for that date.
Formatting
✅ Dates must be specified in YYYY-MM-DD format
This notes the year, then month, then day.
For example: 2024-01-31
Data
The data parameter is a comma separated list of Table.Column arguments that you want to receive data back from the request. You can access a full list of available Tables and Columns by using the list request referenced in R2 API List Request.
There are three forms of tables in our API:
1️⃣ Info Tables: these are the dimensions available and the metadata available at that dimension; these are your group/pivot values in the request
2️⃣ MNTN Graph Tables: these are the data sets available for data retrieval
3️⃣ Detail Tables: data sets that are at the log level
The MNTN Graph tables are grouped by day by a list of dimensions that are also broken out into ‘info’ tables. You will choose your dimensions by including the dimensions’ info tables in your request. You can choose any column within the info table as your dimensional metadata.
For example, if you wanted to receive a list of impressions, visits, and conversions for an advertiser name, the data parameter would be:
GET:
POST:
"data": [
"advertiserinfo.name",
"graph.tvcommercialsaired",
"graph.visits",
"graph.conversions"
]
To receive the same data but in the campaign name, the data parameter would be:
GET:
POST:
"data": [
"advertiserinfo.name",
"campaigninfo.name",
"graph.tvcommercialsaired",
"graph.visits",
"graph.conversions"
]
Format
The Format argument specifies how you want the results of your request returned. Available formats include:
CSV - Comma separated values
Excel - Fully formatted Excel spreadsheet
Human - Human readable in columns and rows
JSON - JSON formatted data
💡Note: The default format returned from R2 is Human readable. JSON is the most commonly requested format for API access.
R2 API Data Request - Optional Parameters
Filter
The filter argument provides a way to constrain results. For example, if you’re querying the campaign table you may not want every campaign. You can follow the below format to include only a single campaign in your results.
GET: must be encoded if used in GET and is limited
POST:
"filter":{
"campaigninfo.id": {
"in": ["28915"]
}
}
Filtering with non-equality conditional matching:
{ "creativegroup.name": { "not": "My Creative Group" } }
{ "creativegroup.name": { "startsWith": "My" } }
Available conditional matchers:
equals
not
in
notIn
startsWith
endsWith
contains
notContains
gt
gte
lt
lte
Filtering on null values:
{ "creativegroup.name": null }
{ "creativegroup.name": { "not": null } }
FormatData
The FormatData argument specifies that data should be returned formatted to the Locale of the advertiser. The formatting is for currency and time. The default behavior is to format but if you can specify FormatData=False to have data returned without formatting.
FullName
The FullName argument returns Table.Column names in the JSON format if FullName=true. If FullName is false or not specified, only the column name is returned in the JSON response.
Limit
The Limit argument specifies a maximum number of rows to return.
💡 Note: The limit for all CSV or excel exports is 65,535 rows of data. Beyond that limit, the report will not export.
Offset
The Offset argument specifies a starting point for the number of rows to return.
Sort
The Sort argument specifies what column you want to sort results on and in what direction. The default is to sort by Day and if no Day column is specified to sort on the first column that is specified in the Data argument in ascending order.
To specify a different column to sort on in descending order, you would specify the following:
Sort=graph.Impressions desc
Ascending is the default sort order. To sort by impressions in ascending order you would specify.
Sort=graph.Impressions
GET
POST
{
"data": [
"graph.day",
"graph.tvcommercialsaired"
],
"key": "<>",
"begin": "ytd",
"format": "human",
"sort": ["graph.day desc"]
}