Query Endpoint

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 100.

offset

(optional) Skips the specified number of rows from the result. Together with limit, this argument allows you to query large datasets. The default value is 0, and can be used only if the limit value is in the range from 0 to 10,000.

include_cumulative

(optional) Defines whether to display the total values for the topN data rows, where N = limit + offset. Possible values: 0 - don’t display Total values for top N data rows, 1 - display Total values for top N data rows. The default value is 0.

filters

(optional) An array of filters, each filter is built using the following format:

• name (str) Specifies the key you wish to query e.g. "name": "bid_context_wrapper.user.geo.country"

• value (array of str) Specifies the values for the key you want to query e.g. "value": ["US", "CA"]

• search_mappings (optional), defines whether the search should be performed in mappings. Possible values:

  • 0 search should be performed in key field values only, this is tge default.

  • 1 search should be performed in both key field values and their mappings,

  • 2 - search should be performed in key field mappings only). The default value is 0.

• match (str) Sets the conditions of how the names and values should be queried. It takes the following valid values:

  • "equals"

  • "not equals"

  • "contains"

  • "not contains"

  • "begins with"

  • "ends with"

• case_insensitive (int) (optional)

  • 0 case-sensitive. The default value is 0.

  • 1 case-insensitive

split_by

An array of key values from those set in tthe filters field by which to split data. Takes the form of ["key_field1", "key_field2"].

start_date

Sets the start of the date range from which to gather data. 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 is any positive integer or zero.

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

  • -Nm_first, -Nmonths_first, -Nm_last and -Nmonth_last for the first and the last day of the specified month correspondingly, where N - any positive integer or zero.

end_date

Sets the end of the date range from which to gather data. 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 is any positive integer or zero.

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

  • -Nm_first, -Nmonths_first, -Nm_last and -Nmonth_last for the first and the last day of the specified month correspondingly, where N - any positive integer or zero.

timezone

(optional): Time zone UTC offset in hours, where N can be any integer in the range of -12 <= N <= +12

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.

include_total

(optional): defines whether to display Total values in the exported file. Possible values: (0 - don’t display Total values in the exported file, 1 - display Total values in the exported file). The default value is 0.

data_fields

(optional) An array of data fields to be returned, e.g. "data_fields": [ "imps", "clicks", "payout.actual_pub", "bids"]

To receive the details of all data fields available to you, use the Info Endpoint.

data_filters

(optional) An array of objects, with each object defining a filters to apply to the data returned for the data_fields filter. e.g. "data_filters": [{"name": "payout.actual_pub", "value": "7", "match": "<="}]

• name specifies the returned data field to use as the filtering basis

• value specifies the value to use as the filter

• match specifies how the value is applied, take the following options: <, >, <=, >=

status

Returns the status of the request, success if the request was processed successfully, or an error code if any error occurred. If the request is not successful, then the response contains the status and reason fields only.

• 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

A user-friendly description of the error which occured. This field is displayed for failed requests only.

total

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

• data: this section contains 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.

• records_found: the total number of found records.

• confidence_range: the confidence range for data (percent), presented in this section, if returned dataset is compressed. Available for the total 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 field name and field value:

  • name data field name.

  • value data field value.

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

• 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 1: If the split_by POST argument contains several key fields, then the name parameter also contains several key fields.

  • Note 2: If the split_by POST argument contains several key fields, queries returning more than 1,000,000 rows of data are rejected.

confidence_range

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