---
title: "Request forecast"
method: POST
path: "/forecaster"
tags: ["Forecast"]
---

# Request forecast

`POST /forecaster`

Request a forecast to be started.

## Request body

- union
  - object — A request to perform an availability forecast, i.e., querying the predicted inventory to find the total amount of available (and booked) clicks, impressions, revenue, unique users, and custom events that exist at a given `Priority` level ([weight](https://dev.kevel.com/docs/priorities#priority-fields)). These are calculated by applying the supplied targeting rules or new ads after the delivery of all existing campaigns with priority weights equal to or above the supplied `Priority`. The priority can be specified in two manners. Either by the `Priority` or `PriorityId` fields (only one of them can be defined) or by the priorities that are defined in the Flights when the `NewAds` field is passed. When the `NewAds` field is specified, the `Targeting`, `Priority`, and `PriorityId` fields cannot be, since all the targeting, capping, and priority rules will be encoded in the Flight and Ads passed in `NewAds`. Additionally, if the `NewAds` provided contain a flight that shares the same ID with another one from the Ad Platform inventory, the simulated deliveries to that booked flight will be considered as potentially available for any of the provided Ads from flight. Note that the available revenue is only calculated when the `NewAds` field is provided.
    - `Type` 'available', required
    - `StartDate` string, date-time — Start date of the available forecast from which availability will be checked, as `yyyy-mm-dd'T'HH:mm:SS` or `yyyy-mm-dd` (default time of `00:00:00`), in the passed `TimeZone` or UTC if omitted.
    - `EndDate` string, date-time, required — End date of the available forecast, must be after current date, as `yyyy-mm-dd'T'HH:mm:SS` or `yyyy-mm-dd` (default time of `23:59:59`), in the passed `TimeZone` or UTC if omitted.
    - `TimeZone` string — The time zone of the available forecast's start and end dates ([available time zones](https://www.joda.org/joda-time/timezones.html)). Additionally, day parting is evaluated in the available forecast's time zone.
    - `Targeting` object — The specified targeting for the available forecast.
      - `FreqCapType` 1 | 2 | 3 — The unit of the frequency cap: * _1_: Hour * _2_: Day * _3_: Minute
      - `FreqCapDuration` number — How long the frequency cap should apply.
      - `FreqCap` number — The cap of the frequency cap.
      - `Keywords` string — Keywords as they're defined in flights. Please head to [Keyword Logic](https://dev.kevel.com/docs/keyword-logic) for more details.
      - `ActiveKeywords` string[] — Keywords as they're defined in ads.
      - `GeoTargeting` object[] — Please head to [Geo Targeting](https://dev.kevel.com/reference/create-geo-targeting) for more details.
        - `CountryCode` string, required — The two-character country code.
        - `Region` string — The two-character code for the state, region, or province.
        - `MetroCode` string — The metro code, such as ZIP code.
        - `IsExclude` boolean — Set to 'false' (it's also the default value) or null if you want to target; true if you want to exclude.
      - `DistanceTargeting` object[] — Please head to [Distance Targeting](https://dev.kevel.com/reference/create-geodistance-targeting-geometry) for more details.
        - `Distance` number — The radius of acceptable area from latitude, longitude centre.
        - `Latitude` number — The latitude of the requester source.
        - `Longitude` number — The latitude of the requester source.
      - `SiteZoneTargeting` object[] — Please head to [Site/Zone Targeting](https://dev.kevel.com/reference/create-sitezone-targeting) for more details.
        - `SiteId` number
        - `ZoneId` number
        - `IsExclude` boolean — Whether targeting is to be excluded or included. Defaults to false, so if you leave this blank it'll target the site/zone.
      - `SegmentTargeting` object[] — A list of user segment targeting objects for the availability check.
        - `SegmentId` number
        - `IsExclude` boolean — Whether targeting is to be excluded or included. Defaults to false.
      - `SearchTerms` Items[] — Search term targeting rules for the availability check. Please head to [Search Term Targeting](https://dev.kevel.com/docs/search-term-targeting) for more details. — unresolved $ref
      - `CustomTargeting` string — The custom targeting (Zerkel query) of the flight. Please head to [Custom Targeting](https://dev.kevel.com/docs/custom-targeting) for more details.
      - `DayParting` object[] — Please head to [Day Parting](https://dev.kevel.com/reference/create-day-part) for more details.
        - `StartTime` string, time, required — HH:mm:ss.
        - `EndTime` string, time, required — HH:mm:ss.
        - `WeekDays` string[], required — The days of the week to target.
      - `AdType` union — An id or list of ids of the Ad Sizes / Types to target by. Setting to null is equivalent to a list with all Ad Sizes / Types.
        - number, nullable
        - number[], nullable
      - `TemplateValues` string, json — Creative Template Fields that can be queried via AdQuery. This is a JSON string with a set of variables and their corresponding values (it can be any json supported type). Please head to [AdQuery documentation](https://dev.kevel.com/docs/adquery) for more details.
      - `SkipTemplateValues` boolean — When true, skips AdQuery filtering by ADRs.
    - `Priority` integer — The priority weight at which availability will be calculated, impressions for existing ads with a "lower" priority than this will be considered available. This does not take into consideration ordering and filtering done at the site or channel level.
    - `PriorityId` integer — The ID of a [Kevel Priority](https://dev.kevel.com/docs/priorities) at which availability will be calculated, impressions for existing ads with a "lower" priority than this will be considered available.
    - `NewAds` object[] — The new ad or ads to consider in the availability request.
      - `Id` integer, required — The id of the ad.
      - `StartDate` string, date-time — The start date of the ad, in UTC.
      - `EndDate` string, date-time — The end date of the ad, in UTC.
      - `FrequencyCap` object
        - `Type` 1 | 2 | 3 — The unit of the frequency cap: * _1_: Hour * _2_: Day * _3_: Minute
        - `Duration` number — How long the frequency cap should apply.
        - `Value` number — The cap of the frequency cap.
      - `Flight` object, required — Details of new flight to be used by the ad.
        - `Id` number, required — The id of the flight.
        - `StartDate` string, date-time, required — The start date of the flight, in UTC.
        - `EndDate` string, date-time — The end date of the flight, in UTC. Required for any `GoalType` other than Percentage, Daily Revenue or Monthly Revenue.
        - `TimeZone` string — The flight's time zone to be used for the flight's daily caps, daily goals, and day parting ( [available time zones](https://www.joda.org/joda-time/timezones.html)).
        - `GoalType` 1 | 2 | 3 | 7 | 8 | 9 | 10, required — The metric used to pace the ads. Currently supported goal types are: * _1_: Impressions * _2_: Percentage * _3_: Clicks * _7_: Conversions * _8_: Revenue * _9_: Daily revenue * _10_: Monthly revenue
        - `GoalAmount` number, required — Maximum total of `GoalType` for all Ads related to Flight. This value can also be sent through the `Impressions` field, as that's its equivalent in the ad server Flight API. However, it will always be referenced to as `GoalAmount`.
        - `RateType` 1 | 2 | 3 | 4 | 5 | 6 — The field used to estimate the revenue you have made from your advertisers. Currently supported rate types are: * _1_: Flat * _2_: CPM * _3_: CPC * _4_: CPA View * _5_: CPA Click * _6_: CPA View & Click
        - `Price` number — The amount an advertiser is paying you, based on the `RateType`. It must be no less than 0, or it may be null.
        - `NetworkId` number, required — The id of the network.
        - `PriorityId` number, required — The id of the priority.
        - `KeywordTargeting` union
          - string — The keyword targeting string representation, please head to [Keyword Logic](https://dev.kevel.com/docs/keyword-logic) for more details.
          - object — The keyword targeting set on the flight.
            - `Include` array[]
              - …
            - `Exclude` array[]
              - …
        - `GeoTargeting` Items[] — The location targeting set on the flight — unresolved $ref
        - `DistanceTargeting` Items[] — The distance targeting set on the flight — unresolved $ref
        - `SiteZoneTargeting` Items[] — A list of site/zone targeting objects for the flight. — unresolved $ref
        - `SegmentTargeting` Items[] — A list of user segment targeting objects for the flight. — unresolved $ref
        - `CustomTargeting` string — The custom targeting (Zerkel query) of the flight.
        - `Campaign` object — Details of new campaign to be used by the flight.
          - `Id` number, required — The id of the campaign.
          - `Advertiser` object — The advertiser for the campaign.
            - `Id` number — The id of the advertiser.
            - `PlacementLimit` number — The placement limit that limits how often ads from that advertiser will appear in an ad request.
            - `CapType` 4 — Set to `CapType = 4` (Revenue). Advertisers can only budget cap on the revenue metric.
            - `DailyCapAmount` number — The maximum daily revenue.
            - `LifetimeCapAmount` number — The maximum lifetime revenue.
          - `CapType` 4 — Set to `CapType = 4` (Revenue). Campaigns can only budget cap on the revenue metric.
          - `DailyCapAmount` number — The maximum daily revenue.
          - `LifetimeCapAmount` number — The maximum lifetime revenue.
        - `CapType` 1 | 2 | 3 | 4 — The type of the cap: * _1_: Impression * _2_: Click * _3_: Conversion * _4_: Revenue
        - `DailyCapAmount` number — The maximum number of `CapType` per day.
        - `LifetimeCapAmount` number — The maximum number of `CapType` per lifetime.
        - `DuplicateMode` 1 | 2 | 3 | 4 — The type of the duplicate mode: * _1_: Flight * _2_: Campaign * _3_: Advertiser * _4_: Creative
        - `EcpmOptimization` object
          - `Period` number — Timeframe to optimize for [1 - 90 days].
          - `Multiplier` number — The final eCPM will be multiplied by this amount.
          - `Floor` number — Minimum eCPM.
          - `Ceiling` number — Maximum eCPM.
          - `DefaultEcpm` number — The eCPM that will be used while the Flight is in burn-in mode.
          - `BurnIn` number — Impressions per creative to show before using the calculated eCPM over the default eCPM.
        - `EcpmOverride` number — Sets a manual override to a flight's CPM, e.g. so a Flat Rate flight can compete in an auction priority.
        - `SearchTerms` Items[] — Search term targeting rules for the flight. Please head to [Search Term Targeting](https://dev.kevel.com/docs/search-term-targeting) for more details. — unresolved $ref
        - `BidModifiers` Items[] — Bid modifiers to apply to the flight's effective price for matching ad requests. Please head to [Bid Modifiers](https://dev.kevel.com/docs/bid-modifiers) for more details. — unresolved $ref
      - `Creative` object, required — Details of new creative to be used by the ad.
        - `Id` number, required — The id of the creative.
        - `AdType` union — The type of creative, which correlates to ad size. Setting to null is equivalent to a list with all types.
          - number, nullable
          - number[], nullable
        - `TemplateValues` object — Creative Template Fields that can be queried via AdQuery. This is a map of variable name to an object containing the fields `type` (string) and `value` (json). Please head to [AdQuery documentation](https://dev.kevel.com/docs/adquery) for more details.
        - `SkipTemplateValues` boolean — When true, skips AdQuery filtering by ADRs.
      - `Price` number — The amount an advertiser is paying you, based on the Flight's `RateType`. It must be no less than 0, or it may be null. When set, this value will take precedence over the Flight's price value for this Ad.
      - `ActiveKeywords` string[] — Active keywords for keyword targeting.
      - `CustomTargeting` string — A string for custom targeting using the [Zerkel Language](https://dev.kevel.com/docs/zerkel-queries).
      - `SiteZoneTargeting` object — Specific site and zone id targeting.
        - `SiteId` number
        - `ZoneId` number
      - `SegmentTargeting` Items[] — A list of user segment targeting objects for the ad. — unresolved $ref
      - `IsGoalOverride` boolean — Whether you are overriding the goal on the Ad.
      - `GoalType` 1 | 2 | 3 | 7 | 8 | 9 | 10 — If you are overriding the flight's goal, sets the target goal metric for the Ad. Currently supported goal types are: * _1_: Impressions * _2_: Percentage * _3_: Clicks * _7_: Conversions * _8_: Revenue * _9_: Daily revenue * _10_: Monthly revenue
      - `GoalAmount` number — If you are overriding the flight's goal, sets the maximum total of `GoalType` for this Ad.
      - `SearchTerms` Items[] — Search term targeting rules for the ad. Please head to [Search Term Targeting](https://dev.kevel.com/docs/search-term-targeting) for more details. — unresolved $ref
    - `Modifiers` object — Manual Forecast Modifiers to apply to this forecast request. Currently, only Traffic Modifiers are supported. Traffic modifiers operate at the Ad Request level and make it possible to manually modify the volume of Ad Request in a certain date range and, optionally, that follow a targeting rule.
      - `Traffic` union[] — The Traffic Modifiers to apply, can be a `AdRequestCount`, `AdRequestMultiplier`, or `PlacementOpportunityRatio`.
        - union
          - 0 — unresolved $ref
          - 1 — unresolved $ref
          - 2 — unresolved $ref
    - `Params` object
      - `Sampling` integer — The level of sampling to use (between 0 and 3). 3 provides the quickest response and 0 for the highest accuracy. By default this is set to 3.
      - `Responsiveness` integer — The responsiveness level to use (between 0 and 3). 3 provides the quickest response at the expense of less intermediate results and 0 results in more intermediate results but at the expense of performance. By default this is set to 1.
      - `GroupBy` string[] — Break the forecast results down by the given `GroupBy` keys. Some caution should be used when choosing the `GroupBy` keys, as some keys may have thousands of possible values and can produce very large responses. For more details and the list of [available keys](https://dev.kevel.com/reference/kevel-forecast-overview#group-by-fields), see this [section](https://dev.kevel.com/reference/kevel-forecast-overview#grouping-by-and-time-zone-considerations). When grouping by fields that are arrays, the default behavior is to group by the whole set. Alternatively, it is possible to expand the elements of the array and group by each of them by suffixing the field name with `[]`, or by using the singular of the field (if it is one of the known array fields). It's also possible to expand the key-value pairs of `$user.custom` by suffixing the field name with `{}`.
      - `NotifyUrl` string, url — The URL for the forecast status update callback. The payload is documented in the "callback" section.
      - `TimeZone` string — The time zone to use when grouping results with a time-related key ([available time zones](https://www.joda.org/joda-time/timezones.html)).
      - `DynamicMultiWinnerImpressionRatio` boolean, nullable — Warning: Using a different value other than the default will substantially increase the forecast duration, only set this value when exploring different winner ratios. When undefined it uses the default value for the network. When `true` uses the projected impressions based on historical data instead of relying on a fixed ratio. Takes precedence over the `MultiWinnerImpressionRatio`.
      - `MultiWinnerImpressionRatio` number, nullable — Warning: Using a different value other than the default will substantially increase the forecast duration, only set this value when exploring different winner ratios. When undefined it uses the default value for the network. A value from 0.0 to 1.0 that represents the ratio to select the percentage of winners for multi-winner requests. The ratio is applied to the Placement's `count` and rounded up to the nearest value. The resulting value is clamped between 1 and the placement's count. e.g., for a ratio of 0, the maximum number of opportunities to consider for that placement will be 1.
      - `Include` object — Request additional data to be included in the forecast results.
        - `Events` number[] — A list of custom event ids to include in the forecast results. By default, no custom events are included. Currently, supported event types are: * _1_: View Conversion * _2_: Click Conversion * _3_: Server to Server Conversion
        - `Metrics` object — Per-metric aggregations to compute over winning ads. The key is a user-chosen name that appears verbatim in the response under each result block's `metrics` map. Currently, supports only `winningBid`.
      - `BookedBy` string[] — Shows the available forecast **booked** results by a subset of `advertiser`, `campaign`, `flight` or `ad`. If more than one element is specified, the results are shown in a hierarchical tree.
      - `ResultsBy` string[] — Shows the forecast results by a subset of `advertiser`, `campaign`, `flight` or `ad`. If more than one element is specified, the results are shown in a hierarchical tree. If any of the `NewAds` are missing advertiser or campaign ids, then `ResultsBy` should include at least one of the non-missing levels - in this case, missing ids will be shown as `-1` in the hierarchical tree.
      - `FilterGroupBy` string — Filter the forecast grouped results breakdown by the given rule (Zerkel query) at the inventory level. This rule operates on the following set of numeric fields for the Available forecast type: `impressions`, `clicks`, `uniqueUsers`, `bookedImpressions`, `bookedClicks` and `bookedUniqueUsers`. These fields act over the total results of each group-by group - for example, a rule `impressions > 10` will filter all groups with less than 10 total available impressions out. An extra key, `groupedFiltered`, is added to the forecast result containing all the results that were filtered out by the rule. If used in combination with the `ResultsBy` parameter, the `advertiser`, `campaign` and `flight` levels won't include the `uniqueUsers`count.
  - object — A request to perform a deliverability forecast, returning counts for clicks, impressions, revenue, unique users, and custom events for the `NewAds` specified. A deliverability forecast simulates how a new set of ads will run, taking into account and competing against all ads already running in the network (i.e., the result will consider the fact the `NewAds` may consume impressions away from existing campaigns).
    - `Type` 'deliverable', required
    - `EndDate` string, date-time, required — End date for results of the deliverable forecast, must be after current date, as `yyyy-mm-dd'T'HH:mm:SS` or `yyyy-mm-dd` (default time of `23:59:59`), in the passed `TimeZone` or UTC if omitted.
    - `NewAds` 0[], required — The new ad or ads to consider in the deliverability request. — unresolved $ref
    - `Modifiers` Modifiers — unresolved $ref
  - object — A request to perform a forecast for all existing running ads, i.e., the total predicted amount of clicks, impressions, revenue, unique users, and custom events for all running ads in the network.
    - `Type` 'existing', required
    - `EndDate` string, date-time, required — End date for results of the existing forecast, must be after current date, as `yyyy-mm-dd'T'HH:mm:SS` or `yyyy-mm-dd` (default time of `23:59:59`), in the passed `TimeZone` or UTC if omitted.
    - `Modifiers` Modifiers — unresolved $ref

## Response `202`

The forecast request was accepted successfully.

- Schema — unresolved $ref

## Other responses

- `400` — Error response, containing error message.

---

[API](https://skmtc.dev/kevel/apis/engine-apis.md) · [All operations](https://skmtc.dev/kevel/apis/engine-apis/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/kevel/engine-apis/revisions/0ca55f45aa7d/schema)