Dashboard API endpoints
Endpoint reference for the Dashboard tag (6 endpoints): Dashboard API and reporting settings
Reference network manager admin
Dashboard API and reporting settings. 6 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.
POST /rest-api/dashboard/widget/create.do
Create widget.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
data.actionCustomParameterFragment | form | string | no | Custom parameter name fragment for filtering by custom parameter |
data.actionCustomValueFragment | form | string | no | Custom parameter value fragment for filtering by custom parameter |
data.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. |
data.breakdownByActions | form | boolean | no | When true, adds one conversions column per conversion action. Ignored when splitColumnsBy is set, which supersedes it |
data.breakdownByCustomParameter | form | boolean | no | When true, enables breakdown by custom parameter values |
data.customFrom | form | string | no | First day of the period (yyyy-MM-dd) when range=CUSTOM; ignored for every other range. Defaults to today |
data.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 |
data.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 |
data.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 |
data.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). |
data.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. |
data.hadoopAppPackage | form | string | no | Advanced report (statisticType=HADOOP) only: count only in-app requests whose app package / bundle id contains this text. |
data.hadoopCustomParmName | form | string | no | Advanced report (statisticType=HADOOP) only: count only requests carrying this custom parameter (the name the ad tag passes). Empty: any. |
data.hadoopCustomParmValue | form | string | no | Advanced report (statisticType=HADOOP) only: with hadoopCustomParmName, count only requests where that custom parameter has this value. |
data.hadoopRefDomain | form | string | no | Advanced report (statisticType=HADOOP) only: count only requests whose referrer URL contains this text. |
data.hourFrom | form | integer | no | Start hour filter (0-23). Only applicable when groupRange=HOUR |
data.hourTo | form | integer | no | End hour filter (0-23). Only applicable when groupRange=HOUR |
data.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. |
data.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 |
data.offset | form | integer | no | Number of result entries to skip (for pagination). Default: 0 |
data.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. |
data.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=… |
data.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. |
data.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. |
data.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. |
data.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 |
data.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 |
id | form | integer | no | Unique widget identifier |
title | form | string | no | Widget display title |
type | form | string | no | Widget visualization type: TABLE, LINE_CHART, PIE_CHART, BAR_CHART, or NOTICE Values: TABLE, LINE_CHART, PIE_CHART, BAR_CHART, NOTICE. |
value | form | string | no | Widget content value. For NOTICE type: the text content. For chart types: JSON-serialized analytics configuration |
x | form | integer | no | X-coordinate position on the dashboard grid (0-3) |
y | form | integer | no | Y-coordinate position on the dashboard grid (0-127) |
Responses: 200 — Widget created successfully. Errors follow the shared conventions.
POST /rest-api/dashboard/widget/delete.do
Delete widget.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | form | integer | yes | Unique numeric identifier of the widget to delete |
Responses: 200 — Widget deleted successfully. Errors follow the shared conventions.
POST /rest-api/dashboard/widget/update.do
Update widget.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | form | integer | yes | Unique numeric identifier of the widget to update |
data.actionCustomParameterFragment | form | string | no | Custom parameter name fragment for filtering by custom parameter |
data.actionCustomValueFragment | form | string | no | Custom parameter value fragment for filtering by custom parameter |
data.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. |
data.breakdownByActions | form | boolean | no | When true, adds one conversions column per conversion action. Ignored when splitColumnsBy is set, which supersedes it |
data.breakdownByCustomParameter | form | boolean | no | When true, enables breakdown by custom parameter values |
data.customFrom | form | string | no | First day of the period (yyyy-MM-dd) when range=CUSTOM; ignored for every other range. Defaults to today |
data.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 |
data.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 |
data.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 |
data.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). |
data.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. |
data.hadoopAppPackage | form | string | no | Advanced report (statisticType=HADOOP) only: count only in-app requests whose app package / bundle id contains this text. |
data.hadoopCustomParmName | form | string | no | Advanced report (statisticType=HADOOP) only: count only requests carrying this custom parameter (the name the ad tag passes). Empty: any. |
data.hadoopCustomParmValue | form | string | no | Advanced report (statisticType=HADOOP) only: with hadoopCustomParmName, count only requests where that custom parameter has this value. |
data.hadoopRefDomain | form | string | no | Advanced report (statisticType=HADOOP) only: count only requests whose referrer URL contains this text. |
data.hourFrom | form | integer | no | Start hour filter (0-23). Only applicable when groupRange=HOUR |
data.hourTo | form | integer | no | End hour filter (0-23). Only applicable when groupRange=HOUR |
data.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. |
data.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 |
data.offset | form | integer | no | Number of result entries to skip (for pagination). Default: 0 |
data.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. |
data.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=… |
data.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. |
data.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. |
data.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. |
data.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 |
data.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 |
title | form | string | no | Widget display title |
type | form | string | no | Widget visualization type: TABLE, LINE_CHART, PIE_CHART, BAR_CHART, or NOTICE Values: TABLE, LINE_CHART, PIE_CHART, BAR_CHART, NOTICE. |
value | form | string | no | Widget content value. For NOTICE type: the text content. For chart types: JSON-serialized analytics configuration |
x | form | integer | no | X-coordinate position on the dashboard grid (0-3) |
y | form | integer | no | Y-coordinate position on the dashboard grid (0-127) |
Responses: 200 — Widget updated successfully. Errors follow the shared conventions.
GET /rest-api/dashboard/widgets.do
Get dashboard widgets.
No parameters beyond authentication.
Responses: 200 — {success:true, widgets:[{id, title, displayTitle, type, x, y, value | data}]}. Errors follow the shared conventions.
GET /rest-api/self-serv/dashboard/{login}/{hash}/{timestamp}.do
Get self-serv dashboard analytics.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
login | path | string | yes | Username of the authenticated user in the Epom system used for login verification |
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 |
Note: the
{hash}and{timestamp}segments carry path-based hash authentication — see REST API overview.
Responses: 200 — Analytics data retrieved successfully · 404 — Not found — resource does not exist · 500 — Internal server error. Errors follow the shared conventions.
POST /rest-api/self-serv/dashboard/{login}/{hash}/{timestamp}.do
Get self-serv dashboard analytics.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
login | path | string | yes | Username of the authenticated user in the Epom system used for login verification |
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 |
Note: the
{hash}and{timestamp}segments carry path-based hash authentication — see REST API overview.
Responses: 200 — Analytics data retrieved successfully · 404 — Not found — resource does not exist · 500 — Internal server error. Errors follow the shared conventions.
Related
- REST API overview — authentication and conventions
- API endpoint reference by tag
- Analytics reports via API
