Get self-serv dashboard analytics — get
Retrieves summary analytics data for the self-serv dashboard, including top-level KPI widgets and chart data for the requested time period.
https://YOUR-NETWORK-DOMAIN/rest-api/self-serv/dashboard/{login}/{hash}/{timestamp}.do Retrieves summary analytics data for the self-serv dashboard, including top-level KPI widgets and chart data for the requested time period. The response compares the current period metrics (impressions, clicks, revenue, conversions, fill rates, CTR, eCPM, etc.) against the equivalent previous period, providing percentage change for each metric. Analytics can be filtered and grouped using optional query parameters such as range, groupRange, groupBy, eqStr, and eqLong. Authentication is performed via path-based login/hash/timestamp credentials. The response is written directly to the output stream as a JSON object with 'top' (summary widgets array) and 'chart' (detailed chart data) keys.
Path Params
login string required
Username of the authenticated user in the Epom system used for login verification
john.doe hash string required
Authentication hash: hex MD5(MD5(password) + timestamp), 32 characters
a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 timestamp integer required
Current UNIX timestamp in milliseconds used for authentication hash generation and request freshness validation (13 digits)
1735689600000 Query Params
actionCustomParameterFragment string
Custom parameter name fragment for filtering by custom parameter
utm_source actionCustomValueFragment string
Custom parameter value fragment for filtering by custom parameter
google actionIds array<integer>
Conversion action IDs to report on; repeat the parameter or comma-separate. Restricts the conversion columns, and the per-action columns of splitColumnsBy=CONVERSION_ACTION, to these actions. Omitted: every action the caller may see.
17 breakdownByActions boolean
When true, adds one conversions column per conversion action. Ignored when splitColumnsBy is set, which supersedes it
true breakdownByCustomParameter boolean
When true, enables breakdown by custom parameter values
true customFrom string
First day of the period (yyyy-MM-dd) when range=CUSTOM; ignored for every other range. Defaults to today
2025-01-01 customTo string
Last day of the period, inclusive (yyyy-MM-dd), when range=CUSTOM; ignored for every other range. Defaults to today, so range=CUSTOM with only customFrom reports up to today. Must not be before customFrom
2025-01-31 eqLong object
Numeric ID-based filters using bracket notation: eqLong[FIELD]=value. Repeat the parameter to filter by multiple values: eqLong[SITE]=100&eqLong[SITE]=200. Available fields: BANNER, CAMPAIGN, ADVERTISER, PLACEMENT, ZONE, SITE. Valid keys: PLACEMENT_ID, ZONE_ID, SITE_ID, BANNER_ID, CAMPAIGN_ID, ADVERTISER_ID, PLACEMENT, ZONE, SITE, OPEN_RTB_PUBLISHER_ID, BANNER, CAMPAIGN, ADVERTISER, CHANNEL, ACTION, ACTION_ID, ATTRIBUTION_TYPE, COUNTRY, COUNTRY_GROUP, CARRIER, CONNECTION_TYPE, LANGUAGE, ACCEPT_LANGUAGE, TIME_ZONE_NAME, BROWSER_COUNTRY, TRAFFIC_SOURCE, FILL_SOURCE, REJECT_REASON, 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, IFA, RISK_SCORE, RISK_LEVEL, RISK_CATEGORY, PLACEMENT_TYPE, OPERATING_SYSTEM, OS_VERSION, BROWSER, BROWSER_VERSION, MOBILE_NETWORK, TIME_ZONE, REFERER, APP_PACKAGE, TOP_DOMAIN, PLATFORM, STATUS, BANNER_LABEL, PLACEMENT_LABEL, TEMPLATE_ID, UNIVERSAL_AD_ID, ADVERTISER_OWNER, SITE_OWNER, USER_ADVERTISER_SHARE
{"SITE":100} eqStr object
String-based filters using bracket notation: eqStr[FIELD]=value. Repeat the parameter to filter by multiple values: eqStr[COUNTRY]=US&eqStr[COUNTRY]=GB. A lone BANNER_LABEL, PLACEMENT_LABEL, DEVICE_VENDOR, DEVICE_MODEL or DEVICE_MODEL_CODE value is one value, commas included: eqStr[PLACEMENT_LABEL]=Coastal, Outdoor matches the label of that name. In every other field a lone value is split on commas: eqStr[COUNTRY]=US,GB is two countries. 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. PLACEMENT_LABEL and BANNER_LABEL take label names, matched regardless of case, and filter the General and the Advanced report alike: the traffic of the placements or creatives that carry any of the labels now (all of them with filterAllLabels). TEMPLATE_ID takes banner template ids and keeps, in both reports, the traffic of the creatives on those templates now. PLACEMENT_TYPE takes placement type ids: 1 Site, 2 Mobile Site, 3 Video, 4 Non-standard, 5 Application, 6 Email, 7 Click-through, 9 Native. 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, REJECT_REASON, 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, IFA, RISK_SCORE, RISK_LEVEL, RISK_CATEGORY, PLACEMENT_TYPE, OPERATING_SYSTEM, OS_VERSION, BROWSER, BROWSER_VERSION, MOBILE_NETWORK, TIME_ZONE, REFERER, APP_PACKAGE, TOP_DOMAIN, PLATFORM, STATUS, BANNER_LABEL, PLACEMENT_LABEL, TEMPLATE_ID, UNIVERSAL_AD_ID, ADVERTISER_OWNER, SITE_OWNER, USER_ADVERTISER_SHARE
{"COUNTRY":"US"} filterAllLabels boolean
With PLACEMENT_LABEL or BANNER_LABEL filters: true keeps only the placements or creatives that carry every named label, false (the default) those that carry any of them. Applies to both label filters, in the General and the Advanced report
true groupBy array<string>
Dimensions to split rows by; repeat the parameter or comma-separate for several. General report (no statisticType): SITE, OPEN_RTB_PUBLISHER_ID, ZONE, PLACEMENT, PLACEMENT_SIZE, PLACEMENT_LABEL, PLACEMENT_TYPE, 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 UNIVERSAL_AD_ID, ATTRIBUTION_TYPE and the owners, plus BROWSER, BROWSER_VERSION, OPERATING_SYSTEM, OS_VERSION, APP_PACKAGE, SCREEN_SIZE, LOCATION, CUSTOM_PARAMETER, TOP_DOMAIN (the page the ad was served on, scheme://host), DEVICE_RAM, PRICE_BAND, BROWSER_RANK, HARDWARE_RANK, PLATFORM_RANK and, depending on the analytics backend version, PLACEMENT_SIZE, PLACEMENT_TYPE, 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. PLACEMENT_TYPE rows are named by the type (Site Placement, Video Placement, ...) in the interface language. REFERER is deprecated: an alias of TOP_DOMAIN, still accepted, returning the Top Domain values under the column name referer
SITE,COUNTRY groupRange string
Time frame for grouping analytical data. Values: NONE, HOUR, DAY, WEEK, MONTH, YEAR, HOUR_24. Default: NONE
DAY hadoopAppPackage string
Advanced report (statisticType=HADOOP) only: count only in-app requests whose app package / bundle id contains this text.
com.example.game hadoopCustomParmName string
Advanced report (statisticType=HADOOP) only, superseded by hadoopCustomParms: count only requests carrying this custom parameter (the name the ad tag passes). Several names separated by commas count a request carrying any of them. Empty: any.
utm_source hadoopCustomParmValue string
Advanced report (statisticType=HADOOP) only, superseded by hadoopCustomParms: with hadoopCustomParmName, count only requests where that custom parameter has this value. With several names, where any of them has it.
newsletter hadoopCustomParms object
Advanced report (statisticType=HADOOP) only: the custom parameters a request must carry, by the name the ad tag passes, using bracket notation: hadoopCustomParms[utm_source]=newsletter. Repeat the parameter for several values of one name, which OR: hadoopCustomParms[utm_source]=newsletter&hadoopCustomParms[utm_source]=promo. Each parameter is one value, commas included. A name sent with no value counts every request carrying the parameter, whatever its value. Several names narrow each other unless hadoopCustomParmsAny is true. Empty: any.
{"utm_source":"newsletter"} hadoopCustomParmsAny boolean
Advanced report (statisticType=HADOOP) only: with several entries in hadoopCustomParms, true counts a request carrying any one of them. The default counts only requests carrying all of them, as every other filter here does
true hadoopRefDomain string
Advanced report (statisticType=HADOOP) only: count only requests whose Top Domain (the page the ad was served on, scheme://host) contains this text. The name is kept from when it matched the deprecated Referer.
news.example.com hourFrom integer
First hour of the day to report on (0-23), in the report's own time zone, applied to every day in the date range. The Advanced report (statisticType=HADOOP) and the raw-event logs (IMPRESSIONS_LOG, CLICKS_LOG, CONVERSIONS_LOG, ACTIONS_LOG) apply it whatever the group range; every other report type reads hours only with groupRange=HOUR and ignores it otherwise. Empty: from midnight.
9 hourTo integer
Last hour of the day to report on (0-23), inclusive, with the same rules as hourFrom. Empty: to the end of the day.
18 jsonKeys string
Analytics report (/rest-api/analytics/{format}) in JSON, and a saved report mailed as JSON: how each row names its fields. name (default) — the column's display name in the user's interface language, e.g. "Impressions" or "Impressionen"; a name several columns share (the Base, Publisher and Advertiser Impressions, Clicks, CTR…) keeps its last occurrence and each earlier one is keyed by its column id, e.g. publisher_impressions. id — every field is keyed by its column id (impressions, publisher_impressions, sumGross): the same in every language and never repeated, so scripts should use it. Other formats and operations ignore it
id limit integer
Maximum number of rows returned (for pagination). On the /rest-api/analytics/{format} report endpoints omitting it returns up to the network's records-per-request limit and a larger value is rejected; elsewhere the default is 50
100 offset integer
Number of result entries to skip (for pagination). Default: 0
0 range string
Time period for the report. Values: TODAY (default), YESTERDAY, CURRENT_WEEK, LAST_WEEK, LAST_2_WEEKS, CURRENT_MONTH, LAST_7_DAYS, LAST_30_DAYS, LAST_MONTH, LAST_3_MONTH, LAST_6_MONTH, CURRENT_YEAR, LAST_YEAR, CUSTOM. CUSTOM reads the period from customFrom/customTo
LAST_7_DAYS reportsLayoutSettings array<string>
Metric column ids to output; only applied when useReportsLayoutSettings=true. These are internal column keys, not display names — 'gross' or 'revenue' match nothing, and an id that names no column of the report type is skipped by the analytics report endpoints (named in the X-Ignored-Report-Columns response header) but refused with a 400 when saving a report or a dashboard widget. General report: impressions, clicks, ctr, requests and fill_rate (absent when grouping or filtering by advertiser/campaign/banner), conversions (also keeps the per-action columns), i2c, ccr, sumGross (Gross), sumNet (Net), sumMinimalNet, profit, apProfit, ecpmGross, ecpmNet, ecpmProfit, unique_visitors, confirmation_status, and the publisher_/advertiser_ variants such as publisher_impressions, publisher_sumNet (Revenue), advertiser_sumGross (Charges), advertiser_ecpmGross. Advanced report (HADOOP): requests, impressionsEligible, clicksEligible, ctrEffective, fillRate, sumGross, sumNet, profit, ecpmGross, ecpmNet, ecpmProfit and more. The complete list for the caller and report type is GET /rest-api/analytics/columns.do?statisticType=...
impressions,clicks,ctr,sumGross splitByAttribution boolean
Adds a nested click-through / view-through pair under each conversion-action column. Only meaningful with splitColumnsBy=CONVERSION_ACTION; ignored otherwise.
true splitColumnsBy string
The single dimension spread across report columns. Leave unset to keep the legacy shape, where breakdownByActions/breakdownByCustomParameter decide and the attribution columns are always present.
CONVERSION_ACTION statisticType string
Report type. Omit it for the General report (the default): aggregated totals — impressions, clicks, CTR, conversions, gross, net, profit, eCPM, requests, fill rate — grouped by site/zone/placement, advertiser/campaign/banner, country, channel or action. HADOOP — the Advanced report, computed from the raw ad-server logs: adds ad requests, opportunities and device/browser/OS/page/app/location dimensions; only when Hadoop analytics is configured on the network (legacy names HADOOP_ADREQUESTS, HADOOP_SECURITY and BROWSER_OS are read as HADOOP). IMPRESSIONS_LOG, CLICKS_LOG, CONVERSIONS_LOG, ACTIONS_LOG — one row per raw event instead of totals. TARGETING_COOKIE — cookie-targeting report. HEADER_BIDDING — the Header Bidding report: fills, unfilled requests, fill rate, gross and eCPM per fill source, needs the Header Bidding report permission
HADOOP useReportsLayoutSettings boolean
When true, only the metric columns listed in reportsLayoutSettings are output (grouping and date columns always stay); the column layout saved in the UI is not applied. Default: false — every metric column the user has permission to see
true usersTimeZoneId string
Time zone the Advanced report (statisticType=HADOOP) buckets its days and hours in, and the raw-event logs (IMPRESSIONS_LOG, CLICKS_LOG, CONVERSIONS_LOG, ACTIONS_LOG) count their days and show event times in: NETWORK, the network's reporting time zone with its daylight saving (also what a missing value means), or 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. Any other value counts as UTC. Other report types use the network's reporting time zone and ignore it. Default: NETWORK
NETWORK Responses
200
Analytics data retrieved successfully
400
customTo is before customFrom
401
Unauthorized - authentication error
403
The role lacks a reporting permission the request needs; the message names it
404
Not found — resource does not exist
500
Internal server error