Commerce Grid Reporting API

Access to the CGrid API is secured using OAuth 2.0, managed through the CGrid IAM service.

Before making any requests to the API, your application needs to obtain an access token. This token must be included in the Authorization header of each request.

Base URL

https://pub.themediagrid.com/api/uslicer/reporting/

Required Headers

Make sure to include the following headers in every request:

Here’s a simple example using curl:

curl -X GET https://pub.themediagrid.com/api/uslicer/reporting/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"
  -d '{
      "start_date": "2025-05-15",
      "end_date": "2025-05-22",
      "split_by": [
        "granularity_day"
      ],
      "timezone": 0,
      "order_by": [
        {
          "name": "granularity_day",
          "direction": "ASC"
        }
      ],
      "add_keys": [
        "granularity_hour"
      ],
      "data_fields": [
        "pub_payout"
      ],
      "limit": 100,
      "offset": 0,
      "include_others": true
    }'

Response Format

{
  "status": "success",
  "uslicer-spark.version": "4.19.0",
  "rows": [
    {
      "data": [
        {
          "name": "pub_payout",
          "value": 7095.69,
          "percent": "24.52106"
        }
      ],
      "name": "2025-05-15",
      "confidence_range": null,
      "mapping": null
    },
    {
      "data": [
        {
          "name": "pub_payout",
          "value": 7225.84,
          "percent": "24.97080"
        }
      ],
      "name": "2025-05-16",
      "confidence_range": null,
      "mapping": null
    },
    {
      "data": [
        {
          "name": "pub_payout",
          "value": 8233.03,
          "percent": "28.45142"
        }
      ],
      "name": "2025-05-17",
      "confidence_range": null,
      "mapping": null
    },
    {
      "data": [
        {
          "name": "pub_payout",
          "value": 6382.58,
          "percent": "22.05672"
        }
      ],
      "name": "2025-05-18",
      "confidence_range": null,
      "mapping": null
    }
  ],
  "total": {
    "data": [
      {
        "name": "pub_payout",
        "value": 28937.15
      }
    ],
    "dates": [
      "2025-05-15",
      "2025-05-16",
      "2025-05-17",
      "2025-05-18"
    ],
    "records_found": 4,
    "confidence_range": null
  },
  "others": {
    "data": [
      {
        "name": "pub_payout",
        "value": 0,
        "percent": "0.00000"
      }
    ],
    "confidence_range": null,
    "key_count": 0
  }
}

Request

• Description:

  • Returns report data restricted by query parameters passed in POST arguments.

• URL:

  • https://pub.themediagrid.com/api/uslicer/reporting/

• URL arguments:

  • None

POST arguments*:
(required unless marked optional)

New fields, such as currencies may appear here.

• limit (optional): the maximum number of returned rows. Possible values: any integer in the range from -1 to 10,000. -1 means all rows. The default value is -1.

• offset (optional): skip the specified number of rows from the result. Together with the limit POST argument allows querying large datasets. The default value is 0. Can be used only, if the limit POST argument is in the range from 0 to 10,000.

• add_keys(optional): the array of key fields to add. Format: ["key_field1", ... ].

• split_by: an array of the key fields to split data by in the form of ["key_field1",...]

• start_date: the start of the date range to gather data for. Supported formats:

  • Absolute dates: YYYY-MM-DD.

  • Relative dates:

    • today, yesterday

    • -Nd and -Ndays for the number of days since the current date, where N - any positive integer or zero.

    • -Nm and - Nmonths for the number of months since the current date, where N - any positive integer or zero.

• end_date: the end of the date range to gather data for. Supported formats:

  • Absolute dates: YYYY-MM-DD.

  • Relative dates:

    • today, yesterday

    • -Nd and -Ndays for the number of days since the current date, where N - any positive integer or zero.

    • -Nm and - Nmonths for the number of months since the current date, where N - any positive integer or zero.

• timezone (optional): time zone UTC offset in hours. Format: N , where N - any integer in the range of -12 <= N <= +12.

• order_by (optional): defines sorting rules.

  • "name": "field", the name of the key or data field to sort the results by. Note that this field can be any key field, specified in the split_by POST argument, or one of the data fields specified by the data_fields POST argument (or any of the data fields if the  data_fields POST argument is not specified). The default value is the first column with enabled percent.

  • "mapping": defines whether to sort by key field ID or by key field mapping. Possible values: (0 - sort by key field ID, 1 - sort by key field mapping). The default value is 0.

  • "direction": sort in the ascending or descending order, either ASC or DESC. The default value is DESC.

• data_fields (optional): the array of data fields to be returned in the form of ["data_field1", ....].

• include_others (optional): return the summary of data outside the specified limit.

• include_mappings (optional): defines whether key field value mappings are returned by the API request. The default value is 1 (mappings are returned) if only 1 key field is used in the split_by POST argument. The default value is 0 (mappings are not returned) if 2 or more key fields are used in the split_by POST argument.

