Overview
Explore forecasting APIs to estimate reach, delivery, and performance before launch.
Forecasting APIs allow partners to simulate potential ad group delivery and performance both prior to launch and when active. These APIs estimate future outcomes based on current ad group configuration, targeting, inventory availability, and marketplace conditions.
Use forecasting to evaluate audience scale, estimate delivery outcomes, and refine and/or optimize ad group configuration.
Forecasting can help answer questions such as:
- Is enough inventory available for this targeting strategy?
- How might budget or bid changes affect delivery?
- What performance outcomes can I expect before launch?
- Should I adjust targeting, bids, budgets, or schedule before activation?
- What potential effect will adjusting targeting, bids, budgets, or schedule have on delivery and/or performance?
Forecast results are directional estimates based on historical and modeled data. They should not be used for billing, invoicing, or finalized performance reporting.
Availability
Supported for Onsite Display only.
Forecasting workflow
Create campaign
Define the campaign structure and settings needed for planning.
Check forecasts
Evaluate potential reach, inventory, and delivery before creating the ad group.
Create ad group
Configure targeting, bids, budget, schedule, and other ad group settings.
Ad group goes live
The configured ad group begins serving media.
Check forecasts again
Use forecasting to evaluate potential delivery and identify opportunities to improve performance.
Optimize ad group
Use forecast insights to refine targeting, bids, budgets, or schedule as needed.
How forecasting works
Forecast requests evaluate ad group configuration and estimate potential outcomes based on:
- Inventory availability
- Audience reach
- Targeting configuration
- Budget settings
- Bid settings
- Schedule configuration
- Marketplace conditions
Configure
Start with the current ad group configuration, including targeting, budget, bids, and schedule.
Apply overrides
Temporarily change supported values to simulate a different configuration.
Run forecast
The forecast engine evaluates the current configuration and applicable overrides.
Review outcomes
Evaluate projected reach, inventory, impressions, clicks, spend, or orders.
ImportantForecasting APIs help estimate what may happen if an ad group is launched. They do not guarantee future performance.
Available endpoints
| Action | Endpoint | Technical Specifications |
|---|---|---|
| Request Reach Estimate | POST /api/v2/reachEstimate | View |
| Request Delivery Estimate | POST /api/v2/deliveryEstimate | View |
Reach Estimate vs. Delivery Estimate
Both forecasting APIs support campaign planning, but they answer different questions.
| Feature | Reach Estimate | Delivery Estimate |
|---|---|---|
| Primary purpose | Estimate available inventory and audience scale | Forecast expected ad group performance |
| Based on | Flight dates, targeting, geotargeting | Objective, targeting, bidding, schedule, budget |
| Returns | Available impression ranges | Projected impressions, clicks, spend, and orders |
| Best used for | Scale validation and inventory planning | Performance planning and optimization |
Simulation ("what-if" analysis) rules
Forecast overrides let you simulate potential configuration changes without modifying the ad group.
Simulated values are temporary
Values exist only for the forecast request.
They do not:
- Update the ad group
- Persist after the request completes
Simulated values exist only for the forecast request.
They do not:
- Update the ad group
- Persist after the request completes
Forecast APIs are read-only simulation tools.
Submitting a forecast request never changes:
- Campaign settings
- Ad group settings
- Targeting configuration
- Budget configuration
- Delivery configuration
Forecast results represent estimates, not guarantees.
Actual performance may differ due to:
- Auction competition
- Inventory availability
- Budget pacing
- Bid competitiveness
- Audience availability
- Marketplace conditions
Simulation eligibility
| Override Eligibility Matrix | ||||
|---|---|---|---|---|
| Attribute | Reach Estimate | Delivery Estimate | Overridable? | Notes |
| startDate | ✅ | ✅ | Yes | Must be ISO 8601 (ET). |
| endDate | ✅ | ✅ | Yes | Use 9999-12-30T00:00:00Z for unlimited. |
| targeting | ✅ | ✅ | Yes | Must include full targeting object. |
| dailyBudget | ❌ | ✅ | Yes (Delivery only) | Budget must be ≥ $0.01 and ≥ maxBid. |
| totalBudget | ❌ | ✅ | Yes (Delivery only) | Only valid when budgetType = total. |
| maxBid | ❌ | ✅ | Yes (Delivery only) | Bid must be ≥ $0.01. |
| deliverySpeed | ❌ | ✅ | Yes (Delivery only) | frontloaded allowed only when budgetType = total. |
| frequencyCapDay | ❌ | ✅ | Yes (Delivery only) | Range: 1–511. |
| frequencyCapWeek | ❌ | ✅ | Yes (Delivery only) | Range: 3–511. |
| frequencyCapMonth | ❌ | ✅ | Yes (Delivery only) | Range: 5–511. |
| Campaign-level budget | ❌ | ❌ | No | Ignored if defined at campaign level. |
| Campaign-level schedule | ❌ | ❌ | No | Ignored if defined at campaign level. |
| Campaign-level deliverySpeed | ❌ | ❌ | No | Ignored if defined at campaign level. |
How to interpret results
Forecasts are most valuable when they lead to configuration changes before launch.
| Forecast result | Potential action |
|---|---|
| Low available reach | Broaden targeting, expand geography, or extend campaign flight |
| Low projected impressions | Increase bids or budget |
| High available reach but weak performance | Refine targeting strategy |
| Strong delivery forecast | Proceed with activation |
| Large variance between reach and delivery | Review bid competitiveness and campaign objectives |
Why doesn't my forecast change?
Common causes include:
| Potential cause | Explanation |
|---|---|
| Campaign-level settings | Simulated values may be ignored because the setting is managed at the campaign level |
| Unsupported field | The selected forecast type may not support that field |
| Highly restrictive targeting | Audience scale may already be limited |
| Limited inventory availability | Available inventory may constrain forecast changes |
| Different forecast timing | Inventory and audience availability can change over time |
Avoid common mistakes
- Treating forecasts as guaranteed results
- Using forecast values for billing
- Forgetting that overrides are non-persistent
- Comparing forecasts directly to real-time reporting
- Assuming campaign-level settings can be overridden
- Forecasting against incomplete campaign configurations
Related pages
Updated about 3 hours ago