--- updatedAt: 2026-10-14T17:56:26.000Z --- # Request Reach Estimate V2 Use this API to request a reach estimate or impressions opportunity forecast for a given ad group.
Users can simulate changes by overriding ad group-level settings in the request payload. The API does not modify any stored data.
Note: Currently, simulation is only supported for ad group-level attributes. Campaign-level schedules that cascade to ad groups cannot yet be simulated in this API. ### What It Does: * [x] Computes **potential reach** ( impressions) based on the targeting and schedule settings of a given ad group.
Allows developers to simulate changes to ad group configuration by overriding certain fields in the request payload. * [x] **Does not persist** or modify ad group data — it is strictly a forecasting tool * [x] To return a valid reach estimate, the following ad group-level attributes must be available **either in the stored ad group OR passed in the request** : *schedule and targeting.* ### Simulation (“What-If” analysis) support: * [x] You can override ad group-level startDate, endDate and targeting in the request body to **simulate changes without modifying the actual ad group.** * [x] Campaign-level schedules that cascade to ad groups cannot yet be simulated in this API. If budget, schedule and deliverySpeed are set at the campaign level, the API will disregard these values if passed, and the forecast provided will use the original campaign values instead. * [x] **All overrides are non-persistent**. This API does not modify stored campaign or ad group data.
### URL:POST /api/v2/reachEstimate
## Request Parameters
Parameters Notes Type Required Possible Values
advertiserId ID of advertiser integer Y Unique numeric identifier
campaignId ID of the campaign integer Y Unique numeric identifier
adGroupId ID the ad group integer N Unique numeric identifier
metric The list of metrics you are requesting an estimate for.
    over the entire forecast window reach) aggregated over the entire time of the duration
array Y IMPRESSIONS, UNIQUE_HOUSEHOLDS
startDate Simulated start date for ad group scheduling
Note:
  • If startDate has been set at the campaign level for the specified ad group:
    the startDate value passed in the API request is ignored, and the forecast in the response is based on the startDate of the campaign
  • If startDate has been set at the ad group level for the specified ad group:
    the forecast is based on the startDate value in the request, not the original value set at the ad group level
 datetime N Date must follow this format:
yyyy-MM-dd'T'HH:mm:ss.SSSXXX
Note:
  • All timestamp values must be in ISO 8601 format (e.g., "2025-07-20T19:10:10-05:00").
  • All date-time values are internally converted to Eastern Time (ET) for processing and normalized to the start of the hour. This means minutes and seconds are truncated. Example: "2025-07-20T19:10:10-05:00" becomes "2025-07-20T19:00:00-05:00" in ET

Kindly take these behaviors into consideration when assigning a value to startDate in your request.
endDate Simulated end date for ad group scheduling.
For ad groups that run indefinitely, use the value:
endDate = ‘9999-12-30T00:00:00Z’
Note:
  • If endDate has been set at the campaign level for the specified ad group:
    the endDate value passed in the API request is ignored. Instead, the forecast returned in the response is based on the endDate of the campaign
  • If endDate has been set at the ad group level for the specified ad group:
    the forecast is based on the endDate value in the request, not the original value set at the ad group level.
 datetime N Date must follow this format:
yyyy-MM-dd'T'HH:mm:ss.SSSXXX Note:
  • All timestamp values must be in ISO 8601 format (e.g., "2025-07-20T19:10:10-05:00").
  • All date-time values are internally converted to Eastern Time (ET) for processing and normalized to the start of the hour. This means minutes and seconds are truncated. Example: "2025-07-20T19:10:10-05:00" becomes "2025-07-20T19:00:00-05:00" in ET
  • The endDate must be set to a time after 12:00 PM ET. If the provided value is before 12:00 PM ET, the system will return an error.
  • Special Case: If you set endDate to exactly "00:00:00" ET (e.g., "2025-07-20T00:00:00-05:00"), it will be interpreted as the end of the previous day: "2025-07-19T23:59:59-05:00".

Kindly take these behaviors into consideration when assigning a value to startDate in your request.
targeting Defines the audience, contextual, keyword, and geographic targeting criteria for an ad group. This object supports both. Supports both expression-based and flattened targeting structure

