Reporting

We have 4 types of reports:

  • advertiser-level reports
  • publisher-level reports
  • network-level reports
  • inventory reports

Reports are constructed using JSON.

Here is an example report:

{
  "scope": "advertiser",
  "groups": [
    "campaign_id"
  ],
  "metrics": [
    "impressions"
  ],
  "where": [
    ["advertiser_id", "==", "1337"]
  ],
  "from": "2016-04-01 00:00:00",
  "to": "2016-05-02 00:00:00",
  "timezone": "UTC",
  "emails": ["test@example.com"]
}
Parameter Required Description
scope Yes is the string advertiser, publisher, network_buy, network_sell, network_managed or inventory to select the type of report.
groups Yes* is a list of group columns
metrics Yes* is a list of metric columns.
where Yes is a list of expression lists.
An expression list is in the form of [column, op, value].
column can be any of the group columns or sum columns.
op can be any of ==, !=, in or not in as a string.
value is either a number or in case of in and not in an list of numbers.
from Yes is a date/time formatted like YYYY-MM-DD HH:00:00 and is inclusive.
It is truncated to the hour.
to Yes is a date/time formatted like YYYY-MM-DD HH:00:00 and is exclusive.
It is truncated to the hour.
timezone Yes Timezone used for all times. For a supported list see: timezones
emails No Array of email addresses that get a notification email once the report is ready to download
name No Optional name for the report

* Note: either groups or metrics is required.

The JSON should be POSTed to http://api.atomx.com/v3/report. The following parameters are accepted:

Parameter Value Description
sort [column_name].[asc|desc] Sorting ascending or descending on column names
limit number Specify the number of rows to return. 0 or omitted means unlimited
offset number Specify the row to start at. Default is 0
download none Download the report as TSV instead of inside JSON

This will return a JSON like:

{
  'success': <true or false>,
  'timestamp': <timestamp>,
  'resource': 'report',
  'report': {
    'id': <report ID>,
    'length': <number or rows>,
    'name': <report name>,
    'totals': <sum of each column>,
    'columns': <names of the columns>,
    'data': <list of lists with the data>,
    'user_id': <ID of the user who created the report>,
    'emails': <list of emails>,
    'is_scheduled_report': <true or false>,
    'whitelabel_url': <url the report was run on>,
    'lines': <number of lines in result>,
    'query': <your original query>
  }
}

You can re-run the report by requesting http://api.atomx.com/v3/report/{report-id}

Groups

Advertiser:

Numeric value String value String + numeric value
advertiser_id advertiser_name advertiser_name_id
advertiser_network_id advertiser_network_name advertiser_network_name_id
app_id app_name app_name_id
browser_id browser_name browser_name_id
campaign_id campaign_name campaign_name_id
conversion_pixel_id conversion_pixel_name conversion_pixel_name_id
country_id country_name country_name_id
creative_id creative_name creative_name_id
device_type_id device_type_name device_type_name_id
dma_id dma_name dma_name_id
domain_id domain_name domain_name_id
operating_system_id operating_system_name operating_system_name_id
placement_type_id placement_type_name placement_type_name_id
publisher_id publisher_name publisher_name_id
publisher_network_id publisher_network_name publisher_network_name_id
site_id site_name site_name_id
size_id size_name size_name_id
day
hour
month

Publisher:

Numeric value String value String + numeric value
advertiser_id advertiser_name advertiser_name_id
advertiser_network_id advertiser_network_name advertiser_network_name_id
app_id app_name app_name_id
browser_id browser_name browser_name_id
country_id country_name country_name_id
device_type_id device_type_name device_type_name_id
dma_id dma_name dma_name_id
domain_id domain_name domain_name_id
operating_system_id operating_system_name operating_system_name_id
placement_id placement_name placement_name_id
placement_type_id placement_type_name placement_type_name_id
publisher_id publisher_name publisher_name_id
publisher_network_id publisher_network_name publisher_network_name_id
site_id site_name site_name_id
size_id size_name size_name_id
user_variable_1
user_variable_2
user_variable_3
day
hour
month

Network Buy:

Numeric value String value String + numeric value
advertiser_id advertiser_name advertiser_name_id
advertiser_network_id advertiser_network_name advertiser_network_name_id
app_id app_name app_name_id
browser_id browser_name browser_name_id
campaign_id campaign_name campaign_name_id
conversion_pixel_id conversion_pixel_name conversion_pixel_name_id
country_id country_name country_name_id
creative_id creative_name creative_name_id
device_type_id device_type_name device_type_name_id
dma_id dma_name dma_name_id
domain_id domain_name domain_name_id
network_id network_name network_name_id
operating_system_id operating_system_name operating_system_name_id
placement_type_id placement_type_name placement_type_name_id
publisher_id publisher_name publisher_name_id
publisher_network_id publisher_network_name publisher_network_name_id
site_id site_name site_name_id
size_id size_name size_name_id
day
hour
month

