Analytics API endpoints
Endpoint reference for the Analytics tag (19 endpoints): Reporting and analytics data retrieval
Reference network manager admin
Reporting and analytics data retrieval. 19 endpoints, generated from the OpenAPI spec. Authentication, the response envelope, pagination and error codes are shared by all endpoints — see REST API overview. Parameters marked form go in an application/x-www-form-urlencoded request body.
GET /rest-api/analytics/{format}.do
Get statistics report — impressions, clicks, CTR, revenue by date, country or entity (API key auth).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
format | path | string | yes | Output format: JSON, CSV, PDF, XLSX, or HTML Values: CSV, XLSX, PDF, HTML, JSON. |
actionCustomParameterFragment | query | string | no | Custom parameter name fragment for filtering by custom parameter |
actionCustomValueFragment | query | string | no | Custom parameter value fragment for filtering by custom parameter |
actionIds | query | array<integer> | no | 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. |
breakdownByActions | query | boolean | no | When true, adds one conversions column per conversion action. Ignored when splitColumnsBy is set, which supersedes it |
breakdownByCustomParameter | query | boolean | no | When true, enables breakdown by custom parameter values |
customFrom | query | string | no | First day of the period (yyyy-MM-dd) when range=CUSTOM; ignored for every other range. Defaults to today |
customTo | query | string | no | 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 |
eqLong | query | object | no | 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 |
eqStr | query | object | no | 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 |
groupBy | query | array<string> | no | 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 Values: 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 … (+43 more, 68 total). |
groupRange | query | string | no | Time frame for grouping analytical data. Values: NONE, HOUR, DAY, WEEK, MONTH, YEAR, HOUR_24. Default: NONE Values: NONE, HOUR, DAY, WEEK, MONTH, YEAR, HOUR_24. |
hadoopAppPackage | query | string | no | Advanced report (statisticType=HADOOP) only: count only in-app requests whose app package / bundle id contains this text. |
hadoopCustomParmName | query | string | no | Advanced report (statisticType=HADOOP) only: count only requests carrying this custom parameter (the name the ad tag passes). Empty: any. |
hadoopCustomParmValue | query | string | no | Advanced report (statisticType=HADOOP) only: with hadoopCustomParmName, count only requests where that custom parameter has this value. |
hadoopRefDomain | query | string | no | Advanced report (statisticType=HADOOP) only: count only requests whose referrer URL contains this text. |
hourFrom | query | integer | no | Start hour filter (0-23). Only applicable when groupRange=HOUR |
hourTo | query | integer | no | End hour filter (0-23). Only applicable when groupRange=HOUR |
jsonKeys | query | string | no | 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 Values: name, id. |
limit | query | integer | no | 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 |
offset | query | integer | no | Number of result entries to skip (for pagination). Default: 0 |
range | query | string | no | 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 Values: TODAY, 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. |
reportsLayoutSettings | query | array<string> | no | 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=… |
splitByAttribution | query | boolean | no | Adds a nested click-through / view-through pair under each conversion-action column. Only meaningful with splitColumnsBy=CONVERSION_ACTION; ignored otherwise. |
splitColumnsBy | query | string | no | 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. Values: NONE, CONVERSION_ACTION, CUSTOM_PARAMETER, ATTRIBUTION_TYPE. |
statisticType | query | string | no | 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 Values: TARGETING_COOKIE, CLICKS_LOG, HADOOP, CONVERSIONS_LOG, IMPRESSIONS_LOG, ACTIONS_LOG, HEADER_BIDDING. |
useReportsLayoutSettings | query | boolean | no | 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 |
usersTimeZoneId | query | string | no | 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 |
apiKey | query | string | no | 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 |
displayIds | query | boolean | no | Show entity IDs alongside names in the report |
showUnique | query | boolean | no | Include unique visitor/click columns in advanced analytics |
archive | query | boolean | no | Zip the download: the response is export.<format>.zip holding export.<format>. It does not select older or archived data |
Responses: 200 — Report in the requested format · 404 — Not found — resource does not exist · 429 — The network’s daily analytics request limit is reached. Errors follow the shared conventions.
POST /rest-api/analytics/{format}.do
Get statistics report — impressions, clicks, CTR, revenue by date, country or entity (API key auth).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
format | path | string | yes | Output format: JSON, CSV, PDF, XLSX, or HTML Values: CSV, XLSX, PDF, HTML, JSON. |
actionCustomParameterFragment | form | string | no | Custom parameter name fragment for filtering by custom parameter |
actionCustomValueFragment | form | string | no | Custom parameter value fragment for filtering by custom parameter |
actionIds | form | array<integer> | no | 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. |
breakdownByActions | form | boolean | no | When true, adds one conversions column per conversion action. Ignored when splitColumnsBy is set, which supersedes it |
breakdownByCustomParameter | form | boolean | no | When true, enables breakdown by custom parameter values |
customFrom | form | string | no | First day of the period (yyyy-MM-dd) when range=CUSTOM; ignored for every other range. Defaults to today |
customTo | form | string | no | 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 |
eqLong | form | object | no | 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 |
eqStr | form | object | no | 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 |
groupBy | form | array<string> | no | 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 Values: 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 … (+43 more, 68 total). |
groupRange | form | string | no | Time frame for grouping analytical data. Values: NONE, HOUR, DAY, WEEK, MONTH, YEAR, HOUR_24. Default: NONE Values: NONE, HOUR, DAY, WEEK, MONTH, YEAR, HOUR_24. |
hadoopAppPackage | form | string | no | Advanced report (statisticType=HADOOP) only: count only in-app requests whose app package / bundle id contains this text. |
hadoopCustomParmName | form | string | no | Advanced report (statisticType=HADOOP) only: count only requests carrying this custom parameter (the name the ad tag passes). Empty: any. |
hadoopCustomParmValue | form | string | no | Advanced report (statisticType=HADOOP) only: with hadoopCustomParmName, count only requests where that custom parameter has this value. |
hadoopRefDomain | form | string | no | Advanced report (statisticType=HADOOP) only: count only requests whose referrer URL contains this text. |
hourFrom | form | integer | no | Start hour filter (0-23). Only applicable when groupRange=HOUR |
hourTo | form | integer | no | End hour filter (0-23). Only applicable when groupRange=HOUR |
jsonKeys | form | string | no | 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 Values: name, id. |
limit | form | integer | no | 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 |
offset | form | integer | no | Number of result entries to skip (for pagination). Default: 0 |
range | form | string | no | 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 Values: TODAY, 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. |
reportsLayoutSettings | form | array<string> | no | 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=… |
splitByAttribution | form | boolean | no | Adds a nested click-through / view-through pair under each conversion-action column. Only meaningful with splitColumnsBy=CONVERSION_ACTION; ignored otherwise. |
splitColumnsBy | form | string | no | 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. Values: NONE, CONVERSION_ACTION, CUSTOM_PARAMETER, ATTRIBUTION_TYPE. |
statisticType | form | string | no | 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 Values: TARGETING_COOKIE, CLICKS_LOG, HADOOP, CONVERSIONS_LOG, IMPRESSIONS_LOG, ACTIONS_LOG, HEADER_BIDDING. |
useReportsLayoutSettings | form | boolean | no | 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 |
usersTimeZoneId | form | string | no | 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 |
apiKey | form | string | no | 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 |
displayIds | form | boolean | no | Show entity IDs alongside names in the report |
showUnique | form | boolean | no | Include unique visitor/click columns in advanced analytics |
archive | form | boolean | no | Zip the download: the response is export.<format>.zip holding export.<format>. It does not select older or archived data |
Responses: 200 — Report in the requested format · 404 — Not found — resource does not exist · 429 — The network’s daily analytics request limit is reached. Errors follow the shared conventions.
GET /rest-api/analytics/{format}/{login}/{hash}/{timestamp}.do
Get statistics report — impressions, clicks, CTR, revenue by date, country or entity (login/hash auth).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
format | path | string | yes | Output format: JSON, CSV, PDF, XLSX, or HTML Values: CSV, XLSX, PDF, HTML, JSON. |
login | path | string | yes | Username of the requesting user |
actionCustomParameterFragment | query | string | no | Custom parameter name fragment for filtering by custom parameter |
actionCustomValueFragment | query | string | no | Custom parameter value fragment for filtering by custom parameter |
actionIds | query | array<integer> | no | 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. |
breakdownByActions | query | boolean | no | When true, adds one conversions column per conversion action. Ignored when splitColumnsBy is set, which supersedes it |
breakdownByCustomParameter | query | boolean | no | When true, enables breakdown by custom parameter values |
customFrom | query | string | no | First day of the period (yyyy-MM-dd) when range=CUSTOM; ignored for every other range. Defaults to today |
customTo | query | string | no | 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 |
eqLong | query | object | no | 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 |
eqStr | query | object | no | 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 |
groupBy | query | array<string> | no | 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 Values: 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 … (+43 more, 68 total). |
groupRange | query | string | no | Time frame for grouping analytical data. Values: NONE, HOUR, DAY, WEEK, MONTH, YEAR, HOUR_24. Default: NONE Values: NONE, HOUR, DAY, WEEK, MONTH, YEAR, HOUR_24. |
hadoopAppPackage | query | string | no | Advanced report (statisticType=HADOOP) only: count only in-app requests whose app package / bundle id contains this text. |
hadoopCustomParmName | query | string | no | Advanced report (statisticType=HADOOP) only: count only requests carrying this custom parameter (the name the ad tag passes). Empty: any. |
hadoopCustomParmValue | query | string | no | Advanced report (statisticType=HADOOP) only: with hadoopCustomParmName, count only requests where that custom parameter has this value. |
hadoopRefDomain | query | string | no | Advanced report (statisticType=HADOOP) only: count only requests whose referrer URL contains this text. |
hourFrom | query | integer | no | Start hour filter (0-23). Only applicable when groupRange=HOUR |
hourTo | query | integer | no | End hour filter (0-23). Only applicable when groupRange=HOUR |
jsonKeys | query | string | no | 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 Values: name, id. |
limit | query | integer | no | 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 |
offset | query | integer | no | Number of result entries to skip (for pagination). Default: 0 |
range | query | string | no | 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 Values: TODAY, 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. |
reportsLayoutSettings | query | array<string> | no | 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=… |
splitByAttribution | query | boolean | no | Adds a nested click-through / view-through pair under each conversion-action column. Only meaningful with splitColumnsBy=CONVERSION_ACTION; ignored otherwise. |
splitColumnsBy | query | string | no | 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. Values: NONE, CONVERSION_ACTION, CUSTOM_PARAMETER, ATTRIBUTION_TYPE. |
statisticType | query | string | no | 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 Values: TARGETING_COOKIE, CLICKS_LOG, HADOOP, CONVERSIONS_LOG, IMPRESSIONS_LOG, ACTIONS_LOG, HEADER_BIDDING. |
useReportsLayoutSettings | query | boolean | no | 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 |
usersTimeZoneId | query | string | no | 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 |
displayIds | query | boolean | no | Show entity IDs alongside names in the report |
showUnique | query | boolean | no | Include unique visitor/click columns in advanced analytics |
archive | query | boolean | no | Zip the download: the response is export.<format>.zip holding export.<format>. It does not select older or archived data |
Note: the
{hash}and{timestamp}segments carry path-based hash authentication — see REST API overview.
Responses: 200 — Report in the requested format · 404 — Not found — resource does not exist · 429 — The network’s daily analytics request limit is reached. Errors follow the shared conventions.
POST /rest-api/analytics/{format}/{login}/{hash}/{timestamp}.do
Get statistics report — impressions, clicks, CTR, revenue by date, country or entity (login/hash auth).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
format | path | string | yes | Output format: JSON, CSV, PDF, XLSX, or HTML Values: CSV, XLSX, PDF, HTML, JSON. |
login | path | string | yes | Username of the requesting user |
actionCustomParameterFragment | form | string | no | Custom parameter name fragment for filtering by custom parameter |
actionCustomValueFragment | form | string | no | Custom parameter value fragment for filtering by custom parameter |
actionIds | form | array<integer> | no | 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. |
breakdownByActions | form | boolean | no | When true, adds one conversions column per conversion action. Ignored when splitColumnsBy is set, which supersedes it |
breakdownByCustomParameter | form | boolean | no | When true, enables breakdown by custom parameter values |
customFrom | form | string | no | First day of the period (yyyy-MM-dd) when range=CUSTOM; ignored for every other range. Defaults to today |
customTo | form | string | no | 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 |
eqLong | form | object | no | 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 |
eqStr | form | object | no | 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 |
groupBy | form | array<string> | no | 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 Values: 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 … (+43 more, 68 total). |
groupRange | form | string | no | Time frame for grouping analytical data. Values: NONE, HOUR, DAY, WEEK, MONTH, YEAR, HOUR_24. Default: NONE Values: NONE, HOUR, DAY, WEEK, MONTH, YEAR, HOUR_24. |
hadoopAppPackage | form | string | no | Advanced report (statisticType=HADOOP) only: count only in-app requests whose app package / bundle id contains this text. |
hadoopCustomParmName | form | string | no | Advanced report (statisticType=HADOOP) only: count only requests carrying this custom parameter (the name the ad tag passes). Empty: any. |
hadoopCustomParmValue | form | string | no | Advanced report (statisticType=HADOOP) only: with hadoopCustomParmName, count only requests where that custom parameter has this value. |
hadoopRefDomain | form | string | no | Advanced report (statisticType=HADOOP) only: count only requests whose referrer URL contains this text. |
hourFrom | form | integer | no | Start hour filter (0-23). Only applicable when groupRange=HOUR |
hourTo | form | integer | no | End hour filter (0-23). Only applicable when groupRange=HOUR |
jsonKeys | form | string | no | 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 Values: name, id. |
limit | form | integer | no | 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 |
offset | form | integer | no | Number of result entries to skip (for pagination). Default: 0 |
range | form | string | no | 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 Values: TODAY, 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. |
reportsLayoutSettings | form | array<string> | no | 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=… |
splitByAttribution | form | boolean | no | Adds a nested click-through / view-through pair under each conversion-action column. Only meaningful with splitColumnsBy=CONVERSION_ACTION; ignored otherwise. |
splitColumnsBy | form | string | no | 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. Values: NONE, CONVERSION_ACTION, CUSTOM_PARAMETER, ATTRIBUTION_TYPE. |
statisticType | form | string | no | 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 Values: TARGETING_COOKIE, CLICKS_LOG, HADOOP, CONVERSIONS_LOG, IMPRESSIONS_LOG, ACTIONS_LOG, HEADER_BIDDING. |
useReportsLayoutSettings | form | boolean | no | 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 |
usersTimeZoneId | form | string | no | 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 |
displayIds | form | boolean | no | Show entity IDs alongside names in the report |
showUnique | form | boolean | no | Include unique visitor/click columns in advanced analytics |
archive | form | boolean | no | Zip the download: the response is export.<format>.zip holding export.<format>. It does not select older or archived data |
Note: the
{hash}and{timestamp}segments carry path-based hash authentication — see REST API overview.
Responses: 200 — Report in the requested format · 404 — Not found — resource does not exist · 429 — The network’s daily analytics request limit is reached. Errors follow the shared conventions.
GET /rest-api/analytics/columns.do
List the report metric columns you may use.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
statisticType | query | string | no | Report type; omitted means the General report. E.g. HADOOP for the Advanced report Values: TARGETING_COOKIE, CLICKS_LOG, HADOOP, CONVERSIONS_LOG, IMPRESSIONS_LOG, ACTIONS_LOG, HEADER_BIDDING. |
Responses: 200 — {statisticType, columns:[{id, name, group, groupName}]}. Errors follow the shared conventions.
GET /rest-api/analytics/raw-log-analyze.do
Analyse raw event logs — counts by value, distinct visitors, sample rows, clicks without impressions.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
logType | query | string | yes | IMPRESSIONS, CLICKS, CONVERSIONS or ACTIONS |
from | query | string | yes | First day, yyyy-MM-dd, server time zone |
to | query | string | no | Last day, yyyy-MM-dd, inclusive; default from; at most 3 days from from |
advertiserIds | query | array<integer> | no | Advertiser ids to keep (ORed with campaigns and banners, as in the raw-log reports) |
campaignIds | query | array<integer> | no | Campaign ids to keep |
bannerIds | query | array<integer> | no | Banner ids to keep |
siteIds | query | array<integer> | no | Site ids to keep (ORed with zones and placements) |
zoneIds | query | array<integer> | no | Zone ids to keep |
placementIds | query | array<integer> | no | Placement ids to keep |
countries | query | array<string> | no | Countries to keep, two-letter codes |
connectionTypes | query | array<string> | no | Connection types to keep (needs RPT_GRP_FILTER_CONNECTION_TYPE) |
languages | query | array<string> | no | Browser languages to keep (needs RPT_GRP_FILTER_LANGUAGE) |
trafficSources | query | array<string> | no | Traffic sources to keep (needs RPT_GRP_FILTER_TRAFFIC_SOURCE) |
incognito | query | string | no | Incognito filter: true, false or unknown (needs RPT_GRP_FILTER_INCOGNITO_MODE) |
validation | query | string | no | VALID (default), NOT_VALID or ALL records - only networks that write invalid records keep NOT_VALID ones |
groupBy | query | array<string> | no | One or two columns to count rows by: a raw-log column (domain, ip, uuid, user_agent, country, deviceFormat, os, browser, banner_id, placement_id…), day, hour, an entity name (banner_name…), or custom_param.<name> for one custom parameter’s values |
top | query | integer | no | Groups listed, most rows first; default 20, at most 100 |
sample | query | integer | no | Sample rows returned; default 10, at most 50, 0 for none |
columns | query | array<string> | no | Columns of the sample rows; default dt, banner_id, placement_id, domain, ip, country, deviceFormat, user_agent, custom_param, transaction_id and the groupBy columns |
link | query | boolean | no | Match clicks to impressions, or conversions and actions to clicks, by transaction id; reads the other log too (up to 50000 rows) |
Responses: 200 — {success, logType, from, to, rowsRead, matchingRows, capped, rowCap, groupBy, groups:[{<column>: value, count, share}], other:{groups, rows}|null, distinctGroups, distinct:{ip, uuid, user_agent, domain}, sampleColumns, sample:[{…}], linkedTo:{log, key, matched, unmatched, withoutId, linkedRowsRead, linkedCapped, unmatchedByAttribution?, unmatchedSample}|{log, skipped}, notes:[…]} · 429 — The network’s daily analytics request limit is reached · 503 — The raw logs could not be read from the analytics cluster. Errors follow the shared conventions.
GET /rest-api/analytics/report-check.do
Check why a report comes back empty.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
from | query | string | yes | First day of the report, yyyy-MM-dd |
reportType | query | string | no | GENERAL (default) or ADVANCED (also HADOOP) |
to | query | string | no | Last day of the report, yyyy-MM-dd, inclusive; default from |
groupRange | query | string | no | Time breakdown: NONE (default), HOUR, DAY, WEEK, MONTH or YEAR |
groupBy | query | array<string> | no | Groupings, as the report names them (CAMPAIGN, COUNTRY, DEVICE_FORMAT…) |
advertiserIds | query | array<integer> | no | Advertiser ids the report was filtered to |
campaignIds | query | array<integer> | no | Campaign ids the report was filtered to |
bannerIds | query | array<integer> | no | Banner ids the report was filtered to |
siteIds | query | array<integer> | no | Site ids the report was filtered to |
zoneIds | query | array<integer> | no | Zone ids the report was filtered to |
placementIds | query | array<integer> | no | Placement ids the report was filtered to |
countries | query | array<string> | no | Countries the report was filtered to, two-letter codes |
deviceFormats | query | array<string> | no | Advanced report only — device formats it was filtered to (MOBILE, DESKTOP…) |
connectionTypes | query | array<string> | no | Advanced report only — connection types it was filtered to |
languages | query | array<string> | no | Advanced report only — browser languages it was filtered to |
incognito | query | string | no | Advanced report only — incognito filter: true, false or unknown |
Responses: 200 — {success, reportType, from, to, decisive:{check, reason, fix}|null, findings:[{check, decisive, reason, fix}]}; check is one of FUTURE, PERMISSION, RETENTION, ENTITY, CONTRADICTION, ADVANCED_DATA, NOT_FLUSHED, COLUMNS, GROUPING, PROVISIONAL. Errors follow the shared conventions.
GET /rest-api/analytics/reports-layout-settings/{login}/{hash}/{timestamp}.do
Get user reporting settings.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
login | path | string | yes | Username of the requesting user |
statsType | query | string | no | Statistic type to get reporting settings for (e.g. IMPRESSIONS_LOG, CLICKS_LOG, CONVERSIONS_LOG, TARGETING_COOKIE) Values: TARGETING_COOKIE, CLICKS_LOG, HADOOP, CONVERSIONS_LOG, IMPRESSIONS_LOG, ACTIONS_LOG, HEADER_BIDDING. |
Note: the
{hash}and{timestamp}segments carry path-based hash authentication — see REST API overview.
Responses: 200 — Reporting layout settings with all and selected columns · 404 — Not found — resource does not exist. Errors follow the shared conventions.
POST /rest-api/analytics/reports-layout-settings/{login}/{hash}/{timestamp}.do
Get user reporting settings.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
login | path | string | yes | Username of the requesting user |
statsType | form | string | no | Statistic type to get reporting settings for (e.g. IMPRESSIONS_LOG, CLICKS_LOG, CONVERSIONS_LOG, TARGETING_COOKIE) Values: TARGETING_COOKIE, CLICKS_LOG, HADOOP, CONVERSIONS_LOG, IMPRESSIONS_LOG, ACTIONS_LOG, HEADER_BIDDING. |
Note: the
{hash}and{timestamp}segments carry path-based hash authentication — see REST API overview.
Responses: 200 — Reporting layout settings with all and selected columns · 404 — Not found — resource does not exist. Errors follow the shared conventions.
GET /rest-api/rtb/dsp-analytics/search.do
DSP endpoint traffic and spend.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
from | query | string | yes | First day of the range, inclusive |
to | query | string | yes | Last day of the range, inclusive |
groupBy | query | string | no | Comma-separated dimensions to break the rows down by: date, dspPartnerName, placementId, countryCode. Empty means one total row. |
sort | query | string | no | Column to sort on — any dimension listed in groupBy, or one of requests, bids, wins, impressions, spend |
dir | query | string | no | Sort direction |
start | query | integer | no | Row offset for paging |
limit | query | integer | no | Maximum rows to return, up to 10000 |
Responses: 200 — Analytics rows retrieved successfully. Errors follow the shared conventions.
GET /rest-api/saved-reports.do
List your saved reports.
No parameters beyond authentication.
Responses: 200 — ‘reports’ lists {id, title, scheduled, schedule:[{dayOfWeek or dayOfMonth, hour, format}], recipients:[e-mail]}. Errors follow the shared conventions.
POST /rest-api/saved-reports.do
Save a report.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
title | form | string | yes | Report title, up to 256 characters |
actionCustomParameterFragment | form | string | no | Custom parameter name fragment for filtering by custom parameter |
actionCustomValueFragment | form | string | no | Custom parameter value fragment for filtering by custom parameter |
actionIds | form | array<integer> | no | 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. |
breakdownByActions | form | boolean | no | When true, adds one conversions column per conversion action. Ignored when splitColumnsBy is set, which supersedes it |
breakdownByCustomParameter | form | boolean | no | When true, enables breakdown by custom parameter values |
customFrom | form | string | no | First day of the period (yyyy-MM-dd) when range=CUSTOM; ignored for every other range. Defaults to today |
customTo | form | string | no | 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 |
eqLong | form | object | no | 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 |
eqStr | form | object | no | 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 |
groupBy | form | array<string> | no | 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 Values: 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 … (+43 more, 68 total). |
groupRange | form | string | no | Time frame for grouping analytical data. Values: NONE, HOUR, DAY, WEEK, MONTH, YEAR, HOUR_24. Default: NONE Values: NONE, HOUR, DAY, WEEK, MONTH, YEAR, HOUR_24. |
hadoopAppPackage | form | string | no | Advanced report (statisticType=HADOOP) only: count only in-app requests whose app package / bundle id contains this text. |
hadoopCustomParmName | form | string | no | Advanced report (statisticType=HADOOP) only: count only requests carrying this custom parameter (the name the ad tag passes). Empty: any. |
hadoopCustomParmValue | form | string | no | Advanced report (statisticType=HADOOP) only: with hadoopCustomParmName, count only requests where that custom parameter has this value. |
hadoopRefDomain | form | string | no | Advanced report (statisticType=HADOOP) only: count only requests whose referrer URL contains this text. |
hourFrom | form | integer | no | Start hour filter (0-23). Only applicable when groupRange=HOUR |
hourTo | form | integer | no | End hour filter (0-23). Only applicable when groupRange=HOUR |
jsonKeys | form | string | no | 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 Values: name, id. |
limit | form | integer | no | 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 |
offset | form | integer | no | Number of result entries to skip (for pagination). Default: 0 |
range | form | string | no | 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 Values: TODAY, 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. |
reportsLayoutSettings | form | array<string> | no | 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=… |
splitByAttribution | form | boolean | no | Adds a nested click-through / view-through pair under each conversion-action column. Only meaningful with splitColumnsBy=CONVERSION_ACTION; ignored otherwise. |
splitColumnsBy | form | string | no | 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. Values: NONE, CONVERSION_ACTION, CUSTOM_PARAMETER, ATTRIBUTION_TYPE. |
statisticType | form | string | no | 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 Values: TARGETING_COOKIE, CLICKS_LOG, HADOOP, CONVERSIONS_LOG, IMPRESSIONS_LOG, ACTIONS_LOG, HEADER_BIDDING. |
useReportsLayoutSettings | form | boolean | no | 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 |
usersTimeZoneId | form | string | no | 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 |
Responses: 200 — The saved report, in the shape of the GET. Errors follow the shared conventions.
GET /rest-api/saved-reports/{id}.do
Read a saved report.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes | Saved report id |
Responses: 200 — {id, title, scheduled, schedule, recipients, params} · 404 — No saved report of the caller has this id. Errors follow the shared conventions.
POST /rest-api/saved-reports/{id}.do
Change a saved report.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes | Saved report id |
title | form | string | no | New report title, up to 256 characters; omit to keep the current one |
actionCustomParameterFragment | form | string | no | Custom parameter name fragment for filtering by custom parameter |
actionCustomValueFragment | form | string | no | Custom parameter value fragment for filtering by custom parameter |
actionIds | form | array<integer> | no | 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. |
breakdownByActions | form | boolean | no | When true, adds one conversions column per conversion action. Ignored when splitColumnsBy is set, which supersedes it |
breakdownByCustomParameter | form | boolean | no | When true, enables breakdown by custom parameter values |
customFrom | form | string | no | First day of the period (yyyy-MM-dd) when range=CUSTOM; ignored for every other range. Defaults to today |
customTo | form | string | no | 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 |
eqLong | form | object | no | 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 |
eqStr | form | object | no | 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 |
groupBy | form | array<string> | no | 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 Values: 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 … (+43 more, 68 total). |
groupRange | form | string | no | Time frame for grouping analytical data. Values: NONE, HOUR, DAY, WEEK, MONTH, YEAR, HOUR_24. Default: NONE Values: NONE, HOUR, DAY, WEEK, MONTH, YEAR, HOUR_24. |
hadoopAppPackage | form | string | no | Advanced report (statisticType=HADOOP) only: count only in-app requests whose app package / bundle id contains this text. |
hadoopCustomParmName | form | string | no | Advanced report (statisticType=HADOOP) only: count only requests carrying this custom parameter (the name the ad tag passes). Empty: any. |
hadoopCustomParmValue | form | string | no | Advanced report (statisticType=HADOOP) only: with hadoopCustomParmName, count only requests where that custom parameter has this value. |
hadoopRefDomain | form | string | no | Advanced report (statisticType=HADOOP) only: count only requests whose referrer URL contains this text. |
hourFrom | form | integer | no | Start hour filter (0-23). Only applicable when groupRange=HOUR |
hourTo | form | integer | no | End hour filter (0-23). Only applicable when groupRange=HOUR |
jsonKeys | form | string | no | 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 Values: name, id. |
limit | form | integer | no | 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 |
offset | form | integer | no | Number of result entries to skip (for pagination). Default: 0 |
range | form | string | no | 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 Values: TODAY, 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. |
reportsLayoutSettings | form | array<string> | no | 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=… |
splitByAttribution | form | boolean | no | Adds a nested click-through / view-through pair under each conversion-action column. Only meaningful with splitColumnsBy=CONVERSION_ACTION; ignored otherwise. |
splitColumnsBy | form | string | no | 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. Values: NONE, CONVERSION_ACTION, CUSTOM_PARAMETER, ATTRIBUTION_TYPE. |
statisticType | form | string | no | 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 Values: TARGETING_COOKIE, CLICKS_LOG, HADOOP, CONVERSIONS_LOG, IMPRESSIONS_LOG, ACTIONS_LOG, HEADER_BIDDING. |
useReportsLayoutSettings | form | boolean | no | 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 |
usersTimeZoneId | form | string | no | 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 |
Responses: 200 — The saved report, in the shape of the GET · 404 — No saved report of the caller has this id. Errors follow the shared conventions.
DELETE /rest-api/saved-reports/{id}.do
Delete a saved report.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes | Saved report id |
Responses: 200 — Deleted · 404 — No saved report of the caller has this id. Errors follow the shared conventions.
POST /rest-api/saved-reports/{id}/recipients.do
Add a recipient to a saved report’s e-mails.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes | Saved report id |
email | form | string | no | E-mail address |
Responses: 200 — The saved report with its recipients, in the shape of the GET · 404 — No saved report of the caller has this id. Errors follow the shared conventions.
DELETE /rest-api/saved-reports/{id}/recipients.do
Remove recipients from a saved report’s e-mails.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes | Saved report id |
email | form | string | no | E-mail address |
Responses: 200 — The saved report with its recipients, in the shape of the GET · 404 — No saved report of the caller has this id, or the email is not one of its recipients. Errors follow the shared conventions.
POST /rest-api/saved-reports/{id}/schedule.do
Schedule a saved report’s e-mail.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes | Saved report id |
format | form | string | yes | File format mailed Values: CSV, XLSX, PDF, HTML, JSON. |
hour | form | integer | yes | Hour of the day in UTC, 0-23 |
daysOfTheMonth | form | array<integer> | no | Days of the month, 1-31 |
daysOfTheWeek | form | array<string> | no | Days of the week, e.g. MONDAY,FRIDAY Values: MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY. |
Responses: 200 — The saved report with its schedule, in the shape of the GET · 404 — No saved report of the caller has this id. Errors follow the shared conventions.
DELETE /rest-api/saved-reports/{id}/schedule.do
Remove a saved report’s e-mail slots.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | integer | yes | Saved report id |
daysOfTheMonth | form | array<integer> | no | Days of the month, 1-31 |
daysOfTheWeek | form | array<string> | no | Days of the week, e.g. MONDAY,FRIDAY Values: MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY. |
format | form | string | no | File format mailed; required when adding slots Values: CSV, XLSX, PDF, HTML, JSON. |
hour | form | integer | no | Hour of the day in UTC, 0-23; required when adding slots, and when removing given days |
Responses: 200 — The saved report with its schedule, in the shape of the GET · 404 — No saved report of the caller has this id, or none of the slots sent is scheduled. Errors follow the shared conventions.
Related
- REST API overview — authentication and conventions
- API endpoint reference by tag
- Analytics reports via API
