MediaMath Data Retrieval API

openapi: 3.2.0
info:
  version: ''
  contact:
    name: API Support
    url: https://www.mediamath.com/contact-us/
    email: support@mediamath.com
  title: Reporting API V1 Data Retrieval API
  description: '{% 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 %}


    {% 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.'
  license:
    url: http://www.apache.org/licenses/LICENSE-2.0.html
    name: Apache 2.0
servers:
- url: https://api.mediamath.com/reporting/v1/std
tags:
- name: Data Retrieval
  description: _
paths:
  /{report}:
    parameters:
    - name: report
      in: path
      description: This must be a report discoverable from https://apidocs.mediamath.com/apis/reporting-api-v1/metadata/get_meta.
      required: true
      schema:
        type: string
    get:
      operationId: GET_report
      summary: Report Data
      tags:
      - Data Retrieval
      description: '{% 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).'
      parameters:
      - $ref: '#/components/parameters/trait_cookieAuth_Cookie'
      - $ref: '#/components/parameters/trait_requestsCustomTimeWindow_dimensions'
      - $ref: '#/components/parameters/trait_requestsCustomTimeWindow_metrics'
      - $ref: '#/components/parameters/trait_requestsCustomTimeWindow_filter'
      - $ref: '#/components/parameters/trait_requestsCustomTimeWindow_having'
      - $ref: '#/components/parameters/trait_requestsCustomTimeWindow_time_rollup'
      - $ref: '#/components/parameters/trait_requestsCustomTimeWindow_time_window'
      - $ref: '#/components/parameters/trait_requestsCustomTimeWindow_start_date'
      - $ref: '#/components/parameters/trait_requestsCustomTimeWindow_end_date'
      - $ref: '#/components/parameters/trait_requestsCustomTimeWindow_order'
      - $ref: '#/components/parameters/trait_requestsCustomTimeWindow_page_limit'
      - $ref: '#/components/parameters/trait_requestsCustomTimeWindow_page_offset'
      - $ref: '#/components/parameters/trait_requestsCustomTimeWindow_precision'
      - $ref: '#/components/parameters/trait_requestsCustomTimeWindow_Accept-Encoding_'
      - $ref: '#/components/parameters/trait_requestsCustomTimeWindow_If-Modified-Since'
      responses:
        '200':
          $ref: '#/components/responses/trait_requestsCustomTimeWindow_200'
        '304':
          $ref: '#/components/responses/trait_requestsCustomTimeWindow_304'
        '400':
          $ref: '#/components/responses/trait_requestsCustomTimeWindow_400'
        '401':
          $ref: '#/components/responses/trait_requestsCustomTimeWindow_401'
        '403':
          $ref: '#/components/responses/trait_requestsCustomTimeWindow_403'
        '404':
          $ref: '#/components/responses/trait_requestsCustomTimeWindow_404'
  /{report}/validate:
    parameters:
    - name: report
      in: path
      required: true
      description: This must be a report discoverable from https://apidocs.mediamath.com/apis/reporting-api-v1/metadata/get_report-meta.
      schema:
        type: string
    get:
      operationId: GET_report-validate
      summary: Validate Report Data Request
      tags:
      - Data Retrieval
      description: '{% 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


        ```'
      parameters:
      - $ref: '#/components/parameters/trait_cookieAuth_Cookie'
      - $ref: '#/components/parameters/trait_requestsCustomTimeWindow_dimensions'
      - $ref: '#/components/parameters/trait_requestsCustomTimeWindow_metrics'
      - $ref: '#/components/parameters/trait_requestsCustomTimeWindow_filter'
      - $ref: '#/components/parameters/trait_requestsCustomTimeWindow_having'
      - $ref: '#/components/parameters/trait_requestsCustomTimeWindow_time_rollup'
      - $ref: '#/components/parameters/trait_requestsCustomTimeWindow_time_window'
      - $ref: '#/components/parameters/trait_requestsCustomTimeWindow_start_date'
      - $ref: '#/components/parameters/trait_requestsCustomTimeWindow_end_date'
      - $ref: '#/components/parameters/trait_requestsCustomTimeWindow_order'
      - $ref: '#/components/parameters/trait_requestsCustomTimeWindow_page_limit'
      - $ref: '#/components/parameters/trait_requestsCustomTimeWindow_page_offset'
      - $ref: '#/components/parameters/trait_requestsCustomTimeWindow_precision'
      - $ref: '#/components/parameters/trait_requestsCustomTimeWindow_Accept-Encoding_'
      - $ref: '#/components/parameters/trait_requestsCustomTimeWindow_If-Modified-Since'
      responses:
        '200':
          $ref: '#/components/responses/trait_requestsCustomTimeWindow_200'
        '304':
          $ref: '#/components/responses/trait_requestsCustomTimeWindow_304'
        '400':
          $ref: '#/components/responses/trait_requestsCustomTimeWindow_400'
        '401':
          $ref: '#/components/responses/trait_requestsCustomTimeWindow_401'
        '403':
          $ref: '#/components/responses/trait_requestsCustomTimeWindow_403'
        '404':
          $ref: '#/components/responses/trait_requestsCustomTimeWindow_404'
components:
  responses:
    trait_requestsCustomTimeWindow_403:
      description: ''
    trait_requestsCustomTimeWindow_401:
      description: ''
    trait_requestsCustomTimeWindow_404:
      description: ''
    trait_requestsCustomTimeWindow_304:
      description: ''
    trait_requestsCustomTimeWindow_200:
      description: ''
    trait_requestsCustomTimeWindow_400:
      description: ''
  parameters:
    trait_requestsCustomTimeWindow_dimensions:
      name: dimensions
      in: query
      description: '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.'
      required: true
      schema:
        type: string
    trait_requestsCustomTimeWindow_filter:
      name: filter
      in: query
      description: Controls filtering against dimension fields.  The filtering is performed before row grouping.  See the Predicate Parameters section of <https://apidocs.mediamath.com/apis/reporting-api-v1/data-retrieval/get_report> for more information about interpretation and accepted formats.
      required: true
      schema:
        type: string
    trait_cookieAuth_Cookie:
      name: Cookie
      description: _
      in: header
      required: true
      schema:
        type: string
        default: adama_session=<<sessionid>>
    trait_requestsCustomTimeWindow_end_date:
      name: end_date
      in: query
      description: Controls filtering against the time field for the report.  See the Time Field section of <https://apidocs.mediamath.com/apis/reporting-api-v1/metadata/get_report-meta> for more information.
      required: false
      schema:
        type: string
        default: yesterday
    trait_requestsCustomTimeWindow_time_rollup:
      name: time_rollup
      in: query
      description: The allowed values are specified by the time_rollups report meta property.  See the Time Field section of <https://apidocs.mediamath.com/apis/reporting-api-v1/metadata/get_report-meta> for more information.
      required: true
      schema:
        type: string
    trait_requestsCustomTimeWindow_If-Modified-Since:
      name: If-Modified-Since
      in: header
      description: '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.'
      schema:
        type: string
        format: date-time
    trait_requestsCustomTimeWindow_precision:
      name: precision
      in: query
      description: Controls how many digits to the right of the decimal places to display for float types.
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 8
        default: 8
    trait_requestsCustomTimeWindow_having:
      name: having
      in: query
      description: Controls filtering against metric and dimension fields.  The filtering is performed after row grouping and metric calculation.  See the Predicate Parameters section of <https://apidocs.mediamath.com/apis/reporting-api-v1/data-retrieval/get_report> for more information about interpretation and accepted formats.
      required: false
      schema:
        type: string
    trait_requestsCustomTimeWindow_page_offset:
      name: page_offset
      in: query
      description: Controls how many pages to skip.
      required: false
      schema:
        type: integer
        minimum: 0
    trait_requestsCustomTimeWindow_time_window:
      name: time_window
      in: query
      description: Controls filtering against the time field for the report.  See the Time Field section of <https://apidocs.mediamath.com/apis/reporting-api-v1/metadata/get_report-meta> for more information.
      required: true
      schema:
        type: string
    trait_requestsCustomTimeWindow_start_date:
      name: start_date
      in: query
      description: Controls filtering against the time field for the report.  See the Time Field section of <https://apidocs.mediamath.com/apis/reporting-api-v1/metadata/get_report-meta> for more information.
      required: true
      schema:
        type: string
    trait_requestsCustomTimeWindow_metrics:
      name: metrics
      in: query
      description: '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 <https://apidocs.mediamath.com/apis/reporting-api-v1/metadata/get_report-meta>.


        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.'
      required: false
      schema:
        type: string
    trait_requestsCustomTimeWindow_order:
      name: order
      in: query
      description: '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.'
      required: false
      schema:
        type: string
    trait_requestsCustomTimeWindow_Accept-Encoding_:
      name: 'Accept-Encoding:'
      in: header
      description: "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.\n\nIn 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](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)). 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.\n\n    ###  request \n    Accept-Encoding: gzip,deflate   \n\n    ###  response  \n    Content-Encoding: gzip \n    Content-Type: text/csv; charset=UTF-8 "
      schema:
        type: string
        enum:
        - gzip,deflate
    trait_requestsCustomTimeWindow_page_limit:
      name: page_limit
      in: query
      description: 'Controls the maximum number of rows of data.


        This parameter is required, if page_offset is one or greater.'
      required: false
      schema:
        type: integer
        minimum: 1
        default: 100
  securitySchemes:
    API_Key_-_1:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.mediamath.com/oauth/token
          scopes: {}
x-stoplight:
  id: bmaieg1p7ctvh