Network Sell:

Numeric value String value String + numeric value
advertiser_id advertiser_name advertiser_name_id
advertiser_network_id advertiser_network_name advertiser_network_name_id
app_id app_name app_name_id
browser_id browser_name browser_name_id
country_id country_name country_name_id
device_type_id device_type_name device_type_name_id
dma_id dma_name dma_name_id
domain_id domain_name domain_name_id
network_id network_name network_name_id
operating_system_id operating_system_name operating_system_name_id
placement_id placement_name placement_name_id
placement_type_id placement_type_name placement_type_name_id
publisher_id publisher_name publisher_name_id
publisher_network_id publisher_network_name publisher_network_name_id
site_id site_name site_name_id
size_id size_name size_name_id
user_variable_1
user_variable_2
user_variable_3
day
hour
month

Network Managed:

Numeric value String value String + numeric value
advertiser_id advertiser_name advertiser_name_id
advertiser_network_id advertiser_network_name advertiser_network_name_id
app_id app_name app_name_id
browser_id browser_name browser_name_id
campaign_id campaign_name campaign_name_id
conversion_pixel_id conversion_pixel_name conversion_pixel_name_id
country_id country_name country_name_id
creative_id creative_name creative_name_id
device_type_id device_type_name device_type_name_id
dma_id dma_name dma_name_id
domain_id domain_name domain_name_id
network_id network_name network_name_id
operating_system_id operating_system_name operating_system_name_id
placement_id placement_name placement_name_id
placement_type_id placement_type_name placement_type_name_id
publisher_id publisher_name publisher_name_id
publisher_network_id publisher_network_name publisher_network_name_id
site_id site_name site_name_id
size_id size_name size_name_id
user_variable_1
user_variable_2
user_variable_3
day
hour
month

Inventory:

Numeric value String value String + numeric value
app_id app_name app_name_id
browser_id browser_name browser_name_id
country_id country_name country_name_id
day_timestamp day_formatted (YYYY-MM-DD)
device_type_id device_type_name device_type_name_id
domain_id domain_name domain_name_id
hour_timestamp hour_formatted (YYYY-MM-DD HH:00:00)
isp_id isp_name isp_name_id
operating_system_id operating_system_name operating_system_name_id
placement_id placement_name placement_name_id
placement_type_id placement_type_name placement_type_name_id
publisher_id publisher_name publisher_name_id
publisher_network_id publisher_network_name publisher_network_name_id
size_id size_name size_name_id
day
hour
month

Metrics

Advertiser

Numeric value
advertiser_network_ppm
advertiser_network_profit
campaign_cost
campaign_cpm
campaign_cr
campaign_ctr
conversion_value
clicks
conversions
impressions

Publisher

Numeric value
block_rate
blocks
clicks
fallbacks
impressions
psas
publisher_ctr
publisher_network_ppm
publisher_network_profit
publisher_network_revenue
publisher_ppm
publisher_profit

Network

Numeric value
advertiser_network_ppm
advertiser_network_profit
block_rate
blocks
campaign_cost
campaign_cpm
campaign_cr
campaign_ctr
clicks
conversions
conversion_value
fallbacks
impressions
media_cost
network_revenue
psas
publisher_ctr
publisher_network_ppm
publisher_network_profit
publisher_network_revenue
publisher_ppm
publisher_profit

Inventory

Numeric value
requests
inventory_cpm

Scheduling reports

The JSON to schedule a recurring report is almost the same as the normal report JSON. The only differences is that the scheduling reporting JSON has a when and interval instead of a to and from.

{
  "scope": "advertiser",
  "groups": [
    "campaign_id"
  ],
  "metrics": [
    "impressions"
  ],
  "where": [
    ["advertiser_id", "==", "1337"]
  ],
  "when": "daily",
  "interval": "2 days",
  "timezone": "UTC",
  "emails": ["test@example.com"]
}

The when parameter accepts the following values:

parameterdescription
dailyThe report will be each day.
monthlyThe report will be run the first day of each month.
mondayThe report will be run each Monday.
tuesdayThe report will be run each Tuesday.
wednesdayThe report will be run each Wednesday.
thursdayThe report will be run each Thursday.
fridayThe report will be run each Friday.
saturdayThe report will be run each Saturday.
sundayThe report will be run each Sunday.

The interval parameter accepts the following values.

valuedescription
N daysThe report will contain the last N days.
N monthsThe report will contain the last N months.

Reports are always run at 1:00 (in the specified timezone).

The JSON should be POSTed to https://api.atomx.com/v3/report
This will return the same report JSON from above but with is_scheduled_report set to true.

The returned ID can be used to cancel the scheduled report with a DELETE to https://api.atomx.com/v3/report/<scheduled report ID>

The reports generated from a scheduled report have an additional json field (schedule_report_id) that tells you which scheduled report triggered the report.