/

Browse the help center

Get statistics report — impressions, clicks, CTR, revenue by date, country or entity (API key auth) — post

Reference

POST https://YOUR-NETWORK-DOMAIN/rest-api/analytics/{format}.do

Returns traffic and revenue statistics — impressions, clicks, CTR, conversions, gross revenue (sumGross), net payout (sumNet), profit, eCPM, requests and fill rate — as JSON, CSV, PDF, XLSX or HTML. Rows are split by date (groupRange) and by the groupBy dimensions such as COUNTRY, ADVERTISER, CAMPAIGN, BANNER, SITE, ZONE, PLACEMENT, CHANNEL or ACTION, and narrowed with the eqLong/eqStr filters over the period set by range. Omit statisticType for the General report; HADOOP gives the Advanced report with device, browser, OS and referer dimensions, HEADER_BIDDING gives the Header Bidding fill report, and the *_LOG types return raw event rows. Only columns the user has permission to see are returned; useReportsLayoutSettings=true with reportsLayoutSettings picks a subset by column id. JSON rows name their fields by the column names in the user's interface language; jsonKeys=id names them by column id instead, the same in every language and never repeated. Each call counts against the network's daily analytics request limit, and limit may not exceed the network's records-per-request limit. A refusal keeps its JSON body with success=false and answers with the matching status: 400 for validation, 401 for authentication, 403 naming the missing reporting permission, 429 for the daily limit. Authenticated via API key.

Path Params

format string required

Output format: JSON, CSV, PDF, XLSX, or HTML

CSV

Form Params

actionCustomParameterFragment string

Custom parameter name fragment for filtering by custom parameter

utm_source

actionCustomValueFragment string

Custom parameter value fragment for filtering by custom parameter

google

actionIds array<integer>

Conversion action IDs to report on; repeat the parameter or comma-separate. Restricts the conversion columns, and the per-action columns of splitColumnsBy=CONVERSION_ACTION, to these actions. Omitted: every action the caller may see.

17

breakdownByActions boolean

When true, adds one conversions column per conversion action. Ignored when splitColumnsBy is set, which supersedes it

true

breakdownByCustomParameter boolean

When true, enables breakdown by custom parameter values

true

customFrom string

First day of the period (yyyy-MM-dd) when range=CUSTOM; ignored for every other range. Defaults to today

2025-01-01

customTo string

Last day of the period, inclusive (yyyy-MM-dd), when range=CUSTOM; ignored for every other range. Defaults to today, so range=CUSTOM with only customFrom reports up to today. Must not be before customFrom

2025-01-31

eqLong object

Numeric ID-based filters using bracket notation: eqLong[FIELD]=value. Repeat the parameter to filter by multiple values: eqLong[SITE]=100&eqLong[SITE]=200. Available fields: BANNER, CAMPAIGN, ADVERTISER, PLACEMENT, ZONE, SITE. Valid keys: PLACEMENT_ID, ZONE_ID, SITE_ID, BANNER_ID, CAMPAIGN_ID, ADVERTISER_ID, PLACEMENT, ZONE, SITE, OPEN_RTB_PUBLISHER_ID, BANNER, CAMPAIGN, ADVERTISER, CHANNEL, ACTION, ACTION_ID, ATTRIBUTION_TYPE, COUNTRY, COUNTRY_GROUP, CARRIER, CONNECTION_TYPE, LANGUAGE, ACCEPT_LANGUAGE, TIME_ZONE_NAME, BROWSER_COUNTRY, TRAFFIC_SOURCE, FILL_SOURCE, LOCATION, CUSTOM_PARAMETER, CUSTOM_PARAMETER_NAME, CUSTOM_PARAMETER_VALUE, PLACEMENT_SIZE, SCREEN_SIZE, DEVICE_FORMAT, PROXY, DEVICE_RELEASE_YEAR, DEVICE_RAM, PRICE_BAND, IS_WEB_APP, IS_INCOGNITO_MODE, BROWSER_RANK, HARDWARE_RANK, PLATFORM_RANK, DEVICE_VENDOR, DEVICE_MODEL, DEVICE_MODEL_CODE, RISK_SCORE, RISK_LEVEL, RISK_CATEGORY, PLACEMENT_TYPE, OPERATING_SYSTEM, OS_VERSION, BROWSER, BROWSER_VERSION, MOBILE_NETWORK, TIME_ZONE, REFERER, APP_PACKAGE, TOP_DOMAIN, PLATFORM, STATUS, BANNER_LABEL, PLACEMENT_LABEL, TEMPLATE_ID, UNIVERSAL_AD_ID, ADVERTISER_OWNER, SITE_OWNER, USER_ADVERTISER_SHARE

