Guides

Request reach estimate

Use this endpoint to forecast available impressions (reach) for an ad group configuration.

Overview

Use the Reach Estimate API to forecast the potential impression scale for a specific ad group configuration before launch.

Reach estimates help you:

  • evaluate targeting scale
  • understand whether targeting is too narrow or too broad
  • compare configuration changes before launch
  • optimize campaign setup before delivery begins

Reach Estimate answers one core planning question:

How much inventory is likely available for this ad group configuration?

Availability

Supported for Onsite Display only.

How Reach Estimate fits into planning

1
Configure

Define ad group parameters

Define targeting, geotargeting, and, schedule for the ad group.

2
Estimate

Run Reach Estimate

Estimate potential reach using the current configuration or eligible overrides.

3
Review

Evaluate reach

Review the estimated impression range and scale classification.

4
Refine

Adjust configuration

Adjust targeting or budget when estimated reach is too narrow or too broad.

5
Launch

Proceed to activation

Move forward with activation once the estimated scale is acceptable.

Use the forecast as a planning input: Review the estimate, refine the configuration as needed, and rerun the forecast before launch.

📌

Important

Reach Estimate evaluates projected inventory availability. It does not modify campaign or ad group settings.

How it works

The API simulates projected inventory availability based on your ad group configuration.

Reach estimates are influenced by:

  • targeting criteria
  • geotargeting
  • flight dates

The request can use:

  • existing ad group configuration
  • temporary simulation values supplied in the request

Important behavior

Forecasts are simulations only.

Reach estimate requests do not modify stored campaign or ad group settings. Simulation values exist only for the duration of the forecast request.

When to use Reach Estimate

Use Reach Estimate when you need to:

  • validate targeting scale before launch
  • compare broad versus narrow targeting strategies
  • determine whether a configuration is likely too restrictive
  • evaluate available impression scale before activation

Before you begin

  • Valid advertiserId
  • Defined targeting inputs
  • Valid geoTargets (if applicable)
📌

Readiness check

If targeting inputs or audiences are incomplete, the forecast may fail validation or return misleading scale results.

Endpoint

POST /api/v2/reachEstimate

View technical specifications

Request details

How this request is used

Use this endpoint to evaluate projected reach before activating or updating an ad group.

This is especially useful when:

  • testing targeting combinations
  • validating scale before launch
  • evaluating audience reach
  • comparing broader versus narrower targeting

Understanding configuration behavior

Reach estimate requests can use:

Configuration sourceBehavior
Stored ad group settingsUses existing configuration
Simulation values in requestTemporarily simulates different settings

Important behavior

If schedule is configured at the campaign level, simulation values in the request are ignored.

Key fields and behaviors

  • metric
    IMPRESSIONS, UNIQUE_HOUSEHOLDS
  • timeframes
    Specifies the forecast timeframes returned (daily, 30days, lifetime)
  • adgroupId
    Optional if forecasting stored ad group configuraiton

Required configuration areas

Configuration structure is the same as standard ad group configuration. To generate a valid estimate, the following must exist either:

  • in the stored ad group configuration
  • or inside the request payload
  • Schedule (startDate, endDate)
  • Targeting (targeting object, geotargeting, and audiences)

Existing ad group rules still apply

Reach estimate requests follow the same targeting and delivery rules as standard ad group configuration.

This means:

  • audience eligibility still applies
  • targeting validation still applies
  • unsupported targeting combinations still fail validation

Sample request

Reach estimate request for existing ad group
curl --location --request POST 'https://developer.api.us.walmart.com/api-proxy/service/display/api/v1/api/v2/reachEstimate' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <auth_token>' \ --header 'WM_SEC.AUTH_SIGNATURE: ***********' \ --header 'WM_CONSUMER.ID: <consumer_id>' \ --header 'WM_SEC.KEY_VERSION: 1' \ --header 'WM_CONSUMER.INTIMESTAMP: 1565309779' \ --data '{ "advertiserId": 1, "campaignId": 9, "adGroupId": 2, "metric": [ "impressions" ], "timeframes": ["daily", "30days", "lifetime"], "startDate": "2024-06-27T00:00:00Z", "endDate": "2024-12-30T23:59:59Z", "targeting": { "and": [ { "runOfSite": true }, { "geoTargets": [ { "id": 2 } ] } ] } }'
Reach estimate request without the adgroupId
curl --location --request POST 'https://developer.api.us.walmart.com/api-proxy/service/display/api/v1/api/v2/reachEstimate' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <auth_token>' \ --header 'WM_SEC.AUTH_SIGNATURE: ***********' \ --header 'WM_CONSUMER.ID: abcde-v123-fa2r-a1fs-asd45f6qef' \ --header 'WM_SEC.KEY_VERSION: 1' \ --header 'WM_CONSUMER.intimestamp: 1565309779' \ --data '
{ "advertiserId": 1, "campaignId": 9, "metric": [ "impressions" ], "timeframes":["daily","30days","lifetime"], "startDate": "2024-06-27T00:00:00Z", "endDate": "2024-12-30T23:59:59Z", "targeting": { "and": [ { "runOfSite": true }, { "geoTargets": [ { "id": 2 } ] } ] }
}

Response details

What this response returns

Returns projected impression estimates across one or more timeframes.

Key fields to use

  • forecastId
    Forecast request ID
  • estimates
    Forecasted metrics
  • daily
    Estimated daily impressions
  • 30days
    Estimated 30-day impressions
  • lifetime
    Estimated impressions across full flight
  • minValue
    Lower estimate bound
  • maxValue
    Upper estimate bound
  • scale
    Retrieve forecast scale

How to interpret the results

The API returns a range instead of an exact forecast because inventory availability changes dynamically.

Use:

  • minValue
  • maxValue
  • scale

together to evaluate expected delivery potential.

Scale interpretation

ScaleMeaningTypical action
LowNarrow reachBroaden targeting, increase budget, or adjust bids
ModerateBalanced reachContinue with current configuration or test small refinements
HighBroad reachConfirm targeting fit before activation

Common issues

IssueWhat it usually means
invalid targeting objectsTargeting configuration failed validation
invalid targetingUsing audiences not in AVAILABLE status or using targeting IDs that have isDisabled = true
missing or invalid schedule configurationRequired dates were not supplied or are invalid
overly narrow targetingConfiguration may produce limited scale
override values do not change resultsCampaign-level settings may be controlling the configuration

What happens next

After retrieving the estimate:

  • compare scale across targeting configurations
  • adjust targeting or budget if needed
  • use Delivery Estimate for performance modeling
  • rerun Reach Estimate after major configuration changes

Related pages

Updated about 3 hours ago

Did this page help you?