📘

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:

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