{"SITE":100}

eqStr object

String-based filters using bracket notation: eqStr[FIELD]=value. Repeat the parameter to filter by multiple values: eqStr[COUNTRY]=US&eqStr[COUNTRY]=GB. Available fields: CHANNEL, COUNTRY, PLACEMENT_TYPE, BANNER_LABEL, PLACEMENT_LABEL, ACTION, BROWSER, OPERATING_SYSTEM, UNIVERSAL_AD_ID (needs the Banner ISCI / Ad-ID Code permission), and FILL_SOURCE in the Header Bidding report. Valid keys: PLACEMENT_ID, ZONE_ID, SITE_ID, BANNER_ID, CAMPAIGN_ID, ADVERTISER_ID, PLACEMENT, ZONE, SITE, OPEN_RTB_PUBLISHER_ID, BANNER, CAMPAIGN, ADVERTISER, CHANNEL, ACTION, ACTION_ID, ATTRIBUTION_TYPE, COUNTRY, COUNTRY_GROUP, CARRIER, CONNECTION_TYPE, LANGUAGE, ACCEPT_LANGUAGE, TIME_ZONE_NAME, BROWSER_COUNTRY, TRAFFIC_SOURCE, FILL_SOURCE, LOCATION, CUSTOM_PARAMETER, CUSTOM_PARAMETER_NAME, CUSTOM_PARAMETER_VALUE, PLACEMENT_SIZE, SCREEN_SIZE, DEVICE_FORMAT, PROXY, DEVICE_RELEASE_YEAR, DEVICE_RAM, PRICE_BAND, IS_WEB_APP, IS_INCOGNITO_MODE, BROWSER_RANK, HARDWARE_RANK, PLATFORM_RANK, DEVICE_VENDOR, DEVICE_MODEL, DEVICE_MODEL_CODE, RISK_SCORE, RISK_LEVEL, RISK_CATEGORY, PLACEMENT_TYPE, OPERATING_SYSTEM, OS_VERSION, BROWSER, BROWSER_VERSION, MOBILE_NETWORK, TIME_ZONE, REFERER, APP_PACKAGE, TOP_DOMAIN, PLATFORM, STATUS, BANNER_LABEL, PLACEMENT_LABEL, TEMPLATE_ID, UNIVERSAL_AD_ID, ADVERTISER_OWNER, SITE_OWNER, USER_ADVERTISER_SHARE

{"COUNTRY":"US"}

groupBy array<string>

Dimensions to split rows by; repeat the parameter or comma-separate for several. General report (no statisticType): SITE, OPEN_RTB_PUBLISHER_ID, ZONE, PLACEMENT, PLACEMENT_SIZE, PLACEMENT_LABEL, ADVERTISER, CAMPAIGN, BANNER, BANNER_LABEL, TEMPLATE_ID, UNIVERSAL_AD_ID, CHANNEL, COUNTRY, COUNTRY_GROUP, ACTION, ATTRIBUTION_TYPE, ADVERTISER_OWNER, SITE_OWNER. Advanced report (statisticType=HADOOP) takes the same entity/country/channel/action dimensions except TEMPLATE_ID, ATTRIBUTION_TYPE and the owners, plus BROWSER, BROWSER_VERSION, OPERATING_SYSTEM, OS_VERSION, REFERER, APP_PACKAGE, SCREEN_SIZE, LOCATION, CUSTOM_PARAMETER, TOP_DOMAIN, DEVICE_RAM, PRICE_BAND, BROWSER_RANK, HARDWARE_RANK, PLATFORM_RANK and, depending on the analytics backend version, PLACEMENT_SIZE, CARRIER, CONNECTION_TYPE, LANGUAGE, DEVICE_VENDOR, DEVICE_MODEL, RISK_LEVEL, RISK_CATEGORY and similar device fields. Header Bidding report (statisticType=HEADER_BIDDING): FILL_SOURCE, COUNTRY, SITE, ZONE, PLACEMENT. Every dimension is also permission-gated; a value the user may not group by for the chosen report type fails the whole request with a 'forbidden' error. Group by date with groupRange, not here

SITE,COUNTRY

groupRange string

Time frame for grouping analytical data. Values: NONE, HOUR, DAY, WEEK, MONTH, YEAR, HOUR_24. Default: NONE