View more details about the targeting object and its schema structures from the Ad group documentation here 

Note: You must choose one structure; mixing flat and expression-based schemas in a single payload is not supported. 		object Conditional\* The values:
• keywords
• contextual
• behavioral
• runOfSite
• geoTargets
timeframes Specifies the timeframes for which forecasts should be returned. If not provided, forecasts for all available timeframes will be returned. array N The values:
• daily
• 30days
• lifetime
\*Conditional - required if not configured for the adGroupId
***Note:*** If `adGroupId `is not provided, `startDate`, `endDate`, and `targeting `should be mandatorily passed and the forecast returned should be based on the specified values of `startDate`, `endDate`, and `targeting` .
### Rules * [x] To return a valid reach estimate, the following **ad group-level attributes** must be available either in the stored ad group OR passed in the request: startDate, endDate, and targeting
If any of these are missing in the ad group and not provided in the request payload, the API returns an error. * [x] If the following request parameters are set at the campaign level: startDate, endDate, the values for these parameters in the request payload are disregarded and the forecast response uses the original campaign values instead. * [x] If the following request parameters are set at the ad group level: startDate, endDate, and targeting, the values provided for these parameters in the request payload override the original values set at ad group level and are used in the forecast response instead * [x] Users can simulate changes by overriding ad group-level settings in the request payload. The API does not modify any stored data.
**Note:** Currently, the API supports simulation only for ad group-level attributes. Campaign-level budgets or schedules that apply to ad groups are not yet supported for simulation. * [x] Only one of flat or expression-based schemas can be be provided for targeting object in a single payload ## # Headers | Header Name | Description | Required | Values | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `Authorization` | The token will provide you the access to the API. It is same for all advertisers you access through the API. | Y | Please utilize the generated `auth_token` shared with you at the time of partner onboarding from the Getting Started Guide | | `Content-Type` | Format of the message body | Y | application/json | | `WM_CONSUMER.ID` | Unique ID for consumer. We will provide you the consumer ID to access the API. It is same for all advertisers you access through the API.    | Y | Please use the generated `ConsumerId` shared with you at the time of partner onboarding. Refer to the Getting Started Guide for more information | | `WM_SEC.AUTH_SIGNATURE` | Auth signature as an API key. | Y | Use the signature generator code from Getting Started Guide to generate this value | | `WM_SEC.KEY_VERSION` | Key version. We will provide you with the KEY VERSION to access the API. It is same for all advertisers you access through the API. | Y | 1 | | `WM_CONSUMER.intimestamp` | Timestamp for which the auth signature is generated. Use Unix epoch format for the timestamp. | Y | Use the signature generator code from Getting Started Guide to generate this value |
### Sample Request - Get impressions forecast for an ad group with updated values for schedule and targeting (Expression based Targeting Structure) ```curl 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 ' \ --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, "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 } ] } ] } }' ``` ### Sample Request - Get impressions forecast for an ad group with updated values for schedule and targeting(Flattened Targeting Structure) ```curl 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 ' \ --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, "adGroupId": 2, "metric": [ "impressions" ], "timeframes":["daily","30days","lifetime"], "startDate": "2024-06-27T00:00:00Z", "endDate": "2024-12-30T23:59:59Z", "targeting": { "runOfSite": true, "geoTargets": { "include": [ { "id": 2 } ] } } }' ``` ### Sample Request - Get unique\_households forecast for an ad group with updated values for schedule and targeting (Expression based Targeting Structure) ```curl 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 ' \ --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, "adGroupId": 2, "metric": [ "unique_households" ], "timeframes":["30days","lifetime"], "startDate": "2024-06-27T00:00:00Z", "endDate": "2024-12-30T23:59:59Z", "targeting": { "and": [ { "runOfSite": true }, { "geoTargets": [ { "id": 2 } ] } ] } }' ``` ### Sample Request - Get unique\_households forecast for an ad group with updated values for schedule and targeting (Flattened Targeting Structure) ```curl 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 ' \ --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, "adGroupId": 2, "metric": [ "unique_households" ], "timeframes":["30days","lifetime"], "startDate": "2024-06-27T00:00:00Z", "endDate": "2024-12-30T23:59:59Z", "targeting": { "runOfSite": true, "geoTargets": { "include": [ { "id": 2 } ] } } }' ``` ### Sample Request: Ex- 2 Get unique\_households forecast for an ad group with updated values for schedule and targeting(Expression based Targeting Structure) ```curl 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 ' \ --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, "adGroupId": 2, "metric": [ "impressions","unique_households" ], "timeframes":["daily","30days","lifetime"], "startDate": "2024-06-27T00:00:00Z", "endDate": "2024-12-30T23:59:59Z", "targeting": { "and": [ { "runOfSite": true }, { "geoTargets": [ { "id": 2 } ] } ] } }' ``` ### Sample Request: Ex- 2 Get unique\_households forecast for an ad group with updated values for schedule and targeting(Flattened Targeting Structure) ```curl 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 ' \ --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, "adGroupId": 2, "metric": [ "impressions","unique_household" ], "timeframes":["daily","30days","lifetime"], "startDate": "2024-06-27T00:00:00Z", "endDate": "2024-12-30T23:59:59Z", "targeting": { "runOfSite": true, "geoTargets": { "include": [ { "id": 2 } ] } } }' ``` ### Sample Request: Get impressions forecast for an ad group without the adgroupId with updated values for schedule and targeting(Expression based Targeting Structure) ```curl 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 ' \ --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 | Element | Description | Required | Type | | :--------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | :----- | | code | The response code can have following values:
  • success
  • failure
