---
title: "Dashboard API endpoints"
description: "Endpoint reference for the Dashboard tag (6 endpoints): Dashboard API and reporting settings"
type: "reference"
audience: [network-manager, admin]
keywords: [api, rest, endpoints, dashboard]
---

Fetch the complete documentation index at: https://epom.com/ad-server/docs/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.

# Dashboard API endpoints

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](https://epom.com/ad-server/docs/api.md). Parameters marked `form` go in an `application/x-www-form-urlencoded` request body.

### POST /rest-api/dashboard/widget/create.do

[Request examples](https://epom.com/ad-server/docs/api/dashboard/post-dashboard-widget-create.md)

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](https://epom.com/ad-server/docs/api.md#error-codes).

### POST /rest-api/dashboard/widget/delete.do

[Request examples](https://epom.com/ad-server/docs/api/dashboard/post-dashboard-widget-delete.md)

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](https://epom.com/ad-server/docs/api.md#error-codes).

### POST /rest-api/dashboard/widget/update.do

[Request examples](https://epom.com/ad-server/docs/api/dashboard/post-dashboard-widget-update.md)

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](https://epom.com/ad-server/docs/api.md#error-codes).

### GET /rest-api/dashboard/widgets.do

[Request examples](https://epom.com/ad-server/docs/api/dashboard/get-dashboard-widgets.md)

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](https://epom.com/ad-server/docs/api.md#error-codes).

### GET /rest-api/self-serv/dashboard/{login}/{hash}/{timestamp}.do

[Request examples](https://epom.com/ad-server/docs/api/dashboard/get-self-serv-dashboard.md)

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](https://epom.com/ad-server/docs/api.md#authentication).

**Responses:** `200` — Analytics data retrieved successfully · `404` — Not found — resource does not exist · `500` — Internal server error. Errors follow the [shared conventions](https://epom.com/ad-server/docs/api.md#error-codes).

### POST /rest-api/self-serv/dashboard/{login}/{hash}/{timestamp}.do

[Request examples](https://epom.com/ad-server/docs/api/dashboard/post-self-serv-dashboard.md)

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](https://epom.com/ad-server/docs/api.md#authentication).

**Responses:** `200` — Analytics data retrieved successfully · `404` — Not found — resource does not exist · `500` — Internal server error. Errors follow the [shared conventions](https://epom.com/ad-server/docs/api.md#error-codes).

## Related

- [REST API overview](https://epom.com/ad-server/docs/api.md) — authentication and conventions
- [API endpoint reference by tag](https://epom.com/ad-server/docs/api/endpoints.md)
- [Analytics reports via API](https://epom.com/ad-server/docs/api/analytics-api.md)

<!-- Generated from the OpenAPI spec. Do not edit by hand. -->