• filters (optional):

  • name": "key_field",

  • "case_insensitive": (optional), defines whether search should be case-insensitive. Possible values: (1 - case-insensitive, 0 - case-sensitive). The default value is 0.

  • "search_mappings": (optional), defines whether the search should be performed in mappings. Possible values: (1 - search should be performed in both key field values and their mappings, 0 - search should be performed in key field values only). The default value is 0.

  • "value": ["value1", ... ], where the value of the "value" field should be an array.

  • "match": "equals|not equals|contains|not contains|beginswith|endswith|not beginswith|not endswith"

  • if "search_mappings" is set to 1, the search will be performed for both specified key field values and their mappings (descriptions). For example, if you have the creative_id key field with some value of "1" and its mapping of "First Creative", you can search for it as follows:

    {"name": "creative_id", "value": ["First Creative"],"match":"equals", "search_mappings": 1}

    OR

    {"name": "creative_id", "value": [1],"match": "equals"}

  • Regarding the account filters: if the account is not explicitly specified in the filters, it's taken from the user (based on the account selected by the user). If no account is selected (this case should only occur for superusers), an error is raised. Account filter example:

    "filters": [
      {
        "match": "equals",
        "value": [
            "211"
        ],
        "case_insensitive": 1,
        "search_mappings": 1,
        "name": "publisher.account_id"
      }
    ]

List of available reporting dimensions and data_fields

Below is a table of available reporting dimensions and fields that can be requested.

In the table, "UI Name" refers to how the report or field is named in the Reporting Tab in the Commerce Grid UI. The "API Name" refers to how the same report or field should be called when utilizing the API. "Description" defines a given report or field.

Response

The response may vary slightly due to additional aggregations.

• status: the status of the request. success, if the request was processed successfully, or error code, if any error occurred. If the status is not success, then the response contains the status and reason fields only. Possible values:

  • success: the request was processed successfully.

  • bad_request: invalid request parameters, please see the reason field for more details.

  • timeout: the request took too long to complete.

  • access_error: the user doesn't have access to the specified project/slicer, or a wrong token was used.

  • internal_error: the request failed due to an unknown problem.

• reason: user-friendly description of the occurred error. This field is displayed for failed requests only.

• total: this section contains information about the entire dataset returned by the query.

  • data: the summary values for each data column found in the result dataset. It's an array of elements with the following fields:

    • name: data field name.

    • value: data field value.

    • comment (optional): calculation comment (only for custom data columns), can be inf , -inf in case of stack overflow, "Division by zero" , and ERROR! at any other errors in calculation. In all of these cases, the value is displayed as 0.

  • records_found: the total number of found records.

  • confidence_range: the confidence range for data (in percent, presented in this section, if the returned dataset is compressed. Available for the Total rows. Contains “N/A” if compressed is unknown and 0 for uncompressed rows.

  • dates: the array with all the dates, for which data exist in the period from the start_date to the end_date.

• rows: this section contains query data results. It is an array of data rows, each containing the following fields:

  • data: the list of items with the following field names and values:
    

    • name: data field name.

      • value: data field value.

      • percent (optional): percent of the total value (if applicable).

      • comment (optional): calculation comment (only for custom data columns), can be inf,-inf in case of stack overflow, "Division by zero" , and ERROR! at any other errors in calculation. In all of these cases, the value is displayed as 0.

  • name: the value of the split_by key field for this row, including six specific time-related fields:

    • granularity_hour: data, aggregated by day+hour, where each key field value contains 1 item (date and hour) like:
      "name": [ "2013-09-30 19:00" ]

    • granularity_day: data, aggregated by day, where each key field value contains 1 item (date) like:
      "name": "2013-09-30"

    • granularity_week: data, aggregated by week, where each key field value contains 1 item (week) like:
      "name": "2013-W48"

    • granularity_month: data aggregated by month, where each key field value contains 1 item (month) like:
      name": "2013-09"

    • granularity_quarter: data aggregated by quarter, where each key field value contains 1 item (quarter) like:
      name": "2013 Q4"

    • granularity_year: data aggregated by year, where each key field value contains 1 item (year) like:
      name": "2013"

Note: If the split_by POST argument contains several key fields, then the name parameter also contains several key fields.

• mapping (optional): the mappings of the current row key field values for the key fields specified in the split_by POST argument. Mapping display is defined by the include_mappings POST argument.

  • confidence_range: the confidence range for data (percent), presented in this section if the returned dataset is compressed. Available for every data row in the resulting dataset.

  • others (optional): the summary of data rows beyond the range defined by limit + offset, if the include_others POST argument was set to 1. It's an array of elements with the following fields:
    

    • data: the list of Total values of data rows beyond the range defined by limit + offset for the data fields specified in the data_fields POST argument. It's an array of elements with the following fields:

      • name: data field name.

      • value: data field Total value for data rows beyond the range defined by limit + offset.

      • percent (optional): percent of the data field Total value for data rows beyond the range defined by limit + offset (if applicable).

    • confidence_range: the confidence range for data (in percent), presented in this section if the returned dataset is compressed. Available for the Total values matching data rows beyond the range defined by limit + offset. Contains “N/A” if compressed is unknown and 0 for uncompressed rows.

    • key_count: the number of data rows beyond the range defined by limit + offset .