DAY

hadoopAppPackage string

Advanced report (statisticType=HADOOP) only: count only in-app requests whose app package / bundle id contains this text.

com.example.game

hadoopCustomParmName string

Advanced report (statisticType=HADOOP) only: count only requests carrying this custom parameter (the name the ad tag passes). Empty: any.

utm_source

hadoopCustomParmValue string

Advanced report (statisticType=HADOOP) only: with hadoopCustomParmName, count only requests where that custom parameter has this value.

newsletter

hadoopRefDomain string

Advanced report (statisticType=HADOOP) only: count only requests whose referrer URL contains this text.

news.example.com

hourFrom integer

Start hour filter (0-23). Only applicable when groupRange=HOUR

9

hourTo integer

End hour filter (0-23). Only applicable when groupRange=HOUR

18

jsonKeys string

Analytics report (/rest-api/analytics/{format}) in JSON, and a saved report mailed as JSON: how each row names its fields. name (default) — the column's display name in the user's interface language, e.g. "Impressions" or "Impressionen"; a name several columns share (the Base, Publisher and Advertiser Impressions, Clicks, CTR…) keeps its last occurrence and each earlier one is keyed by its column id, e.g. publisher_impressions. id — every field is keyed by its column id (impressions, publisher_impressions, sumGross): the same in every language and never repeated, so scripts should use it. Other formats and operations ignore it

id

limit integer

Maximum number of rows returned (for pagination). On the /rest-api/analytics/{format} report endpoints omitting it returns up to the network's records-per-request limit and a larger value is rejected; elsewhere the default is 50

100

offset integer

Number of result entries to skip (for pagination). Default: 0

0

range string

Time period for the report. Values: TODAY (default), YESTERDAY, CURRENT_WEEK, LAST_WEEK, LAST_2_WEEKS, CURRENT_MONTH, LAST_7_DAYS, LAST_30_DAYS, LAST_MONTH, LAST_3_MONTH, LAST_6_MONTH, CURRENT_YEAR, LAST_YEAR, CUSTOM. CUSTOM reads the period from customFrom/customTo

LAST_7_DAYS

reportsLayoutSettings array<string>

Metric column ids to output; only applied when useReportsLayoutSettings=true. These are internal column keys, not display names — 'gross' or 'revenue' match nothing, and an id that names no column of the report type is skipped (the report endpoints name it in the X-Ignored-Report-Columns response header). General report: impressions, clicks, ctr, requests and fill_rate (absent when grouping or filtering by advertiser/campaign/banner), conversions (also keeps the per-action columns), i2c, ccr, sumGross (Gross), sumNet (Net), sumMinimalNet, profit, apProfit, ecpmGross, ecpmNet, ecpmProfit, unique_visitors, confirmation_status, and the publisher_/advertiser_ variants such as publisher_impressions, publisher_sumNet (Revenue), advertiser_sumGross (Charges), advertiser_ecpmGross. Advanced report (HADOOP): requests, impressionsEligible, clicksEligible, ctrEffective, fillRate, sumGross, sumNet, profit, ecpmGross, ecpmNet, ecpmProfit and more. The complete list for the caller and report type is GET /rest-api/analytics/columns.do?statisticType=...

impressions,clicks,ctr,sumGross

splitByAttribution boolean

Adds a nested click-through / view-through pair under each conversion-action column. Only meaningful with splitColumnsBy=CONVERSION_ACTION; ignored otherwise.

true

splitColumnsBy string

The single dimension spread across report columns. Leave unset to keep the legacy shape, where breakdownByActions/breakdownByCustomParameter decide and the attribution columns are always present.

CONVERSION_ACTION

statisticType string

Report type. Omit it for the General report (the default): aggregated totals — impressions, clicks, CTR, conversions, gross, net, profit, eCPM, requests, fill rate — grouped by site/zone/placement, advertiser/campaign/banner, country, channel or action. HADOOP — the Advanced report, computed from the raw ad-server logs: adds ad requests, opportunities and device/browser/OS/referer/app/location dimensions; only when Hadoop analytics is configured on the network (legacy names HADOOP_ADREQUESTS, HADOOP_SECURITY and BROWSER_OS are read as HADOOP). IMPRESSIONS_LOG, CLICKS_LOG, CONVERSIONS_LOG, ACTIONS_LOG — one row per raw event instead of totals. TARGETING_COOKIE — cookie-targeting report. HEADER_BIDDING — the Header Bidding report: fills, unfilled requests, fill rate, gross and eCPM per fill source, needs the Header Bidding report permission

