# Reporting API V1 {% admonition type="danger" name="This API is deprecated and will be removed in July 2026" %} The new API docs can be found here: [https://apidocs.mediamath.com/apis/reporting-api](https://apidocs.mediamath.com/apis/reporting-api) {% /admonition %} {% admonition type="warning" name="Notice about authentication with cookie adama_session" %} The use of cookie adama_session for authentication has been discontinued and it's not supported in Reporting API V2. We ask all of our clients who have not yet migrated to [OAuth2 Authentication](https://apidocs.mediamath.com/guides/authentication) to do so as soon as possible. {% /admonition %} The Reports API on MediaMath Platform allows advertisers to access, query and aggregate reporting data. It is also the API that powers all reporting seen on our MediaMath Platform flagship UI. The Reports API offers a number of reports. Each report offers its own pre-aggregated, time-based metrics on entities that users can query. A query can filter, aggregate, sort, paginate, and format this data. It is a read-only system meaning no request against it can alter the data in any way. It is also a metadata-driven system. The supported reports are described in a human- and machine-readable format. This ensures easy one-off and repeatable programmatic data querying. It also provides a way for clients to adapt to changes in reports programmatically. This gives client-developers the ability to create UIs that provide useful operational feedback in a navigable and understandable way. The $API_BASE for the V1 version of Reports API is `https://api.mediamath.com/reporting/v1/std` ## Authentication {% admonition type="danger" name="This API is deprecated and will be removed in July 2026" %} The new API docs can be found here: [https://apidocs.mediamath.com/apis/reporting-api](https://apidocs.mediamath.com/apis/reporting-api) {% /admonition %} See [OAuth Authentication](https://apidocs.mediamath.com/guides/authentication) ## Fields {% admonition type="danger" name="This API is deprecated and will be removed in July 2026" %} The new API docs can be found here: [https://apidocs.mediamath.com/apis/reporting-api](https://apidocs.mediamath.com/apis/reporting-api) {% /admonition %} Report data is stored and output in a tabular format. This means that the output consists of rows and columns. Every row has a value for every column. The `structure` object can be used to determine the columns a report can output. Its fields are divided among three mappings - `time_field`, `dimensions`, and `metrics`. ```json { "time_rollups" : [ "by_day", "by_week", "by_month", "all" ], "time_windows" : [ "yesterday", "last_X_days", "month_to_date", "campaign_to_date" ], "timezone" : "campaign timezone", "time_aggregation" : "by_day", "structure" : { "time_field" : { "date" : { "name" : "Date", "type" : "datetime" } }, "dimensions" : { "campaign_id" : { ... }, "campaign_name" : { ... }, "strategy_id" : { ... }, "strategy_name" : { ... } }, "metrics" : { "clicks" : { ... }, "impressions" : { ... } } } ... } ``` --- **Time Field** The time field represents the time-component of the report's metrics. There is (currently) only one time field for each report. It can be of one of these data types: `datetime` or `interval`. Its data type determines the type of report (**datetime** or **interval** based report). **Note:** The type of report is not to be confused with the `Type` attribute. The `Type` attribute is purely informational. The time field was distinguished from the dimension fields to allow its use in grouping and filtering rows easier to understand. It gets its own set of parameters and language. --- **datetime-typed Time Fields** Datetime-typed time fields contains a combination of year, month, day, and possibly down to hour, minute and second. The `time_aggregation` property indicates the field's finest grain (by_hour, by_day, etc). The `time_rollups` property indicates the available grouping options that can go beyond the `time_aggregation` of the report. ``` time_rollup=by_week ### group rows by the week - week starts on Monday time_rollup=by_month ### group rows by the month time_rollup=all ### produces at most one row of output per combination of dimension fields ### listed in the dimensions parameter ``` The time field for these reports are typically represented in the output by a start_date and end_date column. The format of the column will depend on the time window and `time_rollup`. * YYYY-MM-DD * YYYY-MM-DD hh:mi:ss The only exception to this rule is detailed in the Special Time Windows section. The timezone of the start_date and end_date columns will match the `timezone` property. --- **interval-typed Time Fields** `interval`-typed time fields, contain a predefined non-calendar date based aggregation (1 day, 7 days, 30 days, and so on). In this case, the only accepted way to specify a time interval is by using the parameter `time_window`. The only value supported for the parameter `time_rollup` for interval-based reports is `all`. The time field for these reports are represented in the output by a interval column. The value of the column will depend on the `time_window` chosen. The following gives example column values based on the time_window. * yesterday - 1 * last_7_days - 7 * last_30_days - 30 * campaign_to_date - CTD * flight_to_date - FTD --- **Filtering with the Time Field** The API requires the specification of a time window in order to narrow the data set operated on. A time window must be specified in one of the two possible ways. * `start_date` and `end_date` (optional - defaults to "yesterday"). * `time_window` may be set to one of the formats defined by the `time_windows` attribute. ``` ### operate on data timestamped between Jan 01, 2013 and Feb 01, 2013, inclusive start_date=2013-01-01&end_date=2013-02-01 ### operate on data timestamped between May 05, 2013 and yesterday, inclusive start_date=2013-05-01 ### other usage examples time_window=last_30_days time_window=month_to_date time_window=yesterday ``` --- **start_date and end_date** `start_date` and `end_date` may only be used when the report's time field is of the `datetime` type. They may not be used when the report's time field is of the `interval` data type. This is because the `time_windows` are pre-defined intervals that cannot be split. The `start_date` and `end_date` parameters define inclusive boundaries for the data. In order to ease the burden of calculating an inclusive end, the inputs may be specified at various granularities. * month - YYYY-MM * day - YYYY-MM-DD * hour - YYYY-MM-DDThh * minute - YYYY-MM-DDThh:mi * second - YYYY-MM-DDThh:mi:ss Each granularity matches a substring of the ISO 8601 format. If the report is at a coarser granularity (see `time_aggregation`) than the input, the input will be taken to mean the entirety of the time unit. ``` start_date=2016-04-12T01%3A30%3A00&end_date=2016-04-12T02%3A30%3A00 # ie. start_date=2016-04-12T01:30:00&end_date=2016-04-12T02:30:00 # For a report with a time_aggregation of by_hour: # 2016-04-12T01:00:00 to 2016-04-12T02:59:59. # For a report with a time_aggregation of by_day: # 2016-04-12T00:00:00 to 2016-04-12T23:59:59 ``` --- **time_window** All values mentioned in the `time_windows` array will be accepted verbatim by the time_window parameter with the exception of any time window that starts with `last_X_`. They may be interpreted as such. * The `last_X_days` time window ends yesterday (inclusive) and starts X days before that. * The `last_X_hours` time window ends at the previous hour (inclusive) and starts X hours before that. Future windows of this type may be defined following this nomenclature, but for different units. Rules for the time window may vary slightly. --- **Special Time Windows** The following `time_windows` are considered to be special time windows. * `campaign_to_date` * `flight_to_date` For reports with a `datetime`-typed `time_field`, the start_date and end_date columns that would normally be present, will be replaced by the interval column. Additionally, the following validation rules apply when a special `time_window` is chosen. * The results will have an `interval` column instead of `start_date` and `end_date` columns. * The `time_rollup` parameter must be set to `all`. * Any mention of the `time_field` for the report in the `order` parameter will be rejected. --- **Dimension Fields** Dimension fields describe an entity. The example reports provide dimension fields for campaign, and strategy entities. Dimension fields are used to group rows during aggregation in conjunction with the time field. --- **Metric Fields** Once the rows have been grouped. The metric fields are calculated based on the values of the group's underlying rows. These calculations are generally sums or averages. These fields are usually a numeric data type. Please note that fees (eg: managed_service_fee, optimization_fee, platform_access_fee, and mm_total_fee), cost (eg: adserving_cost, adverification_cost, media_cost, and tota_ad_cost), and margin data are only available to users who have “edit margin” access. # Data Types {% admonition type="danger" name="This API is deprecated and will be removed in July 2026" %} The new API docs can be found here: [https://apidocs.mediamath.com/apis/reporting-api](https://apidocs.mediamath.com/apis/reporting-api) {% /admonition %} The `id` type allows any character except whitespace. The `datetime` type may be filtered by dates, or datetimes in either of the following ISO 8601 based formats. * date - YYYY-MM-DD * datetime - YYYY-MM-DDThh:mi:ss Year, month, and day are all 1-based. Hour, minute, and second are all 0-based. Valid hours are 0-23. The dimension fields of the `datetime` type will always be output in the aforementioned datetime format. The output columns for the time field will be output in the same format, but without the separating 'T'. --- **Field Data Type Groupings** This documentation may refer to multiple data types via a group name. The following table details the group names. |Group|Data Types| |--- |--- | |float|float, money, percent, ratio| |integer|integer, count, rank| |numeric|float and integer groups| |date|datetime| |string|string, interval| |id|id| |bool|bool, boolean| License: Apache 2.0 ## Servers ``` https://api.mediamath.com/reporting/v1/std ``` ## Security ### API_Key_-_1 Type: oauth2 Token URL: https://auth.mediamath.com/oauth/token Scopes: ## Download OpenAPI description - [Reporting API V1](https://apidocs.mediamath.com/_bundle/apis/reporting-api-v1.yaml) ## Data Retrieval - [GET /{report}](https://apidocs.mediamath.com/apis/reporting-api-v1/data-retrieval/get_report.md): The new API docs can be found here: [https://apidocs.mediamath.com/apis/reporting-api](https://apidocs.mediamath.com/apis/reporting-api) # Parameters Parameter names are case sensitive, (see the table - [GET /{report}/validate](https://apidocs.mediamath.com/apis/reporting-api-v1/data-retrieval/get_report-validate.md): The new API docs can be found here: [https://apidocs.mediamath.com/apis/reporting-api](https://apidocs.mediamath.com/apis/reporting-api) ### Validating Data Retrieval Requests Data retrieval requests ## Metadata - [GET /meta](https://apidocs.mediamath.com/apis/reporting-api-v1/metadata/get_meta.md): The new API docs can be found here: [https://apidocs.mediamath.com/apis/reporting-api](https://apidocs.mediamath.com/apis/reporting-api) In order to obtain a list of reports which are currently suppor - [GET /{report}/meta](https://apidocs.mediamath.com/apis/reporting-api-v1/metadata/get_report-meta.md): The new API docs can be found here: [https://apidocs.mediamath.com/apis/reporting-api](https://apidocs.mediamath.com/apis/reporting-api) The examples used in this section are truncated versions of [ht ## Reports - [GET /app_transparency](https://apidocs.mediamath.com/apis/reporting-api-v1/reports/get_app_transparency.md): The new API docs can be found here: [https://apidocs.mediamath.com/apis/reporting-api](https://apidocs.mediamath.com/apis/reporting-api) See or query the Meta Endpoint for required fields and paramete - [GET /app_transparency/meta](https://apidocs.mediamath.com/apis/reporting-api-v1/reports/get_app_transparency-meta.md): The new API docs can be found here: [https://apidocs.mediamath.com/apis/reporting-api](https://apidocs.mediamath.com/apis/reporting-api) Get App Transparency Meta - [GET /brain_feature_summary/meta](https://apidocs.mediamath.com/apis/reporting-api-v1/reports/generate-brain-feature-summary-report.md): The new API docs can be found here: [https://apidocs.mediamath.com/apis/reporting-api](https://apidocs.mediamath.com/apis/reporting-api) ## The Brain Feature Summary report Sample usage: GET https://a - [GET /brain_feature_value/meta](https://apidocs.mediamath.com/apis/reporting-api-v1/reports/generate-brain-feature-value-report.md): The new API docs can be found here: [https://apidocs.mediamath.com/apis/reporting-api](https://apidocs.mediamath.com/apis/reporting-api) ## Brain Feature Value Report Sample usage: GET https://api.med - [GET /by_hour](https://apidocs.mediamath.com/apis/reporting-api-v1/reports/get_by_hour.md): The new API docs can be found here: [https://apidocs.mediamath.com/apis/reporting-api](https://apidocs.mediamath.com/apis/reporting-api) Standard performance metrics broken out by standard dimensions, - [GET /by_hour/meta](https://apidocs.mediamath.com/apis/reporting-api-v1/reports/get_by_hour-meta.md): The new API docs can be found here: [https://apidocs.mediamath.com/apis/reporting-api](https://apidocs.mediamath.com/apis/reporting-api) Get By Hour Meta - [GET /day_part](https://apidocs.mediamath.com/apis/reporting-api-v1/reports/get_day_part.md): The new API docs can be found here: [https://apidocs.mediamath.com/apis/reporting-api](https://apidocs.mediamath.com/apis/reporting-api) Standard performance metrics broken out by time of day and day - [GET /day_part/meta](https://apidocs.mediamath.com/apis/reporting-api-v1/reports/get_day_part-meta.md): The new API docs can be found here: [https://apidocs.mediamath.com/apis/reporting-api](https://apidocs.mediamath.com/apis/reporting-api) Get Day Part Meta - [GET /deals](https://apidocs.mediamath.com/apis/reporting-api-v1/reports/get_deals.md): The new API docs can be found here: [https://apidocs.mediamath.com/apis/reporting-api](https://apidocs.mediamath.com/apis/reporting-api) See or query the Meta Endpoint for required fields and paramete - [GET /deals/meta](https://apidocs.mediamath.com/apis/reporting-api-v1/reports/get_deals-meta.md): The new API docs can be found here: [https://apidocs.mediamath.com/apis/reporting-api](https://apidocs.mediamath.com/apis/reporting-api) Get Deals Meta - [GET /device_technology](https://apidocs.mediamath.com/apis/reporting-api-v1/reports/get_device_technology.md): The new API docs can be found here: [https://apidocs.mediamath.com/apis/reporting-api](https://apidocs.mediamath.com/apis/reporting-api) Standard performance metrics broken out by technology dimension - [GET /device_technology/meta](https://apidocs.mediamath.com/apis/reporting-api-v1/reports/get_device_technology-meta.md): The new API docs can be found here: [https://apidocs.mediamath.com/apis/reporting-api](https://apidocs.mediamath.com/apis/reporting-api) ## Versions The API allows you to determine the version of the - [GET /geo](https://apidocs.mediamath.com/apis/reporting-api-v1/reports/get_geo.md): The new API docs can be found here: [https://apidocs.mediamath.com/apis/reporting-api](https://apidocs.mediamath.com/apis/reporting-api) - [GET /geo/meta](https://apidocs.mediamath.com/apis/reporting-api-v1/reports/get_geo-meta.md): The new API docs can be found here: [https://apidocs.mediamath.com/apis/reporting-api](https://apidocs.mediamath.com/apis/reporting-api) Standard performance metrics broken out by geographic dimension - [GET /performance](https://apidocs.mediamath.com/apis/reporting-api-v1/reports/get_performance.md): The new API docs can be found here: [https://apidocs.mediamath.com/apis/reporting-api](https://apidocs.mediamath.com/apis/reporting-api) Standard performance metrics in campaign currency and broken ou - [GET /performance/meta](https://apidocs.mediamath.com/apis/reporting-api-v1/reports/get_performance-meta.md): The new API docs can be found here: [https://apidocs.mediamath.com/apis/reporting-api](https://apidocs.mediamath.com/apis/reporting-api) Get Performance Meta - [GET /reach_frequency](https://apidocs.mediamath.com/apis/reporting-api-v1/reports/get_reach_frequency.md): The new API docs can be found here: [https://apidocs.mediamath.com/apis/reporting-api](https://apidocs.mediamath.com/apis/reporting-api) The Reach and Frequency report measures the number of unique us - [GET /reach_frequency/meta](https://apidocs.mediamath.com/apis/reporting-api-v1/reports/get_reach_frequency-meta.md): The new API docs can be found here: [https://apidocs.mediamath.com/apis/reporting-api](https://apidocs.mediamath.com/apis/reporting-api) Get Reach Frequency Meta - [GET /site_transparency](https://apidocs.mediamath.com/apis/reporting-api-v1/reports/get_site_transparency.md): The new API docs can be found here: [https://apidocs.mediamath.com/apis/reporting-api](https://apidocs.mediamath.com/apis/reporting-api) Get Site Transparency - [GET /site_transparency/meta](https://apidocs.mediamath.com/apis/reporting-api-v1/reports/get_site_transparency-meta.md): The new API docs can be found here: [https://apidocs.mediamath.com/apis/reporting-api](https://apidocs.mediamath.com/apis/reporting-api) Standard performance metrics broken out by the domain of the in - [GET /watermark](https://apidocs.mediamath.com/apis/reporting-api-v1/reports/get_watermark.md): The new API docs can be found here: [https://apidocs.mediamath.com/apis/reporting-api](https://apidocs.mediamath.com/apis/reporting-api) Watermark metrics show how many impressions and how much spend - [GET /watermark/meta](https://apidocs.mediamath.com/apis/reporting-api-v1/reports/get_watermark-meta.md): The new API docs can be found here: [https://apidocs.mediamath.com/apis/reporting-api](https://apidocs.mediamath.com/apis/reporting-api) Get Watermark Meta - [GET /win_loss](https://apidocs.mediamath.com/apis/reporting-api-v1/reports/get_win_loss.md): The new API docs can be found here: [https://apidocs.mediamath.com/apis/reporting-api](https://apidocs.mediamath.com/apis/reporting-api) Metrics describe the auction before a win or even a bid has tak - [GET /win_loss/meta](https://apidocs.mediamath.com/apis/reporting-api-v1/reports/get_win_loss-meta.md): The new API docs can be found here: [https://apidocs.mediamath.com/apis/reporting-api](https://apidocs.mediamath.com/apis/reporting-api) Metrics describe the auction before a win or even a bid has tak - [GET /win_loss_creative](https://apidocs.mediamath.com/apis/reporting-api-v1/reports/get_win_loss_creative.md): The new API docs can be found here: [https://apidocs.mediamath.com/apis/reporting-api](https://apidocs.mediamath.com/apis/reporting-api) Metrics describe the auction before a win has taken place. Brok - [GET /win_loss_creative/meta](https://apidocs.mediamath.com/apis/reporting-api-v1/reports/get_win_loss_creative-meta.md): The new API docs can be found here: [https://apidocs.mediamath.com/apis/reporting-api](https://apidocs.mediamath.com/apis/reporting-api) Metrics describe the auction before a win has taken place. Brok