Overview

The Campaign Reach Estimator allows you to create a "Reach Estimate" - an estimated number of viewable impressions that a campaign could reach.

Estimates are calculated using:

Historical data for your selected targeting parameters (country, platform, audience segments, etc.)
Historical performance data from your actual on-site placements

The estimator returns both impression-based reach estimates and monthly active user (MAU) estimates with upper and lower bounds to account for statistical variance.

Endpoint

POST /api/1.0/{account-id}/campaign/reach_estimator

Query params (optional)

Parameter	Type	Required	Description
`estimations_types`	Array of strings	No	Types of estimates to return. Options: `IMPRESSIONS`, `MONTHLY_USERS`. Defaults to both if not specified

Request object

The request body must contain a campaign object with the minimum required fields.

Required fields


`country_targeting`
`platform_targeting`

🚧
The API does validate for the presence of the above fields.
However, missing targeting fields default to "ALL" (no constraints), which will produce unrealistically broad reach estimates.

📘
You can optionally include additional fields (see below) - or simply submit the entire campaign object.

Additional fields

When provided, the following fields affect the estimate by filtering the available audience:


`region_country_targeting`
`dma_country_targeting`
`city_targeting`
`os_targeting`
`browser_targeting`
`connection_type_targeting`
`publisher_targeting`
`audience_segments_multi_targeting`
`contextual_segments_targeting`
`custom_contextual_targeting`
`custom_audience_targeting`
`lookalike_audience_targeting`
`external_brand_safety`

Fields that do not affect the estimate

Any other fields can be included, but they do not affect the estimate. Examples are shown below:

Targeting

sub_country_targeting, postal_code_targeting

Budget

cpc, daily_cap, spending_limit, pricing_model

Frequency and scheduling

campaign_schedule, day_time_bid_modifier

Campaign settings

id, name, branding_text, tracking_code
creator, status, approval_state, policy_state
start_date, end_date, is_active
campaign_item_type
creative_traffic_allocation_ab_test_start_time
third_party_tags

Advanced campaign settings

daily_ad_delivery_model, spending_limit_model
cpa_goal
bid_strategy, bid_type, learning_state

Examples

Example 1 - Minimum fields

Pass a campaign object with minimum fields:

POST /api/1.0/demo-advertiser/campaign/reach_estimator

{
  "country_targeting": {
    "type": "INCLUDE",
    "value": ["US", "IL"]
  },
  "platform_targeting": {
    "type": "ALL",
    "value": ["DESK", "TBLT"]
  }
}

Example 2 - Additional fields

Pass a campaign object with additional fields:

POST /api/1.0/demo-advertiser/campaign/reach_estimator

{
  "country_targeting": {
    "type": "INCLUDE",
    "value": ["DE"]
  },
  "platform_targeting": {
    "type": "INCLUDE",
    "value": ["DESK"]
  },
  "audience_segments_multi_targeting": {
    "value": [
      {
        "type": "INCLUDE",
        "value": [22183902]
      }
    ]
  },
  "external_brand_safety": {
    "type": "DV",
    "values": [
      {
        "category_name": "Ad Server",
        "risk_level": "HIGH",
        "id": null
      }
    ]
  }
}

Example 3 - Entire campaign object

Pass the entire campaign object:

POST /api/1.0/demo-advertiser/campaign/reach_estimator

{
  "name": "My Campaign",
  "branding_text": "Demo Brand", 
  "country_targeting": {
    "type": "INCLUDE",
    "value": ["US", "CA"]
  },
  "platform_targeting": {
    "type": "INCLUDE", 
    "value": ["DESK", "TBLT"]
  },
  "os_targeting": {
    "type": "INCLUDE",
    "value": [{"osFamily": "WINDOWS"}]
  },
  "audience_segments_multi_targeting": {
    "state": "EXISTS",
    "value": [{"type": "INCLUDE", "value": [12345]}]
  },
  "cpc": 0.25,
  "start_date": "2024-01-01",
  "is_active": true,
  "..."
}

Response

All examples return the same response structure:

{
  "results": [
    {
      "lower_bound": 909568271,
      "upper_bound": 1005754051,
      "estimation_type": "IMPRESSIONS"
    },
    {
      "lower_bound": 850000,
      "upper_bound": 1100000,
      "estimation_type": "MONTHLY_USERS"
    }
  ],
  "metadata": {
    "partial_data_headers": null,
    "partial_data": false
  }
}

Response Fields

Field	Type	Description
`lower_bound`	Long	Conservative estimate of potential reach (capped at 1 billion). If result > 1 billion, the endpoint will return 1,000,000,000.
`upper_bound`	Long	Optimistic estimate of potential reach (capped at 1 billion). If result > 1 billion, the endpoint will return 1,000,000,001.
`is_budget_depleted`	Boolean	Whether budget constraints limit the reach
`estimation_type`	String	Type of estimate: `IMPRESSIONS` or `MONTHLY_USERS`

Notes

Reach Range: The actual reach will likely fall between the lower_bound and upper_bound values
Historical Basis: Estimates are normalized to 30-day periods based on historical performance data
Statistical Confidence: Bounds are calculated using statistical methods to account for data variance
External Limit: Reach estimates are capped at 1 billion impressions.