How to Set Up Your Own Yield Forecast Dashboard

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

Updated 22 days ago