> For the complete documentation index, see [llms.txt](https://docs.exads.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.exads.com/api/exads-public-api/api-manual-global-stats.md). # Global Statistics API This section describes the Global Statistics API request parameters and result data. *** {% hint style="info" %} The statistics API routes have been renamed: * /statistics/advertiser/... -> /statistics/a/... * /statistics/publisher/... -> /statistics/p/... {% endhint %} *** {% hint style="info" %} The Global Statistics API only shows skipped RTB queries for Date, Sites, Zones, Countries, Regions, and Sub IDs. {% endhint %} ***
ParameterDescriptionTypeNotes
countReturn only the total of results.integeroptional
detailedGet more detail if possible.integeroptional
timezoneTimezone setting for 'hour' filter and 'group_by'stringoptional
totalsIndicates whether to add totals to response or not.integeroptional
filterFilters to restrict the returned values of a statistics queryobjectoptional
group_byA list of group by values to be applied in the data. Maximum four are permitted.arraymandatory
order_byOrdering of results by a specific field(s). A maximum of two are permitted.arrayoptional
projectionIndividual sub-structures you want returned.arrayoptional
limitThe number of records to return in this response.integeroptional
offsetThe position to retrieve the records from.integeroptional
## Parameter count | Field | Value | | ---------------- | --------------------------------- | | Property | count | | Type | optional | | Variable type | integer | | Default Value | 0 | | Available values | \[0, 1] | | Description | Return only the total of results. | **Example:** ```json { "count": 1 } ``` ## Parameter detailed | Field | Value | | ---------------- | -------------------------------------- | | Property | detailed | | Type | optional | | Variable type | integer | | Default Value | 0 | | Available values | \[0, 1] | | Description | Whether to return detailed information | **Example:** ```json { "detailed": 1 } ``` ## Parameter timezone Timezone setting for `hour` filter and `group_by`. | Field | Value | | ---------------- | ---------------------------------------------------------------------------------------------------------- | | Property | timezone | | Type | optional | | Variable type | string | | Default Value | `America/New_York` | | Available values | See the `/collections/timezones` endpoint | | Description | NOTE: Timezones are only relevant when querying based on hourly data; for non-hourly data, this is a no-op | **Example:** ```json { "timezone": "Europe/Dublin" } ``` ## Parameter totals | Field | Value | | ---------------- | ------------------------------------------------ | | Property | totals | | Type | optional | | Variable type | integer | | Default Value | 0 | | Available values | \[0,1] | | Description | Indicates whether add totals to response or not. | **Example:** ```json { "totals": 1 } ``` ## Parameter filter | Field | Value | | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Property | filter | | Type | optional | | Variable type | object | | Available option for Advertisers | \["adblock", "advertiser\_ad\_type\_id", "browser\_id", "carrier\_id", "category\_id", "country\_iso", "date\_from", "date\_to", "device\_id", "device\_type\_id", "hour", "language\_id", "operating\_system\_id", "region\_id", "site\_hostname", "site\_id", "size", "sub", "zone\_id", "campaign\_id", "exclude\_deleted", "offer\_id", "offer\_landing\_page\_id", "variation\_id"] | | Available option for Publishers | \["adblock", "browser\_id", "carrier\_id", "category\_id", "country\_iso", "date\_from", "date\_to", "device\_id", "device\_type\_id", "hour", "language\_id", "operating\_system\_id", "region\_id", "site\_hostname", "site\_id", "zone\_id", "publisher\_ad\_type\_id", "size", "sub"] | | Description | Filter by certain parameters. | ### Filter: `country_iso` | Field | Value | | ---------------- | ------------------------------------------------- | | Property | country\_iso | | Type | optional | | Variable type | string | | Default Value | - | | Available values | See /collections/countries endpoint iso3 property | | Description | List of ISO 3 code | **Example:** ```json { "filter": { "country_iso": ["ESP", "IRL"] } } ``` ### Filter `date_from`, `date_to` The `date_from` and `date_to` parameters control the window over which you want to fetch stats information. * date\_from: Date from range for statistics, (Default beginning of month), * date\_to: Date to range for statistics, (Default today) | Field | Value | | ---------------- | ---------------------------------------------------- | | Property | date\_from, date\_to | | Type | optional | | Variable type | string | | Default Value | The dates default to the current month. | | Available values | YYYY-mm-dd | | Description | Date from/to range for statistics. Format YYYY-mm-dd | **Example:** ```json { "filter": { "date_from": "2019-02-25", "date_to": "2019-02-28" } } ``` Timezones are only relevant when we are querying based on hourly data, for non-hourly data this is a no-op. ### Filter: advertiser\_ad\_type\_id, campaign\_id, browser\_id, carrier\_id, category\_id, device\_id, device\_type\_id, language\_id, offer\_id, offer\_landing\_page\_id, operating\_system\_id, hour, region\_id, site\_id, sub, variation\_id, zone\_id, publisher\_ad\_type\_id
FieldValue
Propertyadvertiser_ad_type_id, campaign_id, browser_id, carrier_id, category_id, device_id, device_type_id, language_id, offer_id, offer_landing_page_id, operating_system_id, hour, region_id, site_id, sub, variation_id, zone_id, advertiser_ad_type_id, publisher_ad_type_id
Typeoptional
Variable typearray
Items typeinteger
Default Value-
Available valuesRelative properties OR collections
DescriptionList of entity Ids
**Example:** ```json { "filter": { "campaign_id": [123, 456], "browser_id": [789] } } ``` ### Filter: `exclude_deleted`
FieldValue
Propertyexclude_deleted
Typeoptional
Variable typeinteger
Default Value0
Available values[0, 1]
DescriptionWhether to exclude deleted campaigns or not.
**Example:** ```json { "filter": { "exclude_deleted": 1 } } ``` ### Filter: `adblock` | Field | Value | | ---------------- | ---------------------------------------- | | Property | adblock | | Type | optional | | Variable type | string | | Default Value | "all" | | Available values | "adblock", "all", "standard" | | Description | Whether to include adblock zones or not. | **Example:** ```json { "filter": { "adblock": "standard" } } ``` ### Filter: `site_hostname` | Field | Value | | ---------------- | ----------------------------------------------------------------------------------------------- | | Property | site\_hostname | | Type | optional | | Variable type | string | | Default Value | - | | Available values | Valid characters for hostnames are letters from a to z, the digits from 0 to 9, hyphen and dot. | | Description | Filter by site hostname. | **Example:** ```json { "filter": { "site_hostname": ["www.example.com", "www.example-site.org"] } } ``` ### Filter: `size` | Field | Value | | ---------------- | ------------------------------------------------------------------------------------- | | Property | size | | Type | optional | | Variable type | string | | Default Value | - | | Available values | Valid characters for size are the digits from 0 to 9 and x character. Example 300x100 | | Description | Filter by size | **Example:** ```json { "filter": { "size": ["300x100"] } } ``` ## Parameter group\_by
FieldValue
Propertygroup_by
Typemandatory
Variable typearray
Items typestring
Default Value-
Available values for Advertisers[”adblock”, “advertiser_ad_type_id”, browser_id”, “campaign_id”, “carrier_id”, “category_id”, “country_iso”, “date”, “hour”, “device_id”, “device_type_id”, “language_id”, “operating_system_id”, “region_id”, “site_id”, “sub”, “zone_id”, “week”, “month”, “quarter”, “year”, “offer_id”, “offer_landing_page_id”, “site_hostname”, “size”, “variation_id”]
Available values for Publishers[“adblock”, “browser_id”, “carrier_id”, “category_id”, “country_iso”, “date”, “device_id”, “device_type_id”, “hour”, “language_id”, “operating_system_id”, “publisher_ad_type_id” “region_id”, “site_id”, “size”, “sub”, “zone_id”, “week”, “month”, “quarter”, “year”]
DescriptionA list of sub-requests to include additional data in response.
**Example:** ```json { "group_by": [ "browser", "date" ] } ``` ## Parameter order\_by
Propertyorder_by
Typeoptional
Variable typearray
Items typestring
Default Value-
Available metrics field values[“cpc”, “cpc”, “cpm”, “cpv”, “ctr”, “clicks”, “impressions”, “video_impressions”, “video_views”, “vtr”, “rtb_win_ratio”, “rtb_avg_total_time”, “rtb_skipped”, “rtb_bid_response_ratio”, “rtb_avg_cpm”, “rtb_timeouts_ratio”, “rt_errors_ratio”, “rtb_no_bid_ratio”, “rtb_skipped_ratio”]
Available field values dependent on `group_by’ for Advertisers[”adblock”, “browser_id”, “campaign_id”, “carrier_id”, “category_id”, “country_iso”, “device_id”, “date”, “device_type_id”, “hour”, “ecpa1”, “g1”,“language_id”, “month”, “offer_id”, “offer_landing_page_id”, “operating_system_id”, “quarter”, “region_id”, “site_hostname”, “site_id”, “sub”, “variation_id”, “week”, “year” ,“zone_id”]
Available field values dependent on `group_by’ for Publishers[“adblock”, “browser_id”, “carrier_id”, “category_id”, “country_iso”, “device_id”, “date”, “device_type_id” , “hour”, “language_id”, “month”, “operating_system_id”, “quarter”, “region_id”, “site_id”, “sub”, “week”, “year”, “zone_id”]
Available order values[“asc”, “desc”]
DescriptionA list of available order by options
*** {% hint style="success" %} **Hints**: * The metrics fields are available all the time to use as order by field. * To order by specific value (for example by “browser\_id”), you need to include it in “group\_by” parameter. {% endhint %} *** The “g1”, “ecpa1” values are only available when the account has Conversion Tracking (Goals). All goals associated with a serial number (g1, g2, …gx). The eCPA values are accordingly ecpa1, ecpa2, …ecpax. **Example:** ```json { "order_by": [ { "field": "impressions", "order": "desc" } ] } ``` Example to organize the campaign results chronologically, the “date” need to be included in both “group\_by” and “order\_by”: ```json { "group_by": [ "campaign_id", "date" ], "order_by":[ { "field": "date", "order": "asc" } ] } ``` ## Parameter projection The projection parameter reflects what will be returned in the resulting payload, if not specified all sub structures will be returned. | Property | Projection | | -------------------------------------- | ---------------------------------- | | Type | optional | | Variable type | array | | Items type | string | | Default Value | all options,,see below | | Available field values for Advertisers | \[“base”, “rtb”, “video”, “goals”] | | Available field values for Publishers | \[“base”, “rtb”, “video”, “wpn”] | **Example:** ```json { "projection": [ "video" ] } ``` ### Request single metrics It is possible to require a few metrics instead all the ones inside a given projection. This way, the response time can be drastically reduced as EXADS servers doesn't need to compute every single metric. **Example:** ```json { "projection": { "video": [ "views", "vtr" ] } } ``` **Possible metrics:** | Projection | Metrics | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | base | `impressions`, `clicks`, `cost`, `cpc`, `margin`, `cpm`, `ctr`, `network_revenue`1, `publisher_revenue`1, `revenue`, `ad_requests`, `fill_rate`, `ad_requests_rpm` | | video | `impressions`, `views`, `cpv`, `vtr` | | wpn | `sent`, `subscriptions`, `unsubscriptions` | | rtb2 | `avg_total_time`, `avg_cpm`, `bid_response_ratio`, `errors`, `errors_ratio`, `no_bid`, `no_bid_ratio`, `queries`, `skipped`, `skipped_ratio`, `success`, `timeouts`, `timeouts_ratio`, `total_time`, `value`, `win_ratio`, `wins` | 1 Available only for Network Users;\ 2 Also available Network Users with `adv_` and `pub_` prefixes (for Advertiser and Publisher, respectively). ## Parameter limit The number of records to return in this response. | Field | Value | | ------------- | -------- | | Property | limit | | Type | optional | | Variable type | integer | | Default Value | 50 | **Example:** ```json { "limit": 25 } ``` ## Parameter offset The position to retrieve the records from. | Field | Value | | ------------- | -------- | | Property | offset | | Type | optional | | Variable type | integer | | Default Value | 0 | **Example** ```json { "offset": 150 } ``` ## Example 1 Advertiser campaign statistic with filtering. ### **Request:** ```json { "detailed": true, "totals": 1, "filter": { "date_from": "2019-03-10", "date_to": "2019-03-11", "country_iso": ["USA"] }, "group_by": ["campaign_id"], "order_by": [ { "field": "campaign_id", "order": "desc" } ], "limit": 2, "offset": 0 } ``` ### Response: ```json { "request_metadata": { "count": 4, "limit": 2, "offset": 0 }, "result": [ { "clicks": 0, "cost": 1.3302, "cpc": 0, "cpm": 0.45586017820425, "ctr": 0, "group_by": { "campaign_id": { "active": "1", "campaign_ad_type_name": "Popunders", "id": "1234567", "name": "Ron Mainstream Campaign " } }, "impressions": 2918, "rtb": { "avg_cpm": 0.15582967823432, "avg_total_time": 89.522714492492, "errors": 112, "errors_ratio": 0.011368411650186, "no_bid": 870594, "no_bid_ratio": 88.368490823053, "queries": 985186, "response_ratio": 11.57101298638, "skipped": 0, "skipped_ratio": 0, "success": 984590, "timeouts": 484, "timeouts_ratio": 0.049127778916875, "total_time": 88196525, "value": 1776.396, "win_ratio": 0.29842080581738, "wins": 2940 }, "video": { "cpv": 0, "impressions": 0, "views": 0, "vtr": 0 } }, { "clicks": 0, "cost": 18.1621655, "cpc": 0, "cpm": 1.8273634671496, "ctr": 0, "group_by": { "campaign_id": { "active": "1", "campaign_ad_type_name": "Popunders", "id": "7654321", "name": "Ron Mainstream Campaign Test" } }, "impressions": 9939, "rtb": { "avg_cpm": 1.4753505300475, "avg_total_time": 88.777190144965, "errors": 46, "errors_ratio": 0.0014192869995779, "no_bid": 3209674, "no_bid_ratio": 99.031490893114, "queries": 3241064, "response_ratio": 0.8964340105595, "skipped": 0, "skipped_ratio": 0, "success": 3238728, "timeouts": 2290, "timeouts_ratio": 0.070655809326814, "total_time": 287732555, "value": 4286.48343, "win_ratio": 0.30665855410445, "wins": 9939 }, "video": { "cpv": 0, "impressions": 0, "views": 0, "vtr": 0 } } ], "result_total": { "clicks": 0, "cost": 74.0473595, "cpc": 0, "cpm": 2.0864288391096, "ctr": 0, "impressions": 35490, "rtb": { "avg_cpm": 0.23441613972984, "avg_total_time": 87.995789332859, "errors": 539, "errors_ratio": 0.0049868154705264, "no_bid": 9771471, "no_bid_ratio": 90.405422546568, "queries": 10808501, "response_ratio": 9.5135301370653, "skipped": 0, "skipped_ratio": 0, "success": 10799741, "timeouts": 8221, "timeouts_ratio": 0.07606050089647, "total_time": 951102577, "win_ratio": 0.32861171035651, "wins": 35518 }, "video": { "cpv": 0, "impressions": 0, "views": 0, "vtr": 0 } } } ``` ## Example 2 Advertiser statistic by date for the current month ordered by impressions. ### **Request:** ```json { "group_by": ["date"], "order_by": [ { "field": "impressions", "order": "desc" } ] } ``` ### **Response:** ```json { "request_metadata": { "count": 3, "limit": 50, "offset": 0 }, "result": [ { "clicks": 0, "cost": 624.2439917, "cpc": 0, "cpm": 1.0978015474007, "ctr": 0, "group_by": { "date": { "date": "2019-03-02" } }, "impressions": 568631, "rtb": { "avg_cpm": 0.31273156270632, "avg_total_time": 114.34705591799, "errors": 4143, "errors_ratio": 0.0076578188576312, "no_bid": 48085697, "no_bid_ratio": 88.8804144989, "queries": 54101567, "response_ratio": 10.971772776933, "skipped": 0, "skipped_ratio": 0, "success": 54021598, "timeouts": 75826, "timeouts_ratio": 0.14015490530986, "total_time": 6186354907, "value": 185634.35958, "win_ratio": 1.1633248996281, "wins": 629377 }, "video": { "cpv": 0, "impressions": 0, "views": 0, "vtr": 0 } }, { "clicks": 0, "cost": 622.1688691, "cpc": 0, "cpm": 1.1800128762878, "ctr": 0, "group_by": { "date": { "date": "2019-03-01" } }, "impressions": 527256, "rtb": { "avg_cpm": 0.27775587567531, "avg_total_time": 118.91585420372, "errors": 2954, "errors_ratio": 0.0078196779097434, "no_bid": 32641750, "no_bid_ratio": 86.407573260111, "queries": 37776492, "response_ratio": 13.412992397494, "skipped": 0, "skipped_ratio": 0, "success": 37708708, "timeouts": 64830, "timeouts_ratio": 0.17161466448499, "total_time": 4492223815, "value": 140737.73563, "win_ratio": 1.4077723257099, "wins": 531807 }, "video": { "cpv": 0, "impressions": 0, "views": 0, "vtr": 0 } }, { "clicks": 0, "cost": 441.843491, "cpc": 0, "cpm": 0.96186339096399, "ctr": 0, "group_by": { "date": { "date": "2019-03-03" } }, "impressions": 459362, "rtb": { "avg_cpm": 0.26462497173837, "avg_total_time": 116.9210100884, "errors": 2183, "errors_ratio": 0.0059889808787451, "no_bid": 32174177, "no_bid_ratio": 88.268681100486, "queries": 36450275, "response_ratio": 11.500815837466, "skipped": 0, "skipped_ratio": 0, "success": 36366256, "timeouts": 81836, "timeouts_ratio": 0.22451408116948, "total_time": 4261802971, "value": 110932.87869, "win_ratio": 1.2852029237091, "wins": 468460 }, "video": { "cpv": 0, "impressions": 0, "views": 0, "vtr": 0 } } ] } ``` ## Example 3 Publisher statistic by date and region\_id, ordered by impressions. ### Request: ```json { "detailed": true, "filter": { "date_from": "2019-03-10", "date_to": "2019-03-11", "country_iso": ["USA"] }, "group_by": ["date", "region_id"], "order_by": [ { "field": "impressions", "order": "desc" } ], "limit": 30, "offset": 0 } ``` ### Response: ```json { "request_metadata": { "count": 2, "limit": 30, "offset": 0 }, "result": [ { "clicks": 3087, "cpc": 0.033842716164561, "cpm": 0.069188574849649, "ctr": 0.20444155402072, "group_by": { "date": { "date": "2019-03-11" }, "region_id": { "country_iso": "USA", "country_long_name": "United States of America", "country_short_name": "United States", "id": 5332921, "name": "California" } }, "impressions": 1494954, "revenue": 104.4724648, "rtb": { "avg_cpm": 0, "avg_total_time": 0, "bid_response_ratio": 0, "errors": 0, "errors_ratio": 0, "no_bid": 0, "no_bid_ratio": 0, "queries": 0, "skipped": 0, "skipped_ratio": 0, "success": 0, "timeouts": 0, "timeouts_ratio": 0, "total_time": 0, "value": 0, "win_ratio": 0, "wins": 0 }, "video": { "cpv": 0.038451404048583, "impressions": 15013, "views": 2717, "vtr": 18.097648704456 }, "wpn": { "subscriptions": 0, "unsubscriptions": 0 } }, { "clicks": 3071, "cpc": 0.03151133555845, "cpm": 0.066658890819906, "ctr": 0.21153940205505, "group_by": { "date": { "date": "2019-03-10" }, "region_id": { "country_iso": "USA", "country_long_name": "United States of America", "country_short_name": "United States", "id": 5332921, "name": "California" } }, "impressions": 1436818, "revenue": 96.7713115, "rtb": { "avg_cpm": 0, "avg_total_time": 0, "bid_response_ratio": 0, "errors": 0, "errors_ratio": 0, "no_bid": 0, "no_bid_ratio": 0, "queries": 0, "skipped": 0, "skipped_ratio": 0, "success": 0, "timeouts": 0, "timeouts_ratio": 0, "total_time": 0, "value": 0, "win_ratio": 0, "wins": 0 }, "video": { "cpv": 0.036216808196108, "impressions": 14921, "views": 2672, "vtr": 17.907646940554 }, "wpn": { "subscriptions": 0, "unsubscriptions": 0 } } ] } ``` ## **Example 4** Publisher statistic by site\_id with projection. ### **Request:** ```json { "detailed": true, "projection": ["wpn", "video", "rtb"], "filter": { "date_from": "2019-03-10", "date_to": "2019-03-11", "country_iso": ["USA"] }, "group_by": ["site_id"], "order_by": [ { "field": "impressions", "order": "desc" } ], "limit": 30, "offset": 0 } ``` ### **Response** ```json { "request_metadata": { "count": 2, "limit": 30, "offset": 0 }, "result": [ { "clicks": 14320, "cpc": 0.028298959692737, "cpm": 0.057945765404939, "ctr": 0.20476288186597, "group_by": { "site_id": { "id": "11223344", "name": "nice-example.com" } }, "impressions": 6916414, "revenue": 405.2411028, "rtb": { "avg_cpm": 0, "avg_total_time": 0, "bid_response_ratio": 0, "errors": 0, "errors_ratio": 0, "no_bid": 0, "no_bid_ratio": 0, "queries": 0, "skipped": 0, "skipped_ratio": 0, "success": 0, "timeouts": 0, "timeouts_ratio": 0, "total_time": 0, "value": 0, "win_ratio": 0, "wins": 0 }, "video": { "cpv": 0.031519102652252, "impressions": 77041, "views": 12857, "vtr": 16.688516504199 }, "wpn": { "subscriptions": 0, "unsubscriptions": 0 } }, { "clicks": 14148, "cpc": 0.028769196296296, "cpm": 0.063791981699323, "ctr": 0.22173710048179, "impressions": 6314909, "revenue": 407.0265892, "rtb": { "avg_cpm": 0, "avg_total_time": 0, "bid_response_ratio": 0, "errors": 0, "errors_ratio": 0, "no_bid": 0, "no_bid_ratio": 0, "queries": 0, "skipped": 0, "skipped_ratio": 0, "success": 0, "timeouts": 0, "timeouts_ratio": 0, "total_time": 0, "value": 0, "win_ratio": 0, "wins": 0 }, "video": { "cpv": 0.036406671663685, "impressions": 65620, "views": 11180, "vtr": 17.037488570558 }, "wpn": { "subscriptions": 0, "unsubscriptions": 0 } } ] } ```
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.exads.com/api/exads-public-api/api-manual-global-stats.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.