📘

Prerequisites

• Access to the Kevel Forecast API
• Forecast settings configured in your network
• At least one Ad Product and Targeting Set created

1. Configure Forecast Network Settings

Use the GET /v1/forecaster/network-settings and POST /v1/forecaster/network-settings endpoints to review and set:

• Grouping dimensions (e.g., day, week, ad product)
• Priority buckets for traffic (used for sell-through logic)

2. Define Ad Products and Targeting Sets

• Create ad products:POST /v1/forecaster/ad-products
  These represent meaningful segments like “CPM Display”, or "CPC Sponsored Products".
• Add targeting sets to ad product: POST /v1/forecaster/ad-products/{adProductId}/targeting-sets
  Each targeting set should reflect the targeting logic you'd like forecasted (e.g., geography, device, audience).

3. Trigger the Forecast

Call one of the following endpoints to generate forecast data:

• For all ad products:POST /v1/forecaster/trigger-ad-products-forecasts
• For available inventory:POST /v1/forecaster/trigger-inventory-forecast

In the response for this request there will be an ID for each forecast. Save this as you'll need it in the next step.

Example response:

{
"193": {
    "type": "success",
    "forecastId": "7f7d4637-c6c7-4bed-99e0-05f997b96183"
	}
}

Forecast data will be processed and available.

4. Query Forecast Results

Use the GET /v1/forecaster/{forecastId} endpoint to fetch forecasted results.

Response overview

The response contains two key sections:

Yield Forecast trigger endpoints build available forecast requests with NewAds. The Forecast availability widget uses the same request shape, so these results follow the NewAds interpretation for available forecasts.

Total

Aggregate totals over the full forecast window:

"total": {  
  "booked": { "impressions": 7232, "revenue": 960.0, "clicks": 320 },  
  "available": { "impressions": 46144, "clicks": 3264 },  
  ...  
}

Useful for computing:

• Sell-through rate = booked.impressions / (booked.impressions + available.impressions)
• eCPM (booked) = booked.revenue / (booked.impressions / 1000)
• eCPM (all traffic) = booked.revenue / ((booked + available impressions) / 1000)

Grouped

Breakdowns by your chosen grouping (e.g., daily):

...
{
  "values": {
    "booked": {
      "impressions": 0,
      "revenue": 0.0,
      "clicks": 0,
      "uniqueUsers": 0
    },
    "uncapped": {
      "impressions": 1984,
      "revenue": 0.0,
      "clicks": 128,
      "uniqueUsers": 1984
    },
    "inventory": {
      "bookedAtLower": {
        "impressions": 1984,
        "revenue": 448.0,
        "clicks": 192,
        "uniqueUsers": 1984
      },
      "empty": {
        "impressions": 0,
        "clicks": 0,
        "uniqueUsers": 0
      },
      "bookedAtHigher": {
        "impressions": 0,
        "revenue": 0.0,
        "clicks": 0,
        "uniqueUsers": 0
      }
    },
    "available": {
      "impressions": 1984,
      "revenue": 0.0,
      "clicks": 128,
      "uniqueUsers": 1984
    }
  },
},
"key": {
  "$datetime.month": 6,
  "$datetime.date": "2025-06-04",
  "$datetime.week": 23
}
  ...

Each object has:

• key: e.g. the date
• values: booked, available, uncapped traffic data (learn more about these here)
• inventory.bookedAtLower and inventory.bookedAtHigher revenue/impression splits

This enables you to build time-series charts like:

• Daily impressions (booked vs available)
• Daily revenue
• Sell-through over time