# Report Data {% 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 {% /admonition %} # Parameters Parameter names are case sensitive, (see the table below). Most parameters will fall under one of the following two formats. * enumeration of comma-separated items (used in aggregation, selection and sorting); * example: * dimensions=campaign_id%2Ccampaign_name%2Ccampaign_start_date (in other words, campaign_id,campaign_name,campaign_start_date) * list of logically AND-ed expressions, joined by ampersand (used in dimension and metric filtering); * examples: * filter=campaign_id%3D12345%26strategy_id%3D98765 (in other words, campaign_id=12345&strategy_id=98765) * having=impressions%3E%3D500%26clicks%3C100 (in other words, impressions>=500&clicks section. For more information about the filter and having parameters see the following section. #### Predicate Parameters filter and having are predicate parameters. One of the two parameters is required. The parameters consist of one or more predicates. A predicate has the following format. 1. a dimension or metric field from the report definition 2. an operator from the _Operators supported in filtering expressions_ table 3. one or more values matching the type of field At least one predicate parameters is required. This is because at least one of the predicates must use one of the access dimension fields in an equality test (operator =). The filter parameter filters on dimension fields only, while the having parameter may filter by both dimension and metric fields. The filter parameter is applied before rows are grouped, while the having parameter is applied after rows have been grouped, and metrics have been calculated. The parameter filter is not required if access dimension fields are used in parameter having. Using dimension fields in the having parameter causes those dimension fields to be used in grouping rows. ##### Operators supported in filtering expressions |Operators|Operation|Field Data Type| |--- |--- |--- | |=, !=|equality, non-equality check|all| |>, =, =500&clicks = ~ ! : The encoding is a simple two step process. 1. Double quotes are doubled. 2. The resultant value is surrounded in double quotes. The following shows an example. * Unencoded: Jack & Jill "Of All Trades" * Encoded: "Jack & Jill ""Of All Trades""" This special encoding may be applied to any value in the predicates. It does not determine the type. The looseness is there to allow for URLs to be more readable. It does however, need to be applied before URL encoding is performed. ### Aggregation Through the dimensions, one can indicate the way the rows must be grouped. One or more dimension fields, may be specified. The order in which the dimension fields are listed is important for the result set. ### group by these fields in this order dimensions=campaign_id%2Ccampaign_name%2Ccampaign_start_date ### (i.e. campaign_id,campaign_name,campaign_start_date) See the Time Field section of the for grouping options available for the time field. Grouping by metric fields is not allowed. Metric fields are calculated based on the underlying rows of each group. The metrics can be chosen via the metrics parameter. ### calculate these metrics per group dimensions=clicks%2Cimpressions ### (i.e. clicks,impressions) # On Success The system returns an appropriate HTTP return code (2xx or 3xx - see RFC 2616). The response body is CSV-formatted (Content-Type: text/csv), consisting of one header row, and zero or more data rows. The response uses the HTTP 1.1 chunking feature. A data row will represent a group. It will have a start_date/end_date format, or an interval format. Always use the header line to determine the order of columns, as they may not match the order listed in the parameters. ### start_date/end_date Format * two columns of type datetime: * start_date - the start of the time rollup interval (inclusive) * end_date - the end of the time rollup interval (inclusive) * all dimension fields specified in the parameters dimensions * all metric fields specified in the parameter metrics * all fields, dimension or metric, specified in the parameters having and order Note that the start_date and end_date will cover the whole interval specified by the parameter time_window (or start_date \/ end_date equivalents), or the intervals generated according to the parameter time_rollup, even though data may not exist for the whole interval. start_date,end_date,campaign_id,campaign_name,creative_id,creative_name,clicks,impressions,total_spend "2013-05-01","2013-05-22",123456,"My Campaign Nr 10",98765432,"Creative No 12",17701,171981779,45266.65 "2013-04-24","2013-04-30",123456,"My Campaign Nr 10",11223344,"Creative Nr Five",4101,45076933,7566.57 "2013-04-24","2013-04-30",123456,"My Campaign Nr 10",12121212,"Creative Ten",5220,42592353,6360.86 "2013-05-01","2013-05-22",123456,"My Campaign Nr 10",99887766,"Creative One",21912,41691908,61644.34 ### interval Format * one field of type interval: * interval - the pre-aggregated interval of the group. * all dimension fields specified in the parameters dimensions * all metric fields specified in the parameter metrics * all fields, dimension or metric, specified in the parameters having and order interval,campaign_id,campaign_name,creative_id,creative_name,clicks,impressions,total_spend 7,123456,"My Campaign Nr 10",98765432,"Creative No 12",17701,171981779,45266.65 7,123456,"My Campaign Nr 10",11223344,"Creative Nr Five",4101,45076933,7566.57 7,123456,"My Campaign Nr 10",12121212,"Creative Ten",5220,42592353,6360.86 7,123456,"My Campaign Nr 10",99887766,"Creative One",21912,41691908,61644.34 ### Predicting the Format interval based report queries will return the interval format. datetime based report queries: * using a special time window will return the interval format. * using a normal time window will return the start_date/end_date format. # On Error On error, an appropriate HTTP status code is returned (4xx or 5xx - see RFC 2616). The response body, which of type XML (Content-Type: text/xml`) will contain, at the minimum (see examples below), the root element result, with at least one element named status, which in turn has an attribute named code, and a human readable text. Some error responses also contain an attribute reason, which adds more information regarding the error. There are several types of errors: ### Authentication and authorization errors HTTP/1.0 401 Unauthorized Content-Type: text/xml; charset=UTF-8 Authentication Required HTTP/1.0 403 Forbidden Content-Type: text/xml; charset=UTF-8 Insufficient permissions ### Parameter validation errors (malformed values, unknown fields, missing required parameters, etc) HTTP/1.0 400 Bad Request Content-Type: text/xml; charset=UTF-8 a time window is required ### Non-existent entities HTTP/1.0 404 Not Found Content-Type: text/xml; charset=UTF-8 Entity Not Found ### Server errors (internal error, request timeout, scheduled maintenance, server overloaded) HTTP/1.0 500 Internal Server Error Content-Type: text/xml; charset=UTF-8 Internal Server Error HTTP/1.0 500 Internal Server Error Content-Type: text/xml; charset=UTF-8 The request timed out HTTP/1.0 503 Service Unavailable Content-Type: text/xml; charset=UTF-8 The server is temporarily unavailable due to maintenance downtime. Endpoint: GET /{report} ## Path parameters: - `report` (string, required) {% 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 {% /admonition %} This must be a report discoverable from https://apidocs.mediamath.com/apis/reporting-api-v1/metadata/get_meta. ## Header parameters: - `Cookie` (string, required) _ - `Accept-Encoding:` (string) If the client supports the compression methods also supported by the server (currently gzip and deflate), the response data set (text\/csv) will be returned in a compressed format. The metadata and error responses will not be compressed. In order to receive the data in compressed format, the client must use the HTTP request header Accept-Encoding, and enumerate the preferred compression methods (see RFC 2616). If the header Accept-Encoding is not present in the request, or if it contains only compression methods not supported by the system, the data will be returned in an uncompressed format. ### request Accept-Encoding: gzip,deflate ### response Content-Encoding: gzip Content-Type: text/csv; charset=UTF-8 Enum: "gzip,deflate" - `If-Modified-Since` (string) If the data has not changed, the server responds with a 304 Not Modified status code and an empty response body. If the same request was issued and the data had been updated since the specified time, the server responds with the data requested and a new Last-Modified header. ## Query parameters: - `dimensions` (string, required) Selects the dimension fields to use in grouping rows. This should be a comma-separated list of dimension field names. The position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output. - `metrics` (string) Controls the selection of metric fields. This should be a comma-separated list of metric field names. If not specified, this will default to the metric fields specified by the default_metrics property of the . The position of the fields in the output is not guaranteed to match the parameter value. Always use the header line from the response body to identify the position of each column in the output. - `filter` (string, required) Controls filtering against dimension fields. The filtering is performed before row grouping. See the Predicate Parameters section of for more information about interpretation and accepted formats. - `having` (string) Controls filtering against metric and dimension fields. The filtering is performed after row grouping and metric calculation. See the Predicate Parameters section of for more information about interpretation and accepted formats. - `time_rollup` (string, required) The allowed values are specified by the time_rollups report meta property. See the Time Field section of for more information. - `time_window` (string, required) Controls filtering against the time field for the report. See the Time Field section of for more information. - `start_date` (string, required) Controls filtering against the time field for the report. See the Time Field section of for more information. - `end_date` (string) Controls filtering against the time field for the report. See the Time Field section of for more information. - `order` (string) Controls the sorting of the groups. This should be a comma-separated list of field names. Each field name may optionally be prefixed with a minus sign to indicate descending order. Otherwise, ascending order is assumed. The first field has the most significance in sorting. - `page_limit` (integer) Controls the maximum number of rows of data. This parameter is required, if page_offset is one or greater. - `page_offset` (integer) Controls how many pages to skip. - `precision` (integer) Controls how many digits to the right of the decimal places to display for float types. ## Response 200 fields ## Response 304 fields ## Response 400 fields ## Response 401 fields ## Response 403 fields ## Response 404 fields