| Y | string | | forecastId | forecastId for every successful response | N | string | | estimates | Contains forecasted metrics over various time ranges. It is a nested json object that contains forecast data for impressions and uniqueHouseholds
**Supported metrics:**
  • impressions: Estimated number of ad impressions
  • uniqueHouseholds: Estimated number of unique household reach


***The estimates objects are detailed below in a separate table following this one.*** | Y | json | | details | Details of the response.
Values:
  • REACH\_ESTIMATE\_SUCCESS
  • REACH\_ESTIMATE\_FAILURE
| Y | string |
### estimates Objects: The estimates object contains forecasted metrics across multiple time ranges. Each supported metric is represented as a nested object with estimated ranges. Each metric object may include one or more time-range sub-objects. **Object structure**: ```json "estimates": { "": { "daily": { ... }, "30days": { ... }, "lifetime": { ... } } } ``` ***Time-Range Sub-Objects: Each metric can contain the following optional sub-objects:*** | Elements | Description | Required | Type | | :------- | :------------------------------------------------------- | -------- | :----- | | daily | Estimated metric values per day | N | object | | 30days | Estimated metric values for 30 days | N | object | | lifetime | Estimated metric values for the ad group's full lifetime | N | object | ***Estimate range Object: Each time-range object (daily, 30days, lifetime) contains the estimated range values described below :***: | Elements | Description | Required | Type | | :------- | :------------------------------------------------------------------------------------------------------------------------------------------ | -------- | :----- | | minValue | Lower bound of the estimated metric range | Y | int | | maxValue | Upper bound of the estimated metric range
\*\*\*Note:\*\*\*This field is omitted when there is no defined upper bound for the estimate | Y | int | | scale | The relative scale of the forecast (applicable to impressions metric only)
Values:
  • LOW
  • MODERATE
  • HIGH
