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.

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