# MediaMath API

> MediaMath comprehensive APIs empower users to programmatically access and modify campaigns, reports, and log data in MediaMath Platform.

## Table of contents

 - [API Rate Limiting & Throttling](https://apidocs.mediamath.com/guides/api-rate-limiting.md)
 - [API Usage Terms](https://apidocs.mediamath.com/legal/terms.md)
 - [Tool Reference](https://apidocs.mediamath.com/guides/mcp/tool-reference.md)
 - [Security Best Practices](https://apidocs.mediamath.com/guides/security-best-practices.md)
 - [Bid Enrichment](https://apidocs.mediamath.com/guides/bid-enrichment.md)
 - [Syncing](https://apidocs.mediamath.com/guides/syncing.md)
 - [Mobile Pixel SDK](https://apidocs.mediamath.com/guides/mobile-pixel-sdk.md)
 - [Audience Event Onboarding](https://apidocs.mediamath.com/guides/audience-onboarding.md)
 - [Taxonomy Management](https://apidocs.mediamath.com/guides/taxonomy-management.md)
 - [Best Practices](https://apidocs.mediamath.com/guides/mcp/best-practices.md)
 - [Getting Connected](https://apidocs.mediamath.com/guides/mcp/getting-connected.md)
 - [Infillion Agent Connector™ (MCP Integration)](https://apidocs.mediamath.com/guides/mcp/overview.md)
 - [Authentication](https://apidocs.mediamath.com/guides/authentication.md)
 - [Audience Segment Onboarding](https://apidocs.mediamath.com/guides/data-onboarding.md)
 - [APIs](https://apidocs.mediamath.com/guides.md)
 - [Marketplaces](https://apidocs.mediamath.com/guides/marketplaces.md)
 - [Postman Collections](https://apidocs.mediamath.com/guides/postman-collections.md)
 - [FAQ](https://apidocs.mediamath.com/apis/log-level-data-service/faq.md)
 - [Cloud File Transfer](https://apidocs.mediamath.com/guides/cloud-file-transfer.md)
 - [Introduction](https://apidocs.mediamath.com/guides/server-to-server.md)
 - [Log Level Data Service](https://apidocs.mediamath.com/apis/log-level-data-service.md)
 - [Data Platform Architecture](https://apidocs.mediamath.com/apis/log-level-data-service/overview.md)
 - [Reporting API V2](https://apidocs.mediamath.com/apis/reporting-api.md)
 - [Custom Bid Router Overview](https://apidocs.mediamath.com/guides/byoa/custom-bid-router/about.md)
 - [Getting Started with Custom Bid Router](https://apidocs.mediamath.com/guides/byoa/custom-bid-router/getting-started.md)
 - [Custom Bid Router Request and Response examples](https://apidocs.mediamath.com/guides/byoa/custom-bid-router/request-and-response-examples.md)
 - [Setting up S3 delivery of Custom Bid Router bid request/response logs](https://apidocs.mediamath.com/guides/byoa/custom-bid-router/setting-up-s3-logs.md)
 - [Win Notification](https://apidocs.mediamath.com/guides/byoa/custom-bid-router/win-notification.md)
 - [Custom Brain](https://apidocs.mediamath.com/guides/byoa/custom-brain/about.md)
 - [BYOA Model Features](https://apidocs.mediamath.com/guides/byoa/custom-brain/available-features.md)
 - [Getting started with BYOA API for Custom Brain](https://apidocs.mediamath.com/guides/byoa/custom-brain/getting-started.md)
 - [A/B Split Testing with Custom Brain](https://apidocs.mediamath.com/guides/byoa/custom-brain/guide-to-ab-split-tests.md)
 - [Preparing a BYOA Model with Flatbuffer](https://apidocs.mediamath.com/guides/byoa/custom-brain/preparing-a-model.md)
 - [WURFL Parsing](https://apidocs.mediamath.com/guides/byoa/custom-brain/wurfl-parsing.md)
 - [Audience Segments API](https://apidocs.mediamath.com/apis/audience-taxonomies.md): {% admonition type="danger" name="This API is deprecated as of 1st August 2026" %} The functionality has been built into the V3 Campaign Management API docs which can be found here: [https://apidocs.mediamath.com/apis/campaigns-api/openapi](https://apidocs.mediamath.com/apis/campaigns-api/openapi) {% /admonition %}
 - [BOF Config API](https://apidocs.mediamath.com/apis/bof-api-v1.md): 1. [What is BOF?](#what-is-bof) 2. [How is BOF data accessed?](#how-is-bof-data-accessed) 3. [How do I get started with BOF?](#how-do-i-get-started-with-bof) 4. [How do I get self-service access to my BOF config file?](#how-do-i-get-self-service-access-to-my-bof-config-file) 5. [List of Filters](#list-of-filters) 6. [Example Filter Implementation](#example-filter-implementation) 7. [List of Channels (X-Mm-Channel-Type)](#list-of-channels-x-mm-channel-type) 8. [List of Geos (X-Mm-Geo)](#list-of-geos-x-mm-geo) 9. [Tell me more about Role ARN and buckets](#tell-me-more-about-role-arn-and-buckets) 10. [Partition Macros for S3/Google cloud users](#partition-macros-for-s3google-cloud-users) 11. [JSON Object Capabilities](#json-object-capabilities) ### What is BOF? The Bid Request Firehose (BOF), is a high performance system designed to ingest bid opportunities from MediaMath bidders and filter and batch these requests to third parties based on configurable parameters. ### How is BOF data accessed? In order to grant access to the BOF, a config file, called a consumer, must be set-up for the internal/external client. There are 2 types of consumers that are available: 1. Web endpoint - This can significantly reduce client data response time but requires the client to operate a web cluster capable of ingesting the traffic. 2. S3 endpoint - This is for clients who are less worried about the delivery time of the data, and prefer to receive the data in larger batch sizes (30,000). This is typically the lowest cost consumer for clients. Compression Types: LZOP, GZIP Format Types: Json Array, JSONL ### How do I get started with BOF? Setting up a web or s3 consumer takes minimal effort from the MM side. To get set up, please contact your Account representative and provide the following information: * If S3 consumer: Role ARN (see [below](#tell-me-more-about-role-arn-and-buckets) for more details) * If S3 consumer: S3 bucket name(s). You will need to create and provide access to a bucket with a role for BOF to deliver files to it. See [below](#partition-macros-for-s3google-cloud-users) for more details. * Note: BOF V2 offers cross-region data replication meaning you do not have to worry about creating multiple buckets e.g all your regional data can be sent to us-east-1 * Email Contact * Which regions you are interested in capturing traffic from i.e US, EMEA, or APAC * Sample rate (0-100%): If you plan on receiving data from all of the US you should start with a 1% sample. For reference, as of early March 2020, the United States sees approximately 4 million requests a second during the day, so with a 1% filter and a deployment in ewr/ord/pao (United States) you will see ~40k requests per second. This is plenty of data for a sample. * At least one of the following filters (see [below](#list-of-filters) for more details): * X-Mm-Geo * X-Mm-Deal-Id * X-Mm-Exch-Id * X-Mm-Channel-Type ### How do I get self-service access to my BOF config file? As part of the release of BOF v2.0, clients will now have self-service access to their BOF config files. Specifically, they will be able to dynamically update their sample rate, and/or filters without having to engage the MM team. In order to gain self-service access all consumers will need an auth0 account with MediaMath. Please contact developers@mediamath.com to recieve your auth0 client id and secret and then proceed with the following steps: Curl auth.mediamath.com with your client ID and secret `POST https://auth.mediamath.com/oauth/token` Example Request: ``` curl -X POST --header 'content-type: application/json' 'https://auth.mediamath.com/oauth/token' -d '{"audience": "https://api.mediamath.com/opportunity_firehose/", "grant_type":"client_credentials", "client_id":"{CLIENT_ID}", "client_secret":"{CLIENT_SECRET}"}' ``` Example Response: ``` {"access_token":"ACCESS_TOKEN_HERE","expires_in":86400,"token_type":"Bearer"} ``` Use this token here when sending requests to https://api.mediamath.com/opportunity-firehose/v2.0/ `curl -X GET -H "Authorization:Bearer ACCESS_TOKEN_HERE" 'https://api.mediamath.com/opportunity-firehose/v2.0/'` # Additional Information In addition to the API's shown in the left column of your display, the following information will help you with updates to your BOF configurations. ### **List of Filters** ``` [ "X-Mm-Exch-Id", "X-Mm-Deal-Id", "X-Mm-Channel-Type", "X-Mm-Geo" ] ``` ### **Example Filter Implementation** ``` "filters": { "X-Mm-Channel-Type": ["DISPLAY","VIDEO","SOCIAL","MOBILE_DISPLAY_MOBILE_WEB","MOBILE_VIDEO_MOBILE_WEB","SEARCH","EMAIL","NEWSFEED"], "X-Mm-Exch-Id": ["3","4","5","9","13","15","30"], "X-Mm-Geo": ["60231"] } ``` > The filters are additive (they are AND'ed together), so the more filters, the smaller the data set. The above filters will result in seeing request of only those channel types AND only those exchange ids AND only that geo. ### **List of Channels (X-Mm-Channel-Type)** ``` { "DISPLAY", "VIDEO", "SOCIAL", "MOBILE_DISPLAY_MOBILE_WEB", "MOBILE_VIDEO_MOBILE_WEB", "SEARCH", "EMAIL", "MOBILE_DISPLAY_IN_APP", "MOBILE_VIDEO_IN_APP", "NEWSFEED" } ``` ### **List of Geos (X-Mm-Geo)** ``` { "60000": "Unknown", "60001": "Other", "60002": "Aruba", "60003": "Afghanistan", "60004": "Angola", "60005": "Anguilla", "60006": "Aland Islands", "60007": "Albania", "60008": "Andorra", "60009": "Netherlands Antilles", "60010": "United Arab Emirates", "60011": "Argentina", "60012": "Armenia", "60013": "American Samoa", "60014": "Antarctica", "60015": "French Southern Territories", "60016": "Antigua And Barbuda", "60017": "Australia", "60019": "Azerbaijan", "60020": "Burundi", "60022": "Benin", "60023": "Burkina Faso", "60024": "Bangladesh", "60026": "Bahrain", "60027": "Bahamas", "60028": "Bosnia And Herzegowina", "60029": "Belarus", "60030": "Belize", "60031": "Bermuda", "60032": "Bolivia", "60033": "Brazil", "60034": "Barbados", "60035": "Brunei Darussalam", "60036": "Bhutan", "60037": "Bouvet Island", "60038": "Botswana", "60039": "Central African Republic", "60040": "Canada", "60041": "Cocos (Keeling) Islands", "60042": "Switzerland", "60043": "Chile", "60044": "China", "60045": "Cote D Ivoire", "60046": "Cameroon", "60047": "Congo - The Democratic Rep Of", "60048": "Congo", "60049": "Cook Islands", "60050": "Colombia", "60051": "Comoros", "60052": "Cape Verde", "60053": "Costa Rica", "60054": "Cuba", "60055": "Christmas Island", "60056": "Cayman Islands", "60060": "Djibouti", "60061": "Dominica", "60063": "Dominican Republic", "60064": "Algeria", "60065": "Ecuador", "60066": "Egypt", "60067": "Eritrea", "60068": "Western Sahara", "60071": "Ethiopia", "60073": "Fiji", "60074": "Falkland Islands (Malvinas)", "60076": "Faroe Islands", "60077": "Micronesia - Federated States Of", "60078": "Gabon", "60080": "Georgia", "60081": "Guernsey", "60082": "Ghana", "60083": "Gibraltar", "60084": "Guinea", "60085": "Guadeloupe", "60086": "Gambia", "60087": "Guinea-Bissau", "60088": "Equatorial Guinea", "60090": "Grenada", "60091": "Greenland", "60092": "Guatemala", "60093": "French Guiana", "60094": "Guam", "60095": "Guyana", "60096": "Hong Kong", "60097": "Heard And Mc Donald Islands", "60098": "Honduras", "60100": "Haiti", "60102": "Indonesia", "60103": "Isle Of Man", "60104": "India", "60105": "British Indian Ocean Territory", "60107": "Iran (Islamic Republic Of)", "60108": "Iraq", "60110": "Israel", "60112": "Jamaica", "60113": "Jersey", "60114": "Jordan", "60115": "Japan", "60116": "Kazakhstan", "60117": "Kenya", "60118": "Kyrgyzstan", "60119": "Cambodia", "60120": "Kiribati", "60121": "Saint Kitts And Nevis", "60122": "Korea - South", "60123": "Kuwait", "60124": "Lao Peoples Democratic Republic", "60125": "Lebanon", "60126": "Liberia", "60127": "Libyan Arab Jamahiriya", "60128": "Saint Lucia", "60130": "Sri Lanka", "60131": "Lesotho", "60135": "Macau", "60136": "Morocco", "60137": "Monaco", "60138": "Moldova - Republic Of", "60139": "Madagascar", "60140": "Maldives", "60141": "Mexico", "60142": "Marshall Islands", "60143": "Macedonia - The Frm Yugoslav Rep Of", "60144": "Mali", "60146": "Myanmar", "60147": "Montenegro", "60148": "Mongolia", "60149": "Northern Mariana Islands", "60150": "Mozambique", "60151": "Mauritania", "60152": "Montserrat", "60153": "Martinique", "60154": "Mauritius", "60155": "Malawi", "60156": "Malaysia", "60157": "Mayotte", "60158": "Namibia", "60159": "New Caledonia", "60160": "Niger", "60161": "Norfolk Island", "60162": "Nigeria", "60163": "Nicaragua", "60164": "Niue", "60167": "Nepal", "60168": "Nauru", "60169": "New Zealand", "60170": "Oman", "60171": "Pakistan", "60172": "Panama", "60173": "Pitcairn", "60174": "Peru", "60175": "Philippines", "60176": "Palau", "60177": "Papua New Guinea", "60179": "Puerto Rico", "60180": "Korea - North", "60182": "Paraguay", "60183": "Palestinian Territories", "60184": "French Polynesia", "60185": "Qatar", "60186": "Reunion", "60188": "Russian Federation", "60189": "Rwanda", "60190": "Saudi Arabia", "60191": "Sudan", "60192": "Senegal", "60193": "Singapore", "60194": "South Georgia / South Sandwich Isl", "60195": "St. Helena", "60196": "Svalbard And Jan Mayen Islands", "60197": "Solomon Islands", "60198": "Sierra Leone", "60199": "El Salvador", "60200": "San Marino", "60201": "Somalia", "60202": "St. Pierre And Miquelon", "60203": "Serbia", "60204": "Sao Tome And Principe", "60205": "Suriname", "60209": "Swaziland", "60210": "Seychelles", "60211": "Syrian Arab Republic", "60212": "Turks And Caicos Islands", "60213": "Chad", "60214": "Togo", "60215": "Thailand", "60216": "Tajikistan", "60217": "Tokelau", "60218": "Turkmenistan", "60219": "Timor-Leste", "60220": "Tonga", "60221": "Trinidad And Tobago", "60222": "Tunisia", "60223": "Turkey", "60224": "Tuvalu", "60225": "Taiwan", "60226": "Tanzania - United Republic Of", "60227": "Uganda", "60228": "Ukraine", "60229": "Us Minor Outlying Islands", "60230": "Uruguay", "60231": "United States", "60232": "Uzbekistan", "60233": "Holy See (Vatican City State)", "60234": "Saint Vincent And The Grenadines", "60235": "Venezuela", "60236": "British Virgin Islands", "60237": "Us Virgin Islands", "60238": "Viet Nam", "60239": "Vanuatu", "60240": "Wallis And Futuna Islands", "60241": "Samoa", "60242": "Yemen", "60243": "South Africa", "60244": "Zambia", "60245": "Zimbabwe", "60246": "Asia Pacific", "60247": "Europe", "72279": "Bonaire/Sint Eustatius/Saba", "72280": "South Sudan" } ``` ### Tell me more about Role ARN and buckets Create an AWS role with at trust relationship of the following ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam::888665229551:root", "arn:aws:iam::654223338280:root" ] }, "Action": "sts:AssumeRole", "Condition": {} } ] } ``` And then give that role Put access to the bucket and/or bucket path ``` { "Version": "2012-10-17", "Statement": [ { "Action": [ "s3:Put*" ], "Effect": "Allow", "Resource": "arn:aws:s3:::YOUR-BUCKET-NAME/*" } ] } ``` Once you have done that, provide us with the role:arn, bucket name, and region you put the bucket in and we can start delivering you files. If you want to deliver files into a bucket with a prefix such as s3://mediamath/fileshere tell us the prefix and we can deliver the files there. The delivery partitions are as follows. `prefix/HexValue (0-F)/Year-Month-Day/Hour/appUUID_Year-Month-Day-Hour-Minute_opportunities_UTCMS.json.lzo` The numbered prefixes are there for high volume consumers based on the [best practices for s3 delivery on aws.](https://docs.aws.amazon.com/AmazonS3/latest/dev/optimizing-performance.html) I've created some terraform code to reflect this relationship. ``` resource "aws_s3_bucket" "bof_ingest" { bucket = "bof-ingest" region = "us-east-1" acl = "private" } resource "aws_iam_role" "bof_ingest_service_role" { name = "bof_ingest_service_role" assume_role_policy = <<EOF { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam::888665229551:root", "arn:aws:iam::654223338280:root" ] }, "Action": "sts:AssumeRole", "Condition": { } } ] } EOF } resource "aws_iam_policy" "bof_ingest_service_role_policy" { name = "bof_ingest_service_role_policy" path = "/" policy = <<EOF { "Version": "2012-10-17", "Statement": [{ "Action": [ "s3:Put*" ], "Effect": "Allow", "Resource": "${aws_s3_bucket.bof_ingest.arn}/*" }] } EOF } resource "aws_iam_role_policy_attachment" "bof_ingest_service_role_policy_attachment" { role = "${aws_iam_role.bof_ingest_service_role.name}" policy_arn = "${aws_iam_policy.bof_ingest_service_role_policy.arn}" } ``` ### Partition Macros for S3/Google cloud users Partition Macros can be set inside of AwsSettings/GoogleSettings. You can change it by posting a macro to the following: POST /consumers/{name}/awssettings or POST /consumers/{name}/googlesettings Example post data: `{"PartitionMacro": "%hex%/%yyyy%-%mm%-%dd%/%hh%/%appuuid%_%yyyy%-%mm%-%dd%-%hh%-%mm%opportunities%unixms%.jsonl.lzo"}` %yyyy% = year %mm% = month %dd% = day %hh% = hour %mi% = minute %ss% = seconds %hex% = hex value 0-F %unix% = unix time stamp %unixms% = unix millisecond stamp %nano% = unix nanosecond stamp %appuuid% = our internal app UUID which is just a generated UUID You can change the entire delivery of your path with these macros. The default delivery partition macro is `"%hex%/%yyyy%-%mm%-%dd%/%hh%/%appuuid%_%yyyy%-%mm%-%dd%-%hh%-%mm%opportunities%unixms%.jsonl.lzo"` If you were to create a partition macro with the following value `"%yyyy%%mm%%dd%/%hh%/%appuuid%_%nano%.jsonl.lzop` It would expand to `20200402/14/b63aeb5b-9afa-4a42-9d33-b024fd96743f_1585853925137647046.jsonl.lzop` We highly suggest keeping %appuuid%_%nano% in the file name. The files are generated from each server and there is no de-duplication, so if you inadvertently overwrite your own files by choosing a path that is not unique enough there's nothing we can do. This will mean you are being delivered files, charged for that delivery but losing that data. Also remember that these need to be valid s3 path names. If you create an invalid s3 path with a macro your file delivery will be interrupted until it is resolved. ### JSON Object Capabilities ```` type struct ConsumerSettings { DropZeroUID bool DropExchangeUID bool DropBody bool Filters map[string][]string SampleSettings *sampleSettings AwsSettings *awsSettings WebSettings *webSettings GoogleSettings *googleSettings } ```` ```` type sampleSettings struct { Disabled bool SampleRate int } ```` ```` type awsSettings struct { Regions map[string]string Buckets map[string]string ASE256ServerSideEncryption bool PartitionMacro string } ```` ```` type webSettings struct { Endpoints map[string]string } ```` ```` type googleSettings struct { Buckets map[string]string PartitionMacro string } ````
 - [BYOA](https://apidocs.mediamath.com/apis/byoa-api.md): # Custom Brain Custom Brain allows the client to use the BYOA API to upload a set of logistic coefficients corresponding to any of the variables currently in use by the MediaMath Brain. These coefficients will then be used by participating strategies to calculate the predicted response rate for each impression. The bidder will calculate bid price by multipling the predicted response rate by the strategy's goal value. Goal values can be modified using the MediaMath Platform campaign management API. It is best for you to contact us early in your process by emailing developers@mediamath.com, as it may take about 48 hours before you are granted API access to begin work on your model. ![BYOM](https://mediamath.github.io/api-docs/images/BYOA-CustomBrain.png "BYOM Architecture")
 - [Component Creatives API](https://apidocs.mediamath.com/apis/component-creatives.md): The terms creative components and native components may be used interchangeably. Component Creatives are uploaded in the "Creatives Tab" within the Creatives Module, and is where creatives for native campaigns are uploaded. ## Component Creatives API v3.0 (current) QA API Base: `https://t1qa1.mediamath.com/component_creatives/v3.0/` (or whichever QA server is being used) Prod API Base: `https://api.mediamath.com/component_creatives/v3.0/` v3.0 endpoints use Bearer (JWT) authentication via the `Authorization` header. ## Component Creatives API v1.0 (deprecated) > **Deprecated:** The v1.0 endpoints are deprecated. Please migrate to v3.0. QA API Base: `https://t1qa1.mediamath.com/component_creatives/v1.0/` (or whichever QA server is being used) Prod API Base: `https://api.mediamath.com/component_creatives/v1.0`
 - [Marketplaces API V2.0 API](https://apidocs.mediamath.com/apis/marketplaces.md)
 - [Reporting API V1](https://apidocs.mediamath.com/apis/reporting-api-v1.md): {% 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|
 - [Video Creatives](https://apidocs.mediamath.com/apis/video-creatives.md): To work with the MediaMath API with Video Creatives, first generate an [authentication token](/guides/authentication). For more information on Video Creatives, please see the [Video/VPAID Specification](https://support.infillion.com/article/s/article/Video-Creative-Format-Specs) and [The MediaMath Platform Video/Audio tab](https://support.infillion.com/article/s/article/Video-Audio-Tab). *Example HTTPie command to list all video creatives.* `http GET https://api.mediamath.com/api/v3.0/atomic_creatives?q==media_type==video` ## Migration Notice The following V2.0 endpoints are deprecated and replaced by V3.0 equivalents. | Deprecated V2.0 Endpoint | Use Instead | |---|---| | `GET /api/v2.0/atomic_creatives` | `POST /v3.0/creatives/list` | | `GET /api/v2.0/atomic_creatives/{atomic_creative_id}` | `GET /v3.0/creatives/{creativeId}` | | `POST /video/v2.0/creatives` | `POST /v3.0/creatives` | | `GET /video/v2.0/creatives/{video_id}` | `GET /v3.0/creatives/{creativeId}` | | `POST /video/v2.0/creatives/{video_id}` | `POST /v3.0/creatives/{creativeId}` or `PATCH /v3.0/creatives/{creativeId}` | | `GET /video/v2.0/creatives/{video_id}/companions` | `GET /v3.0/creatives/{creativeId}/companions` | | `POST /video/v2.0/creatives/{video_id}/companions` | `POST /v3.0/creatives/{creativeId}/companions` | | `GET /video/v2.0/creatives/{video_id}/companions/{companion_id}/delete` | `DELETE /v3.0/creatives/{creativeId}/companions/{companionId}` | | `POST /video/v2.0/creatives/{video_id}/upload` | `POST /v3.0/creatives` with the `fileName` field (returns a pre-signed S3 upload URL) | | `POST /video/v2.0/creatives/validateVAST` | `POST /v3.0/creatives/validateVAST` | See the **Video Creative Management (V3)** section below for the V3.0 API.
 - [Marketplaces API V2.0 API](https://apidocs.mediamath.com/apis/marketplaces-api/marketplaces.md)
 - [Campaigns API](https://apidocs.mediamath.com/apis/campaigns-api/openapi.md): MediaMath Campaign Management API [Postman Collection](https://apidocs.mediamath.com/guides/postman-collections)
 - [Reporting API V2](https://apidocs.mediamath.com/apis/reporting-api/openapi.md): OpenAPI 3.0 spec of the Reporting API. <!-- theme: info --> > ### Beta datasets > > Datasets marked as **(beta)** are subject to change or removal without prior notice, and are offered as is with no support.