# Data Retrieval

_

## Report Data

 - [GET /{report}](https://apidocs.mediamath.com/apis/reporting-api-v1/data-retrieval/get_report.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
{% /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.

## Validate Report Data Request

 - [GET /{report}/validate](https://apidocs.mediamath.com/apis/reporting-api-v1/data-retrieval/get_report-validate.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
{% /admonition %}

### Validating Data Retrieval Requests

Data retrieval requests can be validated and authenticated without actually requesting data, by simply appending a /validate path segment to the URI. Important: The validation process takes into account the current user's permissions. The error responses that are returned in case of validation failure are the same as the ones that would have been returned by the regular API call.

The following shows an example validation request for a request with an erroneous organization_id filtering parameter:


GET /reporting/v1/std/{report}/validate?filter=organization_id%3D12345&dimensions=campaign_id%2Corganization_id&time_window=last_7_days&time_rollup=by_day



HTTP/1.0 404 Not Found
Content-Type: text/xml; charset=UTF-8



  
  Entity Not Found



By contrast, this call shows a validation response for a valid call:


GET /reporting/v1/std/{report}/validate?filter=organization_id%3D12346&dimensions=campaign_id%2Corganization_id&time_window=last_7_days&time_rollup=by_day



HTTP/1.0 200 OK
Content-Type: text/xml; charset=UTF-8