| Y | string | ### Sample Response Success - Get impressions forecast for an ad group with updated values for schedule and targeting (Expression based Targeting Structure) ```json { "code": "success", "forecastId": "abc-123", "estimates": { "impressions": { "daily": { "minValue": 1, "maxValue": 15, "scale": "LOW" }, "30days": { "minValue": 5, "maxValue": 75, "scale": "MODERATE" }, "lifetime": { "minValue": 1, "maxValue": 15, "scale": "HIGH" } } "details": ["REACH_ESTIMATE_SUCCESS"] } } ``` ### Sample Response Failure - Get impressions forecast for an ad group with updated values for schedule and targeting (Expression based Targeting Structure) ```json JSON { "code": "failure", "details": [ "string" ] } ``` ### Sample Response Success - Get impressions forecast for an ad group with updated values for schedule and targeting(Flattened Targeting Structure) ```json { "code": "success", "forecastId": "abc-123", "estimates": { "impressions": { "daily": { "minValue": 1, "maxValue": 15, "scale": "LOW" }, "30days": { "minValue": 5, "maxValue": 75, "scale": "MODERATE" }, "lifetime": { "minValue": 1, "maxValue": 15, "scale": "HIGH" } } "details": ["REACH_ESTIMATE_SUCCESS"] } } ``` ### Sample Response Failure - Get impressions forecast for an ad group with updated values for schedule and targeting(Flattened Targeting Structure) ```json JSON { "code": "failure", "details": [ "string" ] } ``` ### Sample Response Success - Get unique\_households forecast for an ad group with updated values for schedule and targeting (Expression based Targeting Structure) ```json { "code": "success", "forecastId": "abc-101", "estimates": { "uniqueHouseholds": { "daily": { "minValue": 346602, "maxValue": 577670 }, "30days": { "minValue": 10561900, "maxValue": 17603167 }, "lifetime": { "minValue": 16983502, "maxValue": 28305837 } } }, "details": ["REACH_ESTIMATE_SUCCESS"] } ``` ### Sample Response Failure - Get unique\_households forecast for an ad group with updated values for schedule and targeting (Expression based Targeting Structure) ```json JSON { "code": "failure", "details": [ "DATA_UNAVAILABLE" ] } ``` ### Sample Response Success - Get unique\_households forecast for an ad group with updated values for schedule and targeting (Flattened Targeting Structure) ```json { "code": "success", "forecastId": "abc-101", "estimates": { "uniqueHouseholds": { "daily": { "minValue": 346602, "maxValue": 577670 }, "30days": { "minValue": 10561900, "maxValue": 17603167 }, "lifetime": { "minValue": 16983502, "maxValue": 28305837 } } }, "details": [ "REACH_ESTIMATE_SUCCESS" ] } ``` ### Sample Response Failure - Get unique\_households forecast for an ad group with updated values for schedule and targeting (Flattened Targeting Structure) ```json JSON { "code": "failure", "details": [ "DATA_UNAVAILABLE" ] } ``` ### Sample Response Success: Ex- 2 Get unique\_households forecast for an ad group with updated values for schedule and targeting (Expression based Targeting Structure) ```json JSON { "code": "success", "forecastId": "abc-123", "estimates": { "impressions": { "daily": { "minValue": 1, "maxValue": 15, "scale": "LOW" }, "30days": { "minValue": 5, "maxValue": 75, "scale": "MODERATE" }, "lifetime": { "minValue": 1, "maxValue": 15, "scale": "HIGH" } }, "uniqueHouseholds": { "daily": { "minValue": 346602, "maxValue": 577670 }, "30days": { "minValue": 10561900, "maxValue": 17603167 }, "lifetime": { "minValue": 16983502, "maxValue": 28305837 } } "details": ["REACH_ESTIMATE_SUCCESS"] } } ``` ### Sample Response Success: Ex- 2 Get unique\_households forecast for an ad group with updated values for schedule and targeting (Flattened Targeting Structure) ```json JSON { "code": "success", "forecastId": "abc-123", "estimates": { "impressions": { "daily": { "minValue": 1, "maxValue": 15, "scale": "LOW" }, "30days": { "minValue": 5, "maxValue": 75, "scale": "MODERATE" }, "lifetime": { "minValue": 1, "maxValue": 15, "scale": "HIGH" } }, "uniqueHouseholds": { "daily": { "minValue": 346602, "maxValue": 577670 }, "30days": { "minValue": 10561900, "maxValue": 17603167 }, "lifetime": { "minValue": 16983502, "maxValue": 28305837 } } "details": ["REACH_ESTIMATE_SUCCESS"] } } ``` ### Sample Response Success: Get impressions forecast for an ad group without the adgroupId with updated values for schedule and targeting(Expression based Targeting Structure) ```json JSON { "code": "success", "forecastId": "abc-123", "estimates": { "impressions": { "daily": { "minValue": 1, "maxValue": 15, "scale": "LOW" }, "30days": { "minValue": 5, "maxValue": 75, "scale": "MODERATE" }, "lifetime": { "minValue": 1, "maxValue": 15, "scale": "HIGH" } } "details": [ "REACH_ESTIMATE_SUCCESS" ] } } } ```