Campaign Planner API

Overview

The Forecasting API enables API customers to generate pre-campaign inventory forecasts programmatically before campaign setup. Customers can submit targeting, date range, placement type, and optional inventory constraints to estimate available supply and improve planning confidence.

This API is intended for customers who build campaigns through internal tools, automated workflows, or third-party systems and need forecasting capabilities without relying on the FreeWheel DSP UI.

Problem

API-first customers need a reliable way to forecast inventory before creating or modifying campaigns. Today, forecasting is often tied to UI workflows, manual planning, or support-assisted processes, which creates friction for customers managing campaigns at scale.

Without API-based forecasting, customers may:

Build campaigns without knowing whether enough inventory exists
Over- or under-budget based on incomplete supply estimates
Rely on manual FreeWheel support or account teams
Duplicate targeting logic across planning and activation workflows

Goals

The Forecasting API should allow API customers to:

Submit forecast requests using supported campaign targeting inputs
Retrieve estimated available impressions or avails
Understand whether a campaign is likely to deliver
Integrate forecasting into their own planning, trafficking, and optimization systems

Users

API Customer

A customer that manages campaign planning and trafficking through their own platform or workflow and uses FreeWheel DSP APIs directly

API Approach

Authentication

API customers authenticate using the existing FreeWheel DSP API authentication model.

Forecasting API documentation should clearly cover:

Required authentication method
Required permissions or roles
Token usage and expiration behavior
Error handling for unauthorized requests
Whether SSO/MFA applies to API access or only UI login

For API-only customers, MFA is generally not exposed as an API endpoint unless the API authentication flow itself requires interactive login. If MFA is handled through UI-based SSO, API docs should explain that API access relies on existing API credentials, tokens, or service accounts rather than direct MFA endpoints.

Rate Limits

The API only supports 10 requests per min

Pre Sales Forecasting via the API directions

Access:

Authenticate: https://api-docs.freewheel.tv/advertiser/docs/authentication

Forecasting endpoints:

GET request /rest/v2/forecasting/keys
GET request rest/v2/forecasting/values?targeting_key
POST request /rest/v2/forecasting/run

Example Request

Forecasting request

{
  "start_time": "2025-10-31T00:00:00Z",
  "end_time": "2025-11-29T00:00:00Z",
  "request_timestamp": "2025-10-13T00:00:00Z",
  "non_targeting_keys": {
    "line_item_type": "BANNER"
  },
  "targeting_modules": {
    "app_site": {
      "any": {},
      "all": {
        "app_name": {
          "any": [
            {
              "value": "leboncoin, petites annonces",
              "comparator": "equals"
            }
          ],
          "all": []
        }
      },
      "none": {}
    },
    "environment": {
      "any": {},
      "all": {
        "environment_type": {
          "any": [
            {
              "value": 1,
              "comparator": "equals"
            }
          ],
          "all": []
        }
      },
      "none": {}
    },
    "exchange": {
      "any": {},
      "all": {
        "inventory_source": {
          "any": [
            {
              "value": "ttx",
              "comparator": "equals"
            },
            {
              "value": "axo",
              "comparator": "equals"
            },
            {
              "value": "adx",
              "comparator": "equals"
            }
          ],
          "all": []
        }
      },
      "none": {}
    },
    "geo": {
      "any": {},
      "all": {
        "country": {
          "any": [
            {
              "value": "USA",
              "comparator": "equals"
            }
          ],
          "all": []
        }
      },
      "none": {}
    },
    "time": {
      "any": {},
      "all": {
        "user_time_of_week": {
          "any": [
            {
              "value": [
                6000,
                6839
              ],
              "comparator": "in_range"
            },
            {
              "value": [
                7440,
                8279
              ],
              "comparator": "in_range"
            }
          ],
          "all": []
        }
      },
      "none": {}
    }
  }
}

To run a forecast:

To generate forecasting data, send a POST request to:

https://{{buzz_key}}.api.beeswax.com/rest/v2/forecasting/run

Example Request Body:

{
  "start_time": "2025-11-29T00:00:00Z",
  "end_time": "2025-12-31T00:00:00Z",
  "request_timestamp": "2025-11-03T00:00:00Z",
  "non_targeting_keys": {
    "line_item_type": "BANNER"
  },
  "targeting_modules": {
    "app_site": {
      "all": {
        "deal_id": {
          "any": [
            {
              "value": "trl/benbidnursedeal",
              "comparator": "equals"
            }
          ]
        }
      }
    },
    "environment": {
      "all": {
        "environment_type": {
          "any": [
            {
              "value": 0,
              "comparator": "equals"
            }
          ]
        }
      }
    },
    "exchange": {
      "all": {
        "inventory_source": {
          "any": [
            {
              "value": "adw",
              "comparator": "equals"
            }
          ]
        }
      }
    },
    "geo": {
      "all": {
        "country": {
          "any": [
            {
              "value": "ABW",
              "comparator": "equals"
            }
          ]
        }
      }
    },
    "platform": {
      "all": {
        "device_type": {
          "any": [
            {
              "value": 3,
              "comparator": "equals"
            }
          ]
        }
      }
    },
    "user": {
      "all": {
        "segment": {
          "any": [
            {
              "value": "alliant-167434",
              "comparator": "equals"
            }
          ]
        }
      }
    }
  }
}

Response Structure

The API returns daily and weekly predictions with confidence intervals:

Response

{
  "results": {
    "support_set_id": "dimensions_v1_audience_v2",
    "predicted_values_daily": [],
    "predicted_values_weekly": []
  },
  "errors": {},
  "warnings": {}
}

Customizing the Request

1. Exclude Specific Targeting

Move modules to the "none" section to exclude them from targeting:

Customizing the request (exclude targeting key)

{
  "geo": {
    "any": {},
    "all": {},
    "none": {
      "country": {
        "any": [
          {
            "value": "ABW",
            "comparator": "equals"
          }
        ]
      }
    }
  }
}

2. Remove Entire Modules

Omit modules you don't need. This example removes app_site and user targeting:

Remove Entire Modules

{
  "start_time": "2025-11-29T00:00:00Z",
  "end_time": "2025-12-31T00:00:00Z",
  "request_timestamp": "2025-11-03T00:00:00Z",
  "non_targeting_keys": {
    "line_item_type": "BANNER"
  },
  "targeting_modules": {
    "environment": {},
    "exchange": {},
    "geo": {},
    "platform": {}
  }
}

Notes:

All time fields use ISO 8601 format (UTC)
Empty "any" and "all" arrays can be omitted for cleaner payloads
Set values to null or empty objects {} to disable specific targeting criteria