HADOOP

useReportsLayoutSettings boolean

When true, only the metric columns listed in reportsLayoutSettings are output (grouping and date columns always stay); the column layout saved in the UI is not applied. Default: false — every metric column the user has permission to see

true

usersTimeZoneId string

Time zone the Advanced report (statisticType=HADOOP) buckets its days and hours in, as a fixed UTC offset name: UTC_0, UTC_PLUS_1 ... UTC_PLUS_14, UTC_MINUS_1 ... UTC_MINUS_12, and the half-hour ones such as UTC_PLUS_5_30. A value that is not one of them counts as UTC. Other report types use the network's reporting time zone and ignore it. Default: UTC

UTC_PLUS_2

apiKey string

The user's API key. May instead be sent in the X-Api-Key header or as Authorization: Bearer <key>, like on every other /rest-api call

a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4

displayIds boolean

Show entity IDs alongside names in the report

true

showUnique boolean

Include unique visitor/click columns in advanced analytics

true

archive boolean

Zip the download: the response is export.<format>.zip holding export.<format>. It does not select older or archived data

true

Responses

200

Report in the requested format

400

A parameter failed validation: {success:false, errors:{field: message}}

401

Authentication failed: {success:false, rest_error}

403

The role lacks a reporting permission the request needs; the message names it

404

Not found — resource does not exist

429

The network's daily analytics request limit is reached

Language

cURL Request

curl --request POST \
  --url 'https://YOUR-NETWORK-DOMAIN/rest-api/analytics/CSV.do' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'statisticType=HADOOP' \
  --data-urlencode 'range=LAST_7_DAYS' \
  --data-urlencode 'groupBy=SITE,COUNTRY'

Python Request

import requests

response = requests.request("POST", "https://YOUR-NETWORK-DOMAIN/rest-api/analytics/CSV.do", headers={"X-Api-Key": "YOUR_API_KEY"}, data={"statisticType": "HADOOP", "range": "LAST_7_DAYS", "groupBy": "SITE,COUNTRY"})
print(response.json())

Node Request

const response = await fetch('https://YOUR-NETWORK-DOMAIN/rest-api/analytics/CSV.do', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({"statisticType":"HADOOP","range":"LAST_7_DAYS","groupBy":"SITE,COUNTRY"}),
});

console.log(await response.json());

Java Request

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://YOUR-NETWORK-DOMAIN/rest-api/analytics/CSV.do"))
    .header("X-Api-Key", "YOUR_API_KEY")
    .header("Content-Type", "application/x-www-form-urlencoded")
    .method("POST", HttpRequest.BodyPublishers.ofString("statisticType=HADOOP&range=LAST_7_DAYS&groupBy=SITE%2CCOUNTRY"))
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

C# Request

using var client = new HttpClient();

var request = new HttpRequestMessage(new HttpMethod("POST"), "https://YOUR-NETWORK-DOMAIN/rest-api/analytics/CSV.do");
request.Headers.Add("X-Api-Key", "YOUR_API_KEY");
request.Content = new FormUrlEncodedContent(new Dictionary<string, string> { ["statisticType"] = "HADOOP", ["range"] = "LAST_7_DAYS", ["groupBy"] = "SITE,COUNTRY" });

var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());

Go Request

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	req, _ := http.NewRequest("POST", "https://YOUR-NETWORK-DOMAIN/rest-api/analytics/CSV.do", strings.NewReader(`statisticType=HADOOP&range=LAST_7_DAYS&groupBy=SITE%2CCOUNTRY`))
	req.Header.Set("X-Api-Key", "YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()

	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}

PHP Request

<?php
$ch = curl_init("https://YOUR-NETWORK-DOMAIN/rest-api/analytics/CSV.do");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-Api-Key: YOUR_API_KEY", "Content-Type: application/x-www-form-urlencoded"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, 'statisticType=HADOOP&range=LAST_7_DAYS&groupBy=SITE%2CCOUNTRY');

echo curl_exec($ch);
curl_close($ch);

Ruby Request

require 'net/http'
require 'json'

uri = URI("https://YOUR-NETWORK-DOMAIN/rest-api/analytics/CSV.do")
request = Net::HTTP::Post.new(uri)
request['X-Api-Key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/x-www-form-urlencoded'
request.set_form_data('statisticType' => "HADOOP", 'range' => "LAST_7_DAYS", 'groupBy' => "SITE,COUNTRY")

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
puts response.body