{"openapi":"3.1.0","info":{"title":"Forecast API","description":"The Kevel Forecast API","version":"1"},"servers":[{"url":"https://api.kevel.co/v1"}],"security":[{"ApiKeyAuth":[]}],"paths":{"/forecaster":{"get":{"tags":["Forecast"],"summary":"List forecasts","description":"List information about enqueued and running forecasts.","parameters":[{"name":"details","in":"query","required":false,"description":"Whether to include the details and partial results of running forecasts.","schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"Information about enqueued and running forecasts.","content":{"application/json":{"schema":{"type":"object","properties":{"queue":{"type":"number","description":"The number of forecasts that are queued (i.e. haven't started executing yet).\n","example":0},"executing":{"type":"number","description":"The number of forecasts that are currently executing.\n","example":1},"details":{"type":"array","nullable":true,"description":"The detailed list of active forecasts. Only included if `details` is true.\n","items":{"title":"Forecast List Response","allOf":[{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/0"},{"properties":{"fracProgress":{"type":"number","description":"The fractional progress of the forecast request. It can be a number between 0.0 and 1.0. A forecast with progress 1.0\nis finished.\n","example":0.33},"startTS":{"type":"number","description":"The timestamp (in milliseconds) at which this forecast started processing. It is only available if there are partial results available (i.e., the progress is between 0% and 100%, exclusively).\n","example":1741783201239},"lastUpdateTS":{"type":"number","description":"The timestamp (in milliseconds) at which the information for the forecast request was last updated. It is only available if there are partial results available (i.e., the progress is between 0% and 100%, exclusively).\n","example":1741783222833},"request":{"type":"object","oneOf":[{"$ref":"#/paths/~1forecaster/post/requestBody/content/application~1json/schema/oneOf/0"},{"$ref":"#/paths/~1forecaster/post/requestBody/content/application~1json/schema/oneOf/2"},{"$ref":"#/paths/~1forecaster/post/requestBody/content/application~1json/schema/oneOf/1"}],"description":"The request that originated this forecast."},"result":{"description":"The result object.\n","oneOf":[{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/0"},{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1"},{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/2"},{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/3"}]}}}]}}}}}}}}},"post":{"tags":["Forecast"],"summary":"Request forecast","description":"Request a forecast to be started.","requestBody":{"description":"The JSON object that describes the forecast request.","required":true,"content":{"application/json":{"schema":{"oneOf":[{"title":"Available Forecast Request","type":"object","description":"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](doc:priorities#priority-fields)).\nThese 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`.\nThe 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.\nWhen 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`.\nAdditionally, 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.\nNote that the available revenue is only calculated when the `NewAds` field is provided.\n","required":["EndDate","Type"],"properties":{"Type":{"type":"string","enum":["available"]},"StartDate":{"type":"string","format":"date-time","description":"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.\n"},"EndDate":{"type":"string","format":"date-time","description":"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":{"default":"UTC","type":"string","description":"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.\n"},"Targeting":{"type":"object","allOf":[{"type":"object","properties":{"FreqCapType":{"type":"number","enum":[1,2,3],"description":"The unit of the frequency cap:\n\n  * _1_: Hour\n  * _2_: Day\n  * _3_: Minute\n"},"FreqCapDuration":{"type":"number","description":"How long the frequency cap should apply.\n"},"FreqCap":{"type":"number","description":"The cap of the frequency cap.\n"},"Keywords":{"type":"string","example":"dodge\ntruck","description":"Keywords as they're defined in flights. Please head to [Keyword Logic](doc:keyword-logic) for more details.\n"},"ActiveKeywords":{"type":"array","description":"Keywords as they're defined in ads.\n","items":{"type":"string"},"example":["tacocat","potato cat"]},"GeoTargeting":{"type":"array","items":{"type":"object","properties":{"CountryCode":{"type":"string","description":"The two-character country code.\n","example":"US"},"Region":{"type":"string","description":"The two-character code for the state, region, or province.\n","example":"NY"},"MetroCode":{"type":"string","description":"The metro code, such as ZIP code.\n","example":"10001"},"CityGeonameId":{"type":"integer","description":"The numeric GeoNames ID for city-level targeting. This value is used for matching, not the city name. Please\nhead to [Geo Targeting](ref:create-geo-targeting) for more details.\n","example":5128581},"IsExclude":{"type":"boolean","description":"Set to 'false' (it's also the default value) or null if you want to target; true if you want to exclude."}},"required":["CountryCode"]},"description":"Please head to [Geo Targeting](ref:create-geo-targeting) for more details.\n"},"DistanceTargeting":{"type":"array","items":{"type":"object","description":"For the time being, we don't support StreetAddress.\n","properties":{"Distance":{"type":"number","description":"The radius of acceptable area from latitude, longitude centre.\n","example":20},"Latitude":{"type":"number","description":"The latitude of the requester source.\n","example":41.40338},"Longitude":{"type":"number","description":"The latitude of the requester source.\n","example":2.17403}}},"description":"Please head to [Distance Targeting](ref:create-geodistance-targeting-geometry) for more details.\n"},"SiteZoneTargeting":{"type":"array","items":{"type":"object","properties":{"SiteId":{"type":"number","example":1121285},"ZoneId":{"type":"number","example":247884},"IsExclude":{"type":"boolean","description":"Whether targeting is to be excluded or included. Defaults to false, so if you leave this blank it'll target the site/zone."}}},"description":"Please head to [Site/Zone Targeting](ref:create-sitezone-targeting) for more details.\n"},"SegmentTargeting":{"type":"array","items":{"type":"object","properties":{"SegmentId":{"type":"number","example":123456789},"IsExclude":{"type":"boolean","default":false,"description":"Whether targeting is to be excluded or included. Defaults to false."},"Category":{"type":"string","example":"Demographics","description":"The category the segment belongs to. Include segments are matched OR-within-category and AND-across-categories: a request must match at least one included segment in every targeted category. Optional; segments with no category are treated as a single uncategorized group, so all-one-category (or no category) reduces to flat OR behavior. Ignored for excluded segments, because exclude is a flat deny."}}},"description":"A list of user segment targeting objects for the availability check.\n"},"SearchTerms":{"type":"array","items":{"$ref":"#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/put/requestBody/content/application~1json/schema/properties/flights/items/properties/searchTerms/items"},"description":"Search term targeting rules for the availability check. Please head to [Search Term Targeting](doc:search-term-targeting) for more details.\n"},"CustomTargeting":{"type":"string","description":"The custom targeting (Zerkel query) of the flight. Please head to [Custom Targeting](doc:custom-targeting) for more details.\n","example":"(age > 25 and gender = \"male\")"},"DayParting":{"type":"array","items":{"type":"object","properties":{"StartTime":{"type":"string","format":"time","description":"HH:mm:ss."},"EndTime":{"type":"string","format":"time","description":"HH:mm:ss."},"WeekDays":{"type":"array","items":{"type":"string","enum":["MO","TU","WE","TH","FR","SA","SU"]},"description":"The days of the week to target.\n","example":["TH","FR"]}},"required":["StartTime","EndTime","WeekDays"]},"description":"Please head to [Day Parting](ref:create-day-part) for more details.\n"},"AdType":{"oneOf":[{"type":"number","nullable":true},{"type":"array","nullable":true,"items":{"type":"number"},"minItems":1}],"description":"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.\n"},"TemplateValues":{"type":"string","format":"json","example":"{\"ctString\":\"A string goes here\",\"ctExternalFile\":\"https://cdn.com/ad.gif\"}","description":"Creative Template Fields that can be queried via AdQuery.\nThis is a JSON string with a set of variables and their corresponding values (it can be any json supported type).\nPlease head to [AdQuery documentation](doc:adquery) for more details.\n"},"SkipTemplateValues":{"type":"boolean","default":true,"description":"When true, skips AdQuery filtering by ADRs.\n"}}}],"description":"The specified targeting for the available forecast."},"Priority":{"type":"integer","description":"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.\n"},"PriorityId":{"type":"integer","description":"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.\n"},"NewAds":{"type":"array","description":"The new ad or ads to consider in the availability request.\n","items":{"allOf":[{"title":"New Ad","type":"object","properties":{"Id":{"type":"integer","description":"The id of the ad.","example":123337},"StartDate":{"type":"string","format":"date-time","description":"The start date of the ad, in UTC.\n","example":null},"EndDate":{"type":"string","format":"date-time","description":"The end date of the ad, in UTC.\n","example":null},"FrequencyCap":{"allOf":[{"type":"object","properties":{"Type":{"type":"number","enum":[1,2,3],"description":"The unit of the frequency cap:\n\n  * _1_: Hour\n  * _2_: Day\n  * _3_: Minute\n"},"Duration":{"type":"number","description":"How long the frequency cap should apply.\n"},"Value":{"type":"number","description":"The cap of the frequency cap.\n"}}},{"example":{"Type":1,"Duration":20,"Value":2}}]},"Flight":{"allOf":[{"type":"object","properties":{"Id":{"type":"number","description":"The id of the flight.\n","example":346},"StartDate":{"type":"string","format":"date-time","description":"The start date of the flight, in UTC.\n","example":"2022-11-17T00:00:00"},"EndDate":{"type":"string","format":"date-time","description":"The end date of the flight, in UTC.\nRequired for any `GoalType` other than Percentage, Daily Revenue or Monthly Revenue.\n","example":"2022-11-20T23:59:59"},"TimeZone":{"default":"UTC","type":"string","description":"The flight's time zone to be used for the flight's daily caps, daily goals, and day parting (\n[available time zones](https://www.joda.org/joda-time/timezones.html)).\n"},"GoalType":{"type":"number","enum":[1,2,3,7,8,9,10],"description":"The metric used to pace the ads. Currently supported goal types are:\n\n  * _1_: Impressions\n  * _2_: Percentage\n  * _3_: Clicks\n  * _7_: Conversions\n  * _8_: Revenue\n  * _9_: Daily revenue\n  * _10_: Monthly revenue\n","example":2},"GoalAmount":{"type":"number","description":"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`.\n","example":150000},"RateType":{"type":"number","enum":[1,2,3,4,5,6],"description":"The field used to estimate the revenue you have made from your advertisers. Currently supported rate types are:\n\n  * _1_: Flat\n  * _2_: CPM\n  * _3_: CPC\n  * _4_: CPA View\n  * _5_: CPA Click\n  * _6_: CPA View & Click\n","example":2},"Price":{"type":"number","description":"The amount an advertiser is paying you, based on the `RateType`.\nIt must be no less than 0, or it may be null.\n","example":100},"NetworkId":{"type":"number","description":"The id of the network.\n","example":11379},"PriorityId":{"type":"number","description":"The id of the priority.\n","example":221170},"KeywordTargeting":{"oneOf":[{"type":"string","description":"The keyword targeting string representation, please head to [Keyword Logic](doc:keyword-logic) for more details.","example":"keyword1,keyword2\nkeyword3\n!keyword1,keyword2"},{"type":"object","description":"The keyword targeting set on the flight.\n","properties":{"Include":{"type":"array","items":{"type":"array","items":{"type":"string"}}},"Exclude":{"type":"array","items":{"type":"array","items":{"type":"string"}}}},"example":{"Include":[["keyword1","keyword2"],["keyword3"]],"Exclude":[["keyword1","keyword2"]]}}]},"GeoTargeting":{"type":"array","items":{"$ref":"#/paths/~1forecaster/post/requestBody/content/application~1json/schema/oneOf/0/properties/Targeting/allOf/0/properties/GeoTargeting/items"},"description":"The location targeting set on the flight\n","example":[{"CountryCode":"US"}]},"DistanceTargeting":{"type":"array","items":{"$ref":"#/paths/~1forecaster/post/requestBody/content/application~1json/schema/oneOf/0/properties/Targeting/allOf/0/properties/DistanceTargeting/items"},"description":"The distance targeting set on the flight\n","example":[{"Latitude":41.40338}]},"SiteZoneTargeting":{"type":"array","items":{"$ref":"#/paths/~1forecaster/post/requestBody/content/application~1json/schema/oneOf/0/properties/Targeting/allOf/0/properties/SiteZoneTargeting/items"},"description":"A list of site/zone targeting objects for the flight.\n"},"SegmentTargeting":{"type":"array","items":{"$ref":"#/paths/~1forecaster/post/requestBody/content/application~1json/schema/oneOf/0/properties/Targeting/allOf/0/properties/SegmentTargeting/items"},"description":"A list of user segment targeting objects for the flight.\n"},"CustomTargeting":{"type":"string","description":"The custom targeting (Zerkel query) of the flight.\n"},"DayParting":{"type":"array","items":{"allOf":[{"$ref":"#/paths/~1forecaster/post/requestBody/content/application~1json/schema/oneOf/0/properties/Targeting/allOf/0/properties/DayParting/items"},{"example":{"StartTime":"12:00:00","EndTime":"17:00:00","WeekDays":["SA","SU"]}}]}},"FrequencyCap":{"allOf":[{"$ref":"#/paths/~1forecaster/post/requestBody/content/application~1json/schema/oneOf/0/properties/NewAds/items/allOf/0/properties/FrequencyCap/allOf/0"},{"example":{"Type":1,"Duration":20,"Value":2}}]},"Campaign":{"allOf":[{"type":"object","properties":{"Id":{"type":"number","description":"The id of the campaign.\n","example":123456789},"FrequencyCap":{"allOf":[{"$ref":"#/paths/~1forecaster/post/requestBody/content/application~1json/schema/oneOf/0/properties/NewAds/items/allOf/0/properties/FrequencyCap/allOf/0"},{"example":{"Type":1,"Duration":20,"Value":2}},{"description":"The frequency cap to apply to all ads under the campaign.\n"}]},"Advertiser":{"allOf":[{"type":"object","properties":{"Id":{"type":"number","description":"The id of the advertiser.\n","example":123456789},"FrequencyCap":{"allOf":[{"$ref":"#/paths/~1forecaster/post/requestBody/content/application~1json/schema/oneOf/0/properties/NewAds/items/allOf/0/properties/FrequencyCap/allOf/0"},{"example":{"Type":1,"Duration":20,"Value":2}}]},"PlacementLimit":{"type":"number","description":"The placement limit that limits how often ads from that advertiser will appear in an ad request.\n"},"CapType":{"type":"number","enum":[4],"description":"Set to `CapType = 4` (Revenue). Advertisers can only budget cap on the revenue metric.\n"},"DailyCapAmount":{"type":"number","description":"The maximum daily revenue.\n"},"LifetimeCapAmount":{"type":"number","description":"The maximum lifetime revenue.\n"}}},{"description":"The advertiser for the campaign.\n"}]},"CapType":{"type":"number","enum":[4],"description":"Set to `CapType = 4` (Revenue). Campaigns can only budget cap on the revenue metric.\n"},"DailyCapAmount":{"type":"number","description":"The maximum daily revenue.\n"},"LifetimeCapAmount":{"type":"number","description":"The maximum lifetime revenue.\n"}},"required":["Id"]},{"description":"Details of new campaign to be used by the flight.\n"}]},"CapType":{"type":"number","enum":[1,2,3,4],"description":"The type of the cap:\n\n  * _1_: Impression\n  * _2_: Click\n  * _3_: Conversion\n  * _4_: Revenue\n"},"DailyCapAmount":{"type":"number","description":"The maximum number of `CapType` per day.\n"},"LifetimeCapAmount":{"type":"number","description":"The maximum number of `CapType` per lifetime.\n"},"DuplicateMode":{"type":"number","enum":[1,2,3,4],"description":"The type of the duplicate mode:\n\n  * _1_: Flight\n  * _2_: Campaign\n  * _3_: Advertiser\n  * _4_: Creative\n"},"EcpmOptimization":{"type":"object","properties":{"Period":{"type":"number","description":"Timeframe to optimize for [1 - 90 days].\n","default":7},"Multiplier":{"type":"number","description":"The final eCPM will be multiplied by this amount.\n","default":1},"Floor":{"type":"number","description":"Minimum eCPM.\n"},"Ceiling":{"type":"number","description":"Maximum eCPM.\n"},"DefaultEcpm":{"type":"number","description":"The eCPM that will be used while the Flight is in burn-in mode.\n"},"BurnIn":{"type":"number","description":"Impressions per creative to show before using the calculated eCPM over the default eCPM.\n","default":2400}}},"EcpmOverride":{"type":"number","description":"Sets a manual override to a flight's CPM, e.g. so a Flat Rate flight can compete in an auction priority.\n"},"SearchTerms":{"type":"array","items":{"$ref":"#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/put/requestBody/content/application~1json/schema/properties/flights/items/properties/searchTerms/items"},"description":"Search term targeting rules for the flight. Please head to [Search Term Targeting](doc:search-term-targeting) for more details.\n"},"BidModifiers":{"type":"array","items":{"$ref":"#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/put/requestBody/content/application~1json/schema/properties/flights/items/properties/bidModifiers/items"},"description":"Bid modifiers to apply to the flight's effective price for matching ad requests.\nPlease head to [Bid Modifiers](doc:bid-modifiers) for more details.\n"},"isCompanion":{"type":"boolean","default":false,"description":"Marks a companion flight. When true and one of the flight's ads wins a placement, the forecast co-allocates\nthe flight's other ads across the request's remaining placements.\n","example":false}},"required":["Id","StartDate","GoalType","GoalAmount","NetworkId","PriorityId"]},{"description":"Details of new flight to be used by the ad.\n"}]},"Creative":{"allOf":[{"type":"object","properties":{"Id":{"type":"number","description":"The id of the creative.\n","example":12234},"AdType":{"oneOf":[{"type":"number","nullable":true,"example":4649},{"type":"array","nullable":true,"example":[4649,4650],"items":{"type":"number"},"minItems":1}],"description":"The type of creative, which correlates to ad size. Setting to null is equivalent to a list with all types.\n"},"TemplateValues":{"type":"object","description":"Creative Template Fields that can be queried via AdQuery.\nThis is a map of variable name to an object containing the fields `type` (string) and `value` (json).\nPlease head to [AdQuery documentation](doc:adquery) for more details.\n","additionalProperties":{"x-additionalPropertiesName":"<VARIABLE-NAME>","type":"object","properties":{"Type":{"type":"string","enum":["String","Number","Array"],"description":"The type of the field.\n","example":"Number"},"Value":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"array","items":{"type":"string"}}],"description":"The value of the field.\n","example":12345}}}},"SkipTemplateValues":{"type":"boolean","default":false,"description":"When true, skips AdQuery filtering by ADRs.\n"}},"required":["Id"]},{"description":"Details of new creative to be used by the ad.\n"}]},"Price":{"type":"number","description":"The amount an advertiser is paying you, based on the Flight's `RateType`.\nIt must be no less than 0, or it may be null.\nWhen set, this value will take precedence over the Flight's price value for this Ad.\n","example":100},"ActiveKeywords":{"type":"array","items":{"type":"string"},"description":"Active keywords for keyword targeting.\n","example":null},"CustomTargeting":{"type":"string","description":"A string for custom targeting using the [Zerkel Language](doc:zerkel-queries).\n","example":"[\"order_confirmation\"] contains screen"},"SiteZoneTargeting":{"description":"Specific site and zone id targeting.\n","type":"object","properties":{"SiteId":{"type":"number","example":1121285},"ZoneId":{"type":"number","example":247884}},"example":{"SiteId":1134156}},"SegmentTargeting":{"type":"array","items":{"$ref":"#/paths/~1forecaster/post/requestBody/content/application~1json/schema/oneOf/0/properties/Targeting/allOf/0/properties/SegmentTargeting/items"},"description":"A list of user segment targeting objects for the ad.\n"},"IsGoalOverride":{"type":"boolean","example":true,"description":"Whether you are overriding the goal on the Ad.\n"},"GoalType":{"type":"number","enum":[1,2,3,7,8,9,10],"description":"If you are overriding the flight's goal, sets the target goal metric for the Ad.\nCurrently supported goal types are:\n\n  * _1_: Impressions\n  * _2_: Percentage\n  * _3_: Clicks\n  * _7_: Conversions\n  * _8_: Revenue\n  * _9_: Daily revenue\n  * _10_: Monthly revenue\n","example":2},"GoalAmount":{"type":"number","description":"If you are overriding the flight's goal, sets the maximum total of `GoalType` for this Ad.\n","example":150000},"SearchTerms":{"type":"array","items":{"$ref":"#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/put/requestBody/content/application~1json/schema/properties/flights/items/properties/searchTerms/items"},"description":"Search term targeting rules for the ad. Please head to [Search Term Targeting](doc:search-term-targeting) for more details.\n"}},"required":["Id","Flight","Creative"]}]}},"Modifiers":{"type":"object","description":"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.\n","properties":{"Traffic":{"type":"array","description":"The Traffic Modifiers to apply, can be a `AdRequestCount`, `AdRequestMultiplier`, or `PlacementOpportunityRatio`.","items":{"oneOf":[{"$ref":"#/paths/~1forecaster~1modifiers~1traffic/post/requestBody/content/application~1json/schema/oneOf/0"},{"$ref":"#/paths/~1forecaster~1modifiers~1traffic/post/requestBody/content/application~1json/schema/oneOf/1"},{"$ref":"#/paths/~1forecaster~1modifiers~1traffic/post/requestBody/content/application~1json/schema/oneOf/2"}]}}}},"Params":{"allOf":[{"type":"object","properties":{"Sampling":{"default":3,"type":"integer","description":"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.\n"},"Responsiveness":{"default":1,"type":"integer","description":"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.\n"},"GroupBy":{"type":"array","items":{"type":"string"},"description":"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](ref:kevel-forecast-overview#group-by-fields), see this [section](ref:kevel-forecast-overview#grouping-by-and-time-zone-considerations).\nWhen 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).\nIt's also possible to expand the key-value pairs of `$user.custom` by suffixing the field name with `{}`.\n","example":["$datetime.dayofweek"]},"NotifyUrl":{"type":"string","format":"url","description":"The URL for the forecast status update callback. The payload is documented in the \"callback\" section.\n","example":["http://example.com/endpoint"]},"TimeZone":{"default":"UTC","type":"string","description":"The time zone to use when grouping results with a time-related key ([available time zones](https://www.joda.org/joda-time/timezones.html)).\n"},"DynamicMultiWinnerImpressionRatio":{"type":"boolean","nullable":true,"description":"Warning: Using a different value other than the default will substantially increase the forecast duration, only set this value when exploring different winner ratios.\nWhen undefined it uses the default value for the network.\nWhen `true` uses the projected impressions based on historical data instead of relying on a fixed ratio. Takes precedence over the `MultiWinnerImpressionRatio`.\n","example":null},"MultiWinnerImpressionRatio":{"type":"number","nullable":true,"description":"Warning: Using a different value other than the default will substantially increase the forecast duration, only set this value when exploring different winner ratios.\nWhen undefined it uses the default value for the network.\nA value from 0.0 to 1.0 that represents the ratio to select the percentage of winners for multi-winner requests.\nThe 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.\n","example":null},"Include":{"type":"object","description":"Request additional data to be included in the forecast results.\n","properties":{"Events":{"type":"array","items":{"type":"number","enum":[1,2,3]},"description":"A list of custom event ids to include in the forecast results. By default, no custom events are included. Currently, supported event types are:\n  * _1_: View Conversion\n  * _2_: Click Conversion\n  * _3_: Server to Server Conversion\n","example":[3]},"Metrics":{"type":"object","description":"Per-metric aggregations to compute over winning ads. The key is a user-chosen name that\nappears verbatim in the response under each result block's `metrics` map. Currently, supports only\n`winningBid`.\n","additionalProperties":{"title":"Metric Specification","type":"object","description":"Defines a single metric to compute. `rateType` is required when `source == winningBid`.\n","required":["source","aggregation"],"properties":{"source":{"type":"string","enum":["winningBid"],"description":"The metric source.\n* _winningBid_: the bid price of winning ads, filtered by `rateType`.\n"},"rateType":{"type":"integer","enum":[1,2,3,4,5,6],"description":"Kevel rate-type encoding. Required when `source == winningBid`.\n\n* _1_: Flat\n* _2_: CPM\n* _3_: CPC\n* _4_: CPAView\n* _5_: CPAClick\n* _6_: CPABoth\n"},"aggregation":{"type":"string","enum":["avg"],"description":"Aggregation kind. Currently, only `avg` is supported.\n"}}},"example":{"winningBidCPM":{"source":"winningBid","rateType":2,"aggregation":"avg"}}}}}}},{"type":"object","properties":{"BookedBy":{"type":"array","items":{"type":"string","enum":["advertiser","campaign","flight","ad"]},"description":"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.\n","example":[["advertiser","flight"],"flight"]}}},{"type":"object","properties":{"ResultsBy":{"type":"array","items":{"type":"string","enum":["advertiser","campaign","flight","ad"]},"description":"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.\nIf 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.\n","example":[["advertiser","flight"],"flight"]}}},{"type":"object","properties":{"FilterGroupBy":{"type":"string","description":"Filter the forecast grouped results breakdown by the given rule (Zerkel query) at the inventory level.\nThis rule operates on the following set of numeric fields for the Available forecast type: `impressions`,\n`clicks`, `uniqueUsers`, `bookedImpressions`, `bookedClicks` and `bookedUniqueUsers`. These fields\nact over the total results of each group-by group - for example, a rule `impressions > 10` will filter\nall groups with less than 10 total available impressions out. An extra key, `groupedFiltered`, is added to\nthe forecast result containing all the results that were filtered out by the rule. If used in combination\nwith the `ResultsBy` parameter, the `advertiser`, `campaign` and `flight` levels won't include the\n`uniqueUsers`count.\n","example":"bookedImpressions < 100 and bookedUniqueUsers < 100 or impressions >= 1000"}}}]}}},{"title":"Deliverable Forecast Request","type":"object","description":"A request to perform a deliverability forecast, returning counts for clicks, impressions, revenue, unique users, and custom events for the `NewAds` specified.\nA 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).\n","required":["Type","EndDate","NewAds"],"properties":{"Type":{"type":"string","enum":["deliverable"]},"EndDate":{"type":"string","format":"date-time","description":"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.\n","example":"2022-11-17"},"NewAds":{"type":"array","description":"The new ad or ads to consider in the deliverability request.\n","items":{"allOf":[{"$ref":"#/paths/~1forecaster/post/requestBody/content/application~1json/schema/oneOf/0/properties/NewAds/items/allOf/0"}]}},"Modifiers":{"$ref":"#/paths/~1forecaster/post/requestBody/content/application~1json/schema/oneOf/0/properties/Modifiers"},"Params":{"allOf":[{"$ref":"#/paths/~1forecaster/post/requestBody/content/application~1json/schema/oneOf/0/properties/Params/allOf/0"},{"$ref":"#/paths/~1forecaster/post/requestBody/content/application~1json/schema/oneOf/0/properties/Params/allOf/2"},{"$ref":"#/paths/~1forecaster/post/requestBody/content/application~1json/schema/oneOf/2/properties/Params/allOf/2"}]}}},{"title":"Existing Forecast Request","type":"object","description":"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.\n","properties":{"Type":{"type":"string","enum":["existing"]},"EndDate":{"type":"string","format":"date-time","description":"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.\n","example":"2022-11-17"},"Modifiers":{"$ref":"#/paths/~1forecaster/post/requestBody/content/application~1json/schema/oneOf/0/properties/Modifiers"},"Params":{"allOf":[{"$ref":"#/paths/~1forecaster/post/requestBody/content/application~1json/schema/oneOf/0/properties/Params/allOf/0"},{"type":"object","properties":{"ResultsBy":{"type":"array","items":{"type":"string","enum":["advertiser","campaign","flight","ad"]},"description":"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.\n","example":[["advertiser","flight"],"flight"]}}},{"type":"object","properties":{"FilterGroupBy":{"type":"string","description":"Filter the forecast grouped results breakdown by the given rule (Zerkel query) at the ad level.\nThis rule operates on the following set of numeric fields for the Deliverable and Existing forecast types:\n`impressions`, `clicks`, `uniqueUsers`, `adId`, `flightId`, `campaignId` and `advertiserId`. Additionally,\nthe following fields are available for filtering reserved campaigns: `reservedAdId`, `reservedFlightId` and\n`reservedCampaignId`. These fields act over the results of each ad in the group-by group - for example, a\nrule `impressions > 10` will filter all ads with less than 10 available impressions out. An extra key,\n`groupedFiltered`, is added to the forecast result containing all the ads that were filtered out by the\nrule. If used in combination with the `ResultsBy` parameter, the `advertiser`, `campaign` and `flight`\nlevels won't include the `uniqueUsers` count.\n","example":"bookedImpressions < 100 and bookedUniqueUsers < 100 or impressions >= 1000"}}}]}},"required":["Type","EndDate"]}]}}}},"callbacks":{"Forecast status update":{"{$request.body#/params/notifyUrl}":{"post":{"summary":"This notification is emitted when the forecast transitions to a final state.","requestBody":{"description":"The callback notification body.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"The id of the requested forecast. It must be used when querying for the forecast results.\n","example":"1978ad40-97da-403e-ad5d-c3e71c75a593"},"timestamp":{"type":"string","format":"date-time","description":"The time at which this notification was emitted - a UTC datetime. Example: `2024-01-25T12:30:09.985Z`.\n","example":"2024-01-25T12:30:09.985Z"},"status":{"type":"string","enum":["enqueued","started","cancelled","partial","finished","failed"],"description":"The status of the forecast execution. Currently, the only possible values are `finished` and `failed`.\n","example":"finished"},"desc":{"type":"string","description":"A textual description of the forecast execution status.\n","example":"Forecast is finished"}}}}}},"responses":{"200":{"description":"Notification successfully received."}}}}}},"responses":{"202":{"description":"The forecast request was accepted successfully.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema"}]}}}},"400":{"description":"Error response, containing error message.","content":{"application/json":{"schema":{"title":"Error Response","type":"object","properties":{"errorMessage":{"type":"string","example":"The request content was malformed:\nError at '.': The end date of a forecast must be after start date."}}}}}}}}},"/forecaster/{Id}":{"get":{"tags":["Forecast"],"summary":"Get forecast","description":"Get the status and potential results of a running forecast.","parameters":[{"name":"Id","in":"path","required":true,"description":"The forecast id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Normal response, containing JSON response object for a final result.","content":{"application/json":{"schema":{"title":"Forecast Response","allOf":[{"type":"object","properties":{"id":{"type":"string","description":"The id of the requested forecast. It must be used when querying for the forecast results.\n","example":"1978ad40-97da-403e-ad5d-c3e71c75a593"},"desc":{"type":"string","description":"A textual description of the forecast execution status.\n","example":"This forecast is still being processed. Partial results are available"},"eta":{"type":"string","description":"The expected time of accomplishment of the forecast: a datetime in the ISO 8601 format with timezone information. It is only available if there are partial results available (i.e., the progress is between 0% and 100%, exclusively).\n","example":"2022-11-17T21:48:37+00:00"},"status":{"type":"string","enum":["enqueued","started","cancelled","partial","finished","failed"],"description":"The status of the forecast execution. When forecasts are requested the result will always be \"enqueued\".\nForecasts can transition between states during their processing. The states have the following meaning:\n\n  * _enqueued_: The forecast request was accepted but hasn't started being processed yet.\n  * _started_: The forecast request has started to be processed, but there are no partial results yet.\n  * _cancelled_: The forecast request was cancelled by a user.\n  * _partial_: The forecast has partial results.\n  * _finished_: The forecast was completed.\n  * _failed_: The forecast failed its execution.\n","example":"partial"},"progress":{"type":"number","description":"The progress of the forecast request. It can be a number between 0.0 and 100.0. A forecast with progress 100.0\nis finished.\n","example":33.3}}},{"properties":{"requestDateTime":{"type":"string","description":"The time at which the request for this forecast was received, in UTC.\n","example":"2023-07-19T16:24:46.648Z"},"lastUpdateDateTime":{"type":"string","description":"The time at which the information for the forecast request was last updated, in UTC.\n","example":"2023-07-19T16:24:46.648Z"},"startDateTime":{"type":"string","description":"The time this forecast started processing: a UTC datetime. It is only available if there are partial results available (i.e., the progress is between 0% and 100%, exclusively).\n","example":"2023-07-19T16:24:46.648Z"},"endDateTime":{"type":"string","description":"The time this forecast completed processing: a UTC datetime. It is only available if there are finished results available (i.e., the progress is 100%).\n","example":"2023-06-29T13:57:32.321"},"forecastStartDate":{"type":"string","format":"date-time","description":"The effective start date for the forecast results, with timezone information. It is either the start date in the request (if present) or the time at which the forecast started,\nbut it can suffer some adjustments due to the availability of future traffic.\n","example":"2023-06-19T16:24:46.648Z"},"forecastEndDate":{"type":"string","format":"date-time","description":"The effective start date for the forecast results, with timezone information. It is the end date in the request, but it can suffer some adjustments due to the availability of future traffic.\n","example":"2023-07-19T16:24:46.648Z"},"resultStatus":{"type":"string","enum":["success","failure"],"description":"Whether an error happened while executing the forecast.\n","example":"success"},"result":{"description":"The result object. If resultStatus is 'success', the result can be an Existing, Available or Deliverable-specific forecast result type. If resultStatus is 'failure' a string with the error will be presented.\n","oneOf":[{"title":"Existing Forecast Result","description":"The current existing forecast type results, when available (only partial and finished status).\n","type":"object","properties":{"total":{"type":"object","description":"The number of clicks, impressions, revenue, unique users, and custom events computed as the result of the forecast request.\nClicks, impressions, and revenue are calculated over the entire lifetime of each ad, including values from\npast delivery. The number of unique users represents the projected reach -- that is, users the ad is expected\nto reach in the future.\n","oneOf":[{"type":"object","title":"By Advertiser","properties":{"byAdvertiser":{"type":"object","description":"A map of number of clicks, impressions, revenue, unique users, and custom events affected to each Advertiser, indexed by Advertiser Id. Only shown if the `ResultsBy` parameter includes `advertiser`.\n","additionalProperties":{"x-additionalPropertiesName":"<ADVERTISER-ID>","allOf":[{"type":"object","properties":{"clicks":{"type":"number","description":"Number of clicks forecasted for the Advertiser.\n"},"impressions":{"type":"number","description":"Number of impressions forecasted for the Advertiser.\n"},"revenue":{"type":"number","description":"Amount of revenue forecasted for the Advertiser.\n"},"uniqueUsers":{"type":"number","description":"Number of unique users forecasted for the Advertiser.\n"},"events":{"type":"object","description":"For each of the event types specified in the `.Params.Include.Events` parameter of the forecast request, the number of custom events forecasted for the Advertiser.\n","additionalProperties":{"x-additionalPropertiesName":"<EVENT-ID>","type":"number"}}}},{"oneOf":[{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/0/properties/total/oneOf/1"},{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/0/properties/total/oneOf/2"},{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/0/properties/total/oneOf/3"}]}]}}}},{"type":"object","title":"By Campaign","properties":{"byCampaign":{"type":"object","description":"A map of number of clicks, impressions, revenue, unique users, and custom events affected to each Campaign, indexed by Campaign Id. Only shown if the `ResultsBy` parameter includes `campaign`.\nIDs from reserved campaigns are prefixed with \"rc-\" (e.g., \"rc-123\").\n","additionalProperties":{"x-additionalPropertiesName":"<CAMPAIGN-ID>","allOf":[{"type":"object","properties":{"clicks":{"type":"number","description":"Number of clicks forecasted for the Campaign.\n"},"impressions":{"type":"number","description":"Number of impressions forecasted for the Campaign.\n"},"revenue":{"type":"number","description":"Amount of revenue forecasted for the Campaign.\n"},"uniqueUsers":{"type":"number","description":"Number of unique users forecasted for the Campaign.\n"},"events":{"type":"object","description":"For each of the event types specified in the `.Params.Include.Events` parameter of the forecast request, the number of custom events forecasted for the Campaign.\n","additionalProperties":{"x-additionalPropertiesName":"<EVENT-ID>","type":"number"}}}},{"oneOf":[{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/0/properties/total/oneOf/2"},{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/0/properties/total/oneOf/3"}]}]}}}},{"type":"object","title":"By Flight","properties":{"byFlight":{"type":"object","description":"A map of number of clicks, impressions, revenue, unique users, and custom events affected to each Flight, indexed by Flight Id. Only shown if the `ResultsBy` parameter includes `flight`.\nIDs from reserved campaigns are prefixed with \"rc-\" (e.g., \"rc-123\").\n","additionalProperties":{"x-additionalPropertiesName":"<FLIGHT-ID>","allOf":[{"type":"object","properties":{"clicks":{"type":"number","description":"Number of clicks forecasted for the Flight.\n"},"impressions":{"type":"number","description":"Number of impressions forecasted for the Flight.\n"},"revenue":{"type":"number","description":"Amount of revenue forecasted for the Flight.\n"},"uniqueUsers":{"type":"number","description":"Number of unique users forecasted for the Flight.\n"},"events":{"type":"object","description":"For each of the event types specified in the `.Params.Include.Events` parameter of the forecast request, the number of custom events forecasted for the Flight.\n","additionalProperties":{"x-additionalPropertiesName":"<EVENT-ID>","type":"number"}}}},{"oneOf":[{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/0/properties/total/oneOf/3"}]}]}}}},{"type":"object","title":"By Ad","properties":{"byAd":{"type":"object","description":"A map of number of clicks, impressions, revenue, unique users, and custom events affected to each Ad, indexed by Ad Id. Only shown if the `ResultsBy` parameter includes `ad`.\nIDs from reserved campaigns are prefixed with \"rc-\" (e.g., \"rc-123\").\n","additionalProperties":{"x-additionalPropertiesName":"<AD-ID>","allOf":[{"type":"object","properties":{"clicks":{"type":"number","description":"Number of clicks forecasted for the Ad.\n"},"impressions":{"type":"number","description":"Number of impressions forecasted for the Ad.\n"},"revenue":{"type":"number","description":"Amount of revenue forecasted for the Ad.\n"},"uniqueUsers":{"type":"number","description":"Number of unique users forecasted for the Ad.\n"},"events":{"type":"object","description":"For each of the event types specified in the `.Params.Include.Events` parameter of the forecast request, the number of custom events forecasted for the Ad.\n","additionalProperties":{"x-additionalPropertiesName":"<EVENT-ID>","type":"number"}}}}]}}}}]},"grouped":{"type":"array","description":"A list of objects with information about the number of expected future clicks, impressions, revenue, unique users, and\nunique users indexed by the `GroupBy` keys specified in the forecast request.\n","items":{"type":"object","properties":{"key":{"type":"object","description":"The key by which we are grouping values by. This key is itself an object, because grouping can be done by multiple keys. This object maps all the keys defined in the `GroupBy` parameter of the forecast request to a particular value under which the forecast result values are currently being grouped by.\n"},"value":{"type":"object","description":"The number of clicks, impressions, revenue, unique users, and custom events computed for this group.\n","$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/0/properties/total"}}}},"groupedFiltered":{"description":"The combined number of expected future clicks, impressions, revenue, and custom events that were filtered out with the\n`FilterGroupBy` rule.\n","type":"object","oneOf":[{"type":"object","title":"By Advertiser","properties":{"byAdvertiser":{"type":"object","description":"A map of number of clicks, impressions, revenue, and custom events affected to each Advertiser, indexed by Advertiser Id. Only shown if the `ResultsBy` parameter includes `advertiser`.\n","additionalProperties":{"x-additionalPropertiesName":"<ADVERTISER-ID>","allOf":[{"type":"object","properties":{"clicks":{"type":"number","description":"Number of forecasted clicks that were filtered out for the Advertiser.\n"},"impressions":{"type":"number","description":"Number of forecasted impressions that were filtered out for the Advertiser.\n"},"revenue":{"type":"number","description":"Amount of forecasted revenue that was filtered out for the Advertiser.\n"},"events":{"type":"object","description":"For each of the event types specified in the `.Params.Include.Events` parameter of the forecast request, the number of forecasted custom events that were filtered out for the Advertiser.\n","additionalProperties":{"x-additionalPropertiesName":"<EVENT-ID>","type":"number"}}}},{"oneOf":[{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/0/properties/groupedFiltered/oneOf/1"},{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/0/properties/groupedFiltered/oneOf/2"},{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/0/properties/groupedFiltered/oneOf/3"}]}]}}}},{"type":"object","title":"By Campaign","properties":{"byCampaign":{"type":"object","description":"A map of number of clicks, impressions, revenue, and custom events affected to each Campaign, indexed by Campaign Id. Only shown if the `ResultsBy` parameter includes `campaign`.\nIDs from reserved campaigns are prefixed with \"rc-\" (e.g., \"rc-123\").\n","additionalProperties":{"x-additionalPropertiesName":"<CAMPAIGN-ID>","allOf":[{"type":"object","properties":{"clicks":{"type":"number","description":"Number of forecasted clicks that were filtered out for the Campaign.\n"},"impressions":{"type":"number","description":"Number of forecasted impressions that were filtered out for the Campaign.\n"},"revenue":{"type":"number","description":"Amount of forecasted revenue that was filtered out for the Campaign.\n"},"events":{"type":"object","description":"For each of the event types specified in the `.Params.Include.Events` parameter of the forecast request, the number of forecasted custom events that were filtered out for the Campaign.\n","additionalProperties":{"x-additionalPropertiesName":"<EVENT-ID>","type":"number"}}}},{"oneOf":[{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/0/properties/groupedFiltered/oneOf/2"},{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/0/properties/groupedFiltered/oneOf/3"}]}]}}}},{"type":"object","title":"By Flight","properties":{"byFlight":{"type":"object","description":"A map of number of clicks, impressions, revenue, and custom events affected to each Flight, indexed by Flight Id. Only shown if the `ResultsBy` parameter includes `flight`.\nIDs from reserved campaigns are prefixed with \"rc-\" (e.g., \"rc-123\").\n","additionalProperties":{"x-additionalPropertiesName":"<FLIGHT-ID>","allOf":[{"type":"object","properties":{"clicks":{"type":"number","description":"Number of forecasted clicks that were filtered out for the Flight.\n"},"impressions":{"type":"number","description":"Number of forecasted impressions that were filtered out for the Flight.\n"},"revenue":{"type":"number","description":"Amount of forecasted revenue that was filtered out for the Flight.\n"},"events":{"type":"object","description":"For each of the event types specified in the `.Params.Include.Events` parameter of the forecast request, the number of forecasted custom events that were filtered out for the Flight.\n","additionalProperties":{"x-additionalPropertiesName":"<EVENT-ID>","type":"number"}}}},{"oneOf":[{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/0/properties/groupedFiltered/oneOf/3"}]}]}}}},{"type":"object","title":"By Ad","properties":{"byAd":{"type":"object","description":"A map of number of clicks, impressions, revenue, and custom events affected to each Ad, indexed by Ad Id. Only shown if the `ResultsBy` parameter includes `ad`.\nIDs from reserved campaigns are prefixed with \"rc-\" (e.g., \"rc-123\").\n","additionalProperties":{"x-additionalPropertiesName":"<AD-ID>","allOf":[{"type":"object","properties":{"clicks":{"type":"number","description":"Number of forecasted clicks that were filtered out for the Ad.\n"},"impressions":{"type":"number","description":"Number of forecasted impressions that were filtered out for the Ad.\n"},"revenue":{"type":"number","description":"Amount of forecasted revenue that was filtered out for the Ad.\n"},"events":{"type":"object","description":"For each of the event types specified in the `.Params.Include.Events` parameter of the forecast request, the number of forecasted custom events that were filtered out for the Ad.\n","additionalProperties":{"x-additionalPropertiesName":"<EVENT-ID>","type":"number"}}}}]}}}}]}},"example":{"total":{"411981212":{"clicks":0,"impressions":50,"revenue":1,"uniqueUsers":34},"412081539":{"clicks":0,"impressions":0,"revenue":0,"uniqueUsers":0}},"grouped":[{"key":{"request.localDate":"2023-08-17"},"value":{"411981212":{"clicks":0,"impressions":46,"revenue":2,"uniqueUsers":32},"412081539":{"clicks":0,"impressions":0,"revenue":0,"uniqueUsers":0}}},{"key":{"request.localDate":"2023-08-18"},"value":{"411981212":{"clicks":0,"impressions":4,"revenue":0,"uniqueUsers":2},"412081539":{"clicks":0,"impressions":0,"revenue":0,"uniqueUsers":0}}}]}},{"title":"Available Forecast Result","description":"The current availability forecast type results, when available (only for partial and finished status).\n","type":"object","properties":{"total":{"description":"The number of expected future available and booked clicks, impressions, revenue, unique users, and custom events computed\nas the result of the forecast request.\n","type":"object","properties":{"available":{"allOf":[{"type":"object","properties":{"clicks":{"type":"number","description":"Number of total forecasted available clicks.\n"},"impressions":{"type":"number","description":"Number of total forecasted available impressions.\n"},"revenue":{"type":"number","description":"Amount of total forecasted available revenue.\n"},"uniqueUsers":{"type":"number","description":"Number of total forecasted available unique users.\n"},"events":{"type":"object","description":"For each of the event types specified in the `.Params.Include.Events` parameter of the forecast request, the number of total forecasted available custom events.\n","additionalProperties":{"x-additionalPropertiesName":"<EVENT-ID>","type":"number"}},"metrics":{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/total/properties/inventory/properties/metrics"}}},{"type":"object","oneOf":[{"type":"object","title":"By Advertiser","properties":{"byAdvertiser":{"type":"object","description":"A map of number of available clicks, impressions, revenue, unique users, and custom events affected by each Advertiser, indexed by Advertiser Id. Only shown if the `ResultsBy` parameter includes `advertiser`.\n","additionalProperties":{"x-additionalPropertiesName":"<ADVERTISER-ID>","allOf":[{"type":"object","properties":{"clicks":{"type":"number","description":"Number of available clicks forecasted for the Advertiser.\n"},"impressions":{"type":"number","description":"Number of available impressions forecasted for the Advertiser.\n"},"revenue":{"type":"number","description":"Amount of available revenue forecasted for the Advertiser.\n"},"uniqueUsers":{"type":"number","description":"Number of available unique users forecasted for the Advertiser.\n"},"events":{"type":"object","description":"For each of the event types specified in the `.Params.Include.Events` parameter of the forecast request, the number of available custom events forecasted for the Advertiser.\n","additionalProperties":{"x-additionalPropertiesName":"<EVENT-ID>","type":"number"}}}},{"oneOf":[{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/total/properties/available/allOf/1/oneOf/1"},{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/total/properties/available/allOf/1/oneOf/2"},{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/total/properties/available/allOf/1/oneOf/3"}]}]}}}},{"type":"object","title":"By Campaign","properties":{"byCampaign":{"type":"object","description":"A map of number of available clicks, impressions, revenue, unique users, and custom events affected by each Campaign, indexed by Campaign Id. Only shown if the `ResultsBy` parameter includes `campaign`.\nIDs from reserved campaigns are prefixed with \"rc-\" (e.g., \"rc-123\").\n","additionalProperties":{"x-additionalPropertiesName":"<CAMPAIGN-ID>","allOf":[{"type":"object","properties":{"clicks":{"type":"number","description":"Number of available clicks forecasted for the Campaign.\n"},"impressions":{"type":"number","description":"Number of available impressions forecasted for the Campaign.\n"},"revenue":{"type":"number","description":"Amount of available revenue forecasted for the Campaign.\n"},"uniqueUsers":{"type":"number","description":"Number of available unique users forecasted for the Campaign.\n"},"events":{"type":"object","description":"For each of the event types specified in the `.Params.Include.Events` parameter of the forecast request, the number of available custom events forecasted for the Campaign.\n","additionalProperties":{"x-additionalPropertiesName":"<EVENT-ID>","type":"number"}}}},{"oneOf":[{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/total/properties/available/allOf/1/oneOf/2"},{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/total/properties/available/allOf/1/oneOf/3"}]}]}}}},{"type":"object","title":"By Flight","properties":{"byFlight":{"type":"object","description":"A map of number of available clicks, impressions, revenue, unique users, and custom events affected by each Flight, indexed by Flight Id. Only shown if the `ResultsBy` parameter includes `flight`.\nIDs from reserved campaigns are prefixed with \"rc-\" (e.g., \"rc-123\").\n","additionalProperties":{"x-additionalPropertiesName":"<FLIGHT-ID>","allOf":[{"type":"object","properties":{"clicks":{"type":"number","description":"Number of available clicks forecasted for the Flight.\n"},"impressions":{"type":"number","description":"Number of available impressions forecasted for the Flight.\n"},"revenue":{"type":"number","description":"Amount of available revenue forecasted for the Flight.\n"},"uniqueUsers":{"type":"number","description":"Number of available unique users forecasted for the Flight.\n"},"events":{"type":"object","description":"For each of the event types specified in the `.Params.Include.Events` parameter of the forecast request, the number of available custom events forecasted for the Flight.\n","additionalProperties":{"x-additionalPropertiesName":"<EVENT-ID>","type":"number"}}}},{"oneOf":[{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/total/properties/available/allOf/1/oneOf/3"}]}]}}}},{"type":"object","title":"By Ad","properties":{"byAd":{"type":"object","description":"A map of number of available clicks, impressions, revenue, unique users, and custom events affected by each Ad, indexed by Ad Id. Only shown if the `ResultsBy` parameter includes `ad`.\nIDs from reserved campaigns are prefixed with \"rc-\" (e.g., \"rc-123\").\n","additionalProperties":{"x-additionalPropertiesName":"<AD-ID>","allOf":[{"type":"object","properties":{"clicks":{"type":"number","description":"Number of available clicks forecasted for the Ad.\n"},"impressions":{"type":"number","description":"Number of available impressions forecasted for the Ad.\n"},"revenue":{"type":"number","description":"Amount of available revenue forecasted for the Ad.\n"},"uniqueUsers":{"type":"number","description":"Number of available unique users forecasted for the Ad.\n"},"events":{"type":"object","description":"For each of the event types specified in the `.Params.Include.Events` parameter of the forecast request, the number of available custom events forecasted for the Ad.\n","additionalProperties":{"x-additionalPropertiesName":"<EVENT-ID>","type":"number"}}}}]}}}}]}]},"uncapped":{"allOf":[{"type":"object","properties":{"clicks":{"type":"number","description":"Number of total forecasted available clicks ignoring frequency and daily caps.\n"},"impressions":{"type":"number","description":"Number of total forecasted available impressions ignoring frequency and daily caps.\n"},"revenue":{"type":"number","description":"Amount of total forecasted available revenue ignoring frequency and daily caps.\n"},"uniqueUsers":{"type":"number","description":"Number of total forecasted available unique users ignoring frequency and daily caps.\n"},"events":{"type":"object","description":"For each of the event types specified in the `.Params.Include.Events` parameter of the forecast request, the number of total forecasted available custom events ignoring frequency and daily caps.\n","additionalProperties":{"x-additionalPropertiesName":"<EVENT-ID>","type":"number"}},"metrics":{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/total/properties/inventory/properties/metrics"}}},{"type":"object","oneOf":[{"type":"object","title":"By Advertiser","properties":{"byAdvertiser":{"type":"object","description":"A map of number of uncapped clicks, impressions, revenue, unique users, and custom events affected by each Advertiser, indexed by Advertiser Id. Only shown if the `ResultsBy` parameter includes `advertiser`.\n","additionalProperties":{"x-additionalPropertiesName":"<ADVERTISER-ID>","allOf":[{"type":"object","properties":{"clicks":{"type":"number","description":"Number of uncapped clicks forecasted for the Advertiser.\n"},"impressions":{"type":"number","description":"Number of uncapped impressions forecasted for the Advertiser.\n"},"revenue":{"type":"number","description":"Amount of uncapped revenue forecasted for the Advertiser.\n"},"uniqueUsers":{"type":"number","description":"Number of uncapped unique users forecasted for the Advertiser.\n"},"events":{"type":"object","description":"For each of the event types specified in the `.Params.Include.Events` parameter of the forecast request, the number of uncapped custom events forecasted for the Advertiser.\n","additionalProperties":{"x-additionalPropertiesName":"<EVENT-ID>","type":"number"}}}},{"oneOf":[{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/total/properties/uncapped/allOf/1/oneOf/1"},{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/total/properties/uncapped/allOf/1/oneOf/2"},{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/total/properties/uncapped/allOf/1/oneOf/3"}]}]}}}},{"type":"object","title":"By Campaign","properties":{"byCampaign":{"type":"object","description":"A map of number of uncapped clicks, impressions, revenue, unique users, and custom events affected by each Campaign, indexed by Campaign Id. Only shown if the `ResultsBy` parameter includes `campaign`.\nIDs from reserved campaigns are prefixed with \"rc-\" (e.g., \"rc-123\").\n","additionalProperties":{"x-additionalPropertiesName":"<CAMPAIGN-ID>","allOf":[{"type":"object","properties":{"clicks":{"type":"number","description":"Number of uncapped clicks forecasted for the Campaign.\n"},"impressions":{"type":"number","description":"Number of uncapped impressions forecasted for the Campaign.\n"},"revenue":{"type":"number","description":"Amount of uncapped revenue forecasted for the Campaign.\n"},"uniqueUsers":{"type":"number","description":"Number of uncapped unique users forecasted for the Campaign.\n"},"events":{"type":"object","description":"For each of the event types specified in the `.Params.Include.Events` parameter of the forecast request, the number of uncapped custom events forecasted for the Campaign.\n","additionalProperties":{"x-additionalPropertiesName":"<EVENT-ID>","type":"number"}}}},{"oneOf":[{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/total/properties/uncapped/allOf/1/oneOf/2"},{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/total/properties/uncapped/allOf/1/oneOf/3"}]}]}}}},{"type":"object","title":"By Flight","properties":{"byFlight":{"type":"object","description":"A map of number of uncapped clicks, impressions, revenue, unique users, and custom events affected by each Flight, indexed by Flight Id. Only shown if the `ResultsBy` parameter includes `flight`.\nIDs from reserved campaigns are prefixed with \"rc-\" (e.g., \"rc-123\").\n","additionalProperties":{"x-additionalPropertiesName":"<FLIGHT-ID>","allOf":[{"type":"object","properties":{"clicks":{"type":"number","description":"Number of uncapped clicks forecasted for the Flight.\n"},"impressions":{"type":"number","description":"Number of uncapped impressions forecasted for the Flight.\n"},"revenue":{"type":"number","description":"Amount of uncapped revenue forecasted for the Flight.\n"},"uniqueUsers":{"type":"number","description":"Number of uncapped unique users forecasted for the Flight.\n"},"events":{"type":"object","description":"For each of the event types specified in the `.Params.Include.Events` parameter of the forecast request, the number of uncapped custom events forecasted for the Flight.\n","additionalProperties":{"x-additionalPropertiesName":"<EVENT-ID>","type":"number"}}}},{"oneOf":[{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/total/properties/uncapped/allOf/1/oneOf/3"}]}]}}}},{"type":"object","title":"By Ad","properties":{"byAd":{"type":"object","description":"A map of number of uncapped clicks, impressions, revenue, unique users, and custom events affected by each Ad, indexed by Ad Id. Only shown if the `ResultsBy` parameter includes `ad`.\nIDs from reserved campaigns are prefixed with \"rc-\" (e.g., \"rc-123\").\n","additionalProperties":{"x-additionalPropertiesName":"<AD-ID>","allOf":[{"type":"object","properties":{"clicks":{"type":"number","description":"Number of uncapped clicks forecasted for the Ad.\n"},"impressions":{"type":"number","description":"Number of uncapped impressions forecasted for the Ad.\n"},"revenue":{"type":"number","description":"Amount of uncapped revenue forecasted for the Ad.\n"},"uniqueUsers":{"type":"number","description":"Number of uncapped unique users forecasted for the Ad.\n"},"events":{"type":"object","description":"For each of the event types specified in the `.Params.Include.Events` parameter of the forecast request, the number of uncapped custom events forecasted for the Ad.\n","additionalProperties":{"x-additionalPropertiesName":"<EVENT-ID>","type":"number"}}}}]}}}}]}]},"booked":{"type":"object","allOf":[{"type":"object","properties":{"clicks":{"type":"number","description":"Number of total forecasted booked clicks.\n"},"impressions":{"type":"number","description":"Number of total forecasted booked impressions.\n"},"revenue":{"type":"number","description":"Amount of total forecasted booked revenue.\n"},"uniqueUsers":{"type":"number","description":"Number of total forecasted booked unique users.\n"},"events":{"type":"object","description":"For each of the event types specified in the `.Params.Include.Events` parameter of the forecast request, the number of total forecasted booked custom events.\n","additionalProperties":{"x-additionalPropertiesName":"<EVENT-ID>","type":"number"}},"metrics":{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/total/properties/inventory/properties/metrics"}}},{"oneOf":[{"type":"object","title":"By Advertiser","properties":{"byAdvertiser":{"type":"object","description":"A map of booked number of clicks, impressions, revenue, unique users, and custom events affected to each Advertiser, indexed by Advertiser Id. Only shown if the `BookedBy` parameter includes `advertiser`.\n","additionalProperties":{"x-additionalPropertiesName":"<ADVERTISER-ID>","allOf":[{"type":"object","properties":{"clicks":{"type":"number","description":"Number of booked clicks forecasted for the Advertiser.\n"},"impressions":{"type":"number","description":"Number of booked impressions forecasted for the Advertiser.\n"},"revenue":{"type":"number","description":"Amount of booked revenue forecasted for the Advertiser.\n"},"uniqueUsers":{"type":"number","description":"Number of booked unique users forecasted for the Advertiser.\n"},"events":{"type":"object","description":"For each of the event types specified in the `.Params.Include.Events` parameter of the forecast request, the number of booked custom events forecasted for the Advertiser.\n","additionalProperties":{"x-additionalPropertiesName":"<EVENT-ID>","type":"number"}}}},{"oneOf":[{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/total/properties/booked/allOf/1/oneOf/1"},{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/total/properties/booked/allOf/1/oneOf/2"},{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/total/properties/booked/allOf/1/oneOf/3"}]}]}}}},{"type":"object","title":"By Campaign","properties":{"byCampaign":{"type":"object","description":"A map of booked number of clicks, impressions, revenue, unique users, and custom events affected to each Campaign, indexed by Campaign Id. Only shown if the `BookedBy` parameter includes `campaign`.\nIDs from reserved campaigns are prefixed with \"rc-\" (e.g., \"rc-123\").\n","additionalProperties":{"x-additionalPropertiesName":"<CAMPAIGN-ID>","allOf":[{"type":"object","properties":{"clicks":{"type":"number","description":"Number of booked clicks forecasted for the Campaign.\n"},"impressions":{"type":"number","description":"Number of booked impressions forecasted for the Campaign.\n"},"revenue":{"type":"number","description":"Amount of booked revenue forecasted for the Campaign.\n"},"uniqueUsers":{"type":"number","description":"Number of booked unique users forecasted for the Campaign.\n"},"events":{"type":"object","description":"For each of the event types specified in the `.Params.Include.Events` parameter of the forecast request, the number of booked custom events forecasted for the Campaign.\n","additionalProperties":{"x-additionalPropertiesName":"<EVENT-ID>","type":"number"}}}},{"oneOf":[{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/total/properties/booked/allOf/1/oneOf/2"},{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/total/properties/booked/allOf/1/oneOf/3"}]}]}}}},{"type":"object","title":"By Flight","properties":{"byFlight":{"type":"object","description":"A map of booked number of clicks, impressions, revenue, unique users, and custom events affected to each Flight, indexed by Flight Id. Only shown if the `BookedBy` parameter includes `flight`.\nIDs from reserved campaigns are prefixed with \"rc-\" (e.g., \"rc-123\").\n","additionalProperties":{"x-additionalPropertiesName":"<FLIGHT-ID>","allOf":[{"type":"object","properties":{"clicks":{"type":"number","description":"Number of booked clicks forecasted for the Flight.\n"},"impressions":{"type":"number","description":"Number of booked impressions forecasted for the Flight.\n"},"revenue":{"type":"number","description":"Amount of booked revenue forecasted for the Flight.\n"},"uniqueUsers":{"type":"number","description":"Number of booked unique users forecasted for the Flight.\n"},"events":{"type":"object","description":"For each of the event types specified in the `.Params.Include.Events` parameter of the forecast request, the number of booked custom events forecasted for the Flight.\n","additionalProperties":{"x-additionalPropertiesName":"<EVENT-ID>","type":"number"}}}},{"oneOf":[{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/total/properties/booked/allOf/1/oneOf/3"}]}]}}}},{"type":"object","title":"By Ad","properties":{"byAd":{"type":"object","description":"A map of booked number of clicks, impressions, revenue, unique users, and custom events affected to each Ad, indexed by Ad Id. Only shown if the `BookedBy` parameter includes `ad`.\nIDs from reserved campaigns are prefixed with \"rc-\" (e.g., \"rc-123\").\n","additionalProperties":{"x-additionalPropertiesName":"<AD-ID>","allOf":[{"type":"object","properties":{"clicks":{"type":"number","description":"Number of booked clicks forecasted for the Ad.\n"},"impressions":{"type":"number","description":"Number of booked impressions forecasted for the Ad.\n"},"revenue":{"type":"number","description":"Amount of booked revenue forecasted for the Ad.\n"},"uniqueUsers":{"type":"number","description":"Number of booked unique users forecasted for the Ad.\n"},"events":{"type":"object","description":"For each of the event types specified in the `.Params.Include.Events` parameter of the forecast request, the number of booked custom events forecasted for the Ad.\n","additionalProperties":{"x-additionalPropertiesName":"<EVENT-ID>","type":"number"}}}}]}}}}]}]},"inventory":{"type":"object","properties":{"bookedAtHigher":{"type":"object","properties":{"clicks":{"type":"number","description":"Number of total forecasted clicks booked by existing ads with a higher priority/bid.\n"},"impressions":{"type":"number","description":"Number of total forecasted impressions booked by existing ads with a higher priority/bid.\n"},"revenue":{"type":"number","description":"Amount of total forecasted revenue booked by existing ads with a higher priority/bid.\n"},"uniqueUsers":{"type":"number","description":"Number of total forecasted unique users booked by existing ads with a higher priority/bid.\n"},"events":{"type":"object","description":"For each of the event types specified in the `.Params.Include.Events` parameter of the forecast request, the number of total forecasted custom events booked by existing ads with a higher priority/bid.\n","additionalProperties":{"x-additionalPropertiesName":"<EVENT-ID>","type":"number"}},"metrics":{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/total/properties/inventory/properties/metrics"}}},"bookedAtLower":{"type":"object","properties":{"clicks":{"type":"number","description":"Number of total forecasted clicks inventory booked by existing ads with a lower priority/bid.\n"},"impressions":{"type":"number","description":"Number of total forecasted impressions inventory booked by existing ads with a lower priority/bid.\n"},"revenue":{"type":"number","description":"Amount of total forecasted revenue inventory booked by existing ads with a lower priority/bid.\n"},"uniqueUsers":{"type":"number","description":"Number of total forecasted unique users inventory booked by existing ads with a lower priority/bid.\n"},"events":{"type":"object","description":"For each of the event types specified in the `.Params.Include.Events` parameter of the forecast request, the number of total forecasted custom events inventory booked by existing ads with a lower priority/bid.\n","additionalProperties":{"x-additionalPropertiesName":"<EVENT-ID>","type":"number"}},"metrics":{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/total/properties/inventory/properties/metrics"}}},"empty":{"type":"object","properties":{"clicks":{"type":"number","description":"Number of total forecasted clicks inventory not booked by any existing ad.\n"},"impressions":{"type":"number","description":"Number of total forecasted impressions inventory not booked by any existing ad.\n"},"uniqueUsers":{"type":"number","description":"Number of total forecasted unique users inventory not booked by any existing ad.\n"},"events":{"type":"object","description":"For each of the event types specified in the `.Params.Include.Events` parameter of the forecast request, the number of total forecasted custom events inventory not booked by any existing ad.\n","additionalProperties":{"x-additionalPropertiesName":"<EVENT-ID>","type":"number"}},"metrics":{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/total/properties/inventory/properties/metrics"}}},"metrics":{"title":"Block Metrics Results","type":"object","description":"Aggregated metric values keyed by the user-chosen names from `.Params.Include.Metrics`.\nThe value is the configured aggregation of the metric's source over forecasted data.\nSources that have no match over forecasted data omit the metric field entirely.\n","additionalProperties":{"x-additionalPropertiesName":"<NAME>","type":"number"},"example":{"winningBidCPM":4.2}}}}}},"grouped":{"type":"array","description":"A list of objects containing information about the number of expected future available, uncapped, and booked\nclicks, impressions, revenue, unique users, and custom events indexed by the `GroupBy` keys specified in the forecast\nrequest.\n","items":{"type":"object","properties":{"key":{"type":"object","description":"The key by which we are grouping values by. This key is itself an object, because grouping can be done by multiple keys. This object maps all the keys defined in the `GroupBy` parameter of the forecast request to a particular value under which the forecast result values are currently being grouped by.\n"},"values":{"type":"object","properties":{"available":{"allOf":[{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/total/properties/available/allOf/0"},{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/total/properties/available/allOf/1"}]},"uncapped":{"allOf":[{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/total/properties/uncapped/allOf/0"},{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/total/properties/uncapped/allOf/1"}]},"booked":{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/total/properties/booked"},"inventory":{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/total/properties/inventory"}}}}}},"groupedFiltered":{"description":"The combined number of expected future available, uncapped, and booked clicks, impressions, revenue, and custom events that\nwere filtered out with the `FilterGroupBy` rule.\n","type":"object","properties":{"available":{"allOf":[{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/groupedFiltered/properties/booked"},{"type":"object","oneOf":[{"type":"object","title":"By Advertiser","properties":{"byAdvertiser":{"type":"object","description":"A map of number of available clicks, impressions, revenue, and custom events affected to each Advertiser, indexed by Advertiser Id. Only shown if the `ResultsBy` parameter includes `advertiser`.\n","additionalProperties":{"x-additionalPropertiesName":"<ADVERTISER-ID>","allOf":[{"type":"object","properties":{"clicks":{"type":"number","description":"Number of available forecasted clicks that were filtered out for the Advertiser.\n"},"impressions":{"type":"number","description":"Number of available forecasted impressions that were filtered out for the Advertiser.\n"},"revenue":{"type":"number","description":"Amount of available forecasted revenue that was filtered out for the Advertiser.\n"},"events":{"type":"object","description":"For each of the event types specified in the `.Params.Include.Events` parameter of the forecast request, the number of available forecasted custom events that were filtered out for the Advertiser.\n","additionalProperties":{"x-additionalPropertiesName":"<EVENT-ID>","type":"number"}}}},{"oneOf":[{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/groupedFiltered/properties/available/allOf/1/oneOf/1"},{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/groupedFiltered/properties/available/allOf/1/oneOf/2"},{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/groupedFiltered/properties/available/allOf/1/oneOf/3"}]}]}}}},{"type":"object","title":"By Campaign","properties":{"byCampaign":{"type":"object","description":"A map of number of available clicks, impressions, revenue, and custom events affected to each Campaign, indexed by Campaign Id. Only shown if the `ResultsBy` parameter includes `campaign`.\nIDs from reserved campaigns are prefixed with \"rc-\" (e.g., \"rc-123\").\n","additionalProperties":{"x-additionalPropertiesName":"<CAMPAIGN-ID>","allOf":[{"type":"object","properties":{"clicks":{"type":"number","description":"Number of available forecasted clicks that were filtered out for the Campaign.\n"},"impressions":{"type":"number","description":"Number of available forecasted impressions that were filtered out for the Campaign.\n"},"revenue":{"type":"number","description":"Amount of available forecasted revenue that was filtered out for the Campaign.\n"},"events":{"type":"object","description":"For each of the event types specified in the `.Params.Include.Events` parameter of the forecast request, the number of available forecasted custom events that were filtered out for the Campaign.\n","additionalProperties":{"x-additionalPropertiesName":"<EVENT-ID>","type":"number"}}}},{"oneOf":[{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/groupedFiltered/properties/available/allOf/1/oneOf/2"},{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/groupedFiltered/properties/available/allOf/1/oneOf/3"}]}]}}}},{"type":"object","title":"By Flight","properties":{"byFlight":{"type":"object","description":"A map of number of available clicks, impressions, revenue, and custom events affected to each Flight, indexed by Flight Id. Only shown if the `ResultsBy` parameter includes `flight`.\nIDs from reserved campaigns are prefixed with \"rc-\" (e.g., \"rc-123\").\n","additionalProperties":{"x-additionalPropertiesName":"<FLIGHT-ID>","allOf":[{"type":"object","properties":{"clicks":{"type":"number","description":"Number of available forecasted clicks that were filtered out for the Flight.\n"},"impressions":{"type":"number","description":"Number of available forecasted impressions that were filtered out for the Flight.\n"},"revenue":{"type":"number","description":"Amount of available forecasted revenue that was filtered out for the Flight.\n"},"events":{"type":"object","description":"For each of the event types specified in the `.Params.Include.Events` parameter of the forecast request, the number of available forecasted custom events that were filtered out for the Flight.\n","additionalProperties":{"x-additionalPropertiesName":"<EVENT-ID>","type":"number"}}}},{"oneOf":[{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/groupedFiltered/properties/available/allOf/1/oneOf/3"}]}]}}}},{"type":"object","title":"By Ad","properties":{"byAd":{"type":"object","description":"A map of number of available clicks, impressions, revenue, and custom events affected to each Ad, indexed by Ad Id. Only shown if the `ResultsBy` parameter includes `ad`.\nIDs from reserved campaigns are prefixed with \"rc-\" (e.g., \"rc-123\").\n","additionalProperties":{"x-additionalPropertiesName":"<AD-ID>","allOf":[{"type":"object","properties":{"clicks":{"type":"number","description":"Number of available forecasted clicks that were filtered out for the Ad.\n"},"impressions":{"type":"number","description":"Number of available forecasted impressions that were filtered out for the Ad.\n"},"revenue":{"type":"number","description":"Amount of available revenue forecasted that was filtered out for the Ad.\n"},"events":{"type":"object","description":"For each of the event types specified in the `.Params.Include.Events` parameter of the forecast request, the number of available custom events forecasted that were filtered out for the Ad.\n","additionalProperties":{"x-additionalPropertiesName":"<EVENT-ID>","type":"number"}}}}]}}}}]}]},"uncapped":{"allOf":[{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/groupedFiltered/properties/booked"},{"type":"object","oneOf":[{"type":"object","title":"By Advertiser","properties":{"byAdvertiser":{"type":"object","description":"A map of number of uncapped clicks, impressions, revenue, and custom events affected to each Advertiser, indexed by Advertiser Id. Only shown if the `ResultsBy` parameter includes `advertiser`.\n","additionalProperties":{"x-additionalPropertiesName":"<ADVERTISER-ID>","allOf":[{"type":"object","properties":{"clicks":{"type":"number","description":"Number of uncapped forecasted clicks that were filtered out for the Advertiser.\n"},"impressions":{"type":"number","description":"Number of uncapped forecasted impressions that were filtered out for the Advertiser.\n"},"revenue":{"type":"number","description":"Amount of uncapped forecasted revenue that was filtered out for the Advertiser.\n"},"events":{"type":"object","description":"For each of the event types specified in the `.Params.Include.Events` parameter of the forecast request, the number of uncapped forecasted custom events that were filtered out for the Advertiser.\n","additionalProperties":{"x-additionalPropertiesName":"<EVENT-ID>","type":"number"}}}},{"oneOf":[{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/groupedFiltered/properties/uncapped/allOf/1/oneOf/1"},{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/groupedFiltered/properties/uncapped/allOf/1/oneOf/2"},{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/groupedFiltered/properties/uncapped/allOf/1/oneOf/3"}]}]}}}},{"type":"object","title":"By Campaign","properties":{"byCampaign":{"type":"object","description":"A map of number of uncapped clicks, impressions, revenue, and custom events affected to each Campaign, indexed by Campaign Id. Only shown if the `ResultsBy` parameter includes `campaign`.\nIDs from reserved campaigns are prefixed with \"rc-\" (e.g., \"rc-123\").\n","additionalProperties":{"x-additionalPropertiesName":"<CAMPAIGN-ID>","allOf":[{"type":"object","properties":{"clicks":{"type":"number","description":"Number of uncapped forecasted clicks that were filtered out for the Campaign.\n"},"impressions":{"type":"number","description":"Number of uncapped forecasted impressions that were filtered out for the Campaign.\n"},"revenue":{"type":"number","description":"Amount of uncapped forecasted revenue that was filtered out for the Campaign.\n"},"events":{"type":"object","description":"For each of the event types specified in the `.Params.Include.Events` parameter of the forecast request, the number of uncapped forecasted custom events that were filtered out for the Campaign.\n","additionalProperties":{"x-additionalPropertiesName":"<EVENT-ID>","type":"number"}}}},{"oneOf":[{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/groupedFiltered/properties/uncapped/allOf/1/oneOf/2"},{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/groupedFiltered/properties/uncapped/allOf/1/oneOf/3"}]}]}}}},{"type":"object","title":"By Flight","properties":{"byFlight":{"type":"object","description":"A map of number of uncapped clicks, impressions, revenue, and custom events affected to each Flight, indexed by Flight Id. Only shown if the `ResultsBy` parameter includes `flight`.\nIDs from reserved campaigns are prefixed with \"rc-\" (e.g., \"rc-123\").\n","additionalProperties":{"x-additionalPropertiesName":"<FLIGHT-ID>","allOf":[{"type":"object","properties":{"clicks":{"type":"number","description":"Number of uncapped forecasted clicks that were filtered out for the Flight.\n"},"impressions":{"type":"number","description":"Number of uncapped forecasted impressions that were filtered out for the Flight.\n"},"revenue":{"type":"number","description":"Amount of uncapped forecasted revenue that was filtered out for the Flight.\n"},"events":{"type":"object","description":"For each of the event types specified in the `.Params.Include.Events` parameter of the forecast request, the number of uncapped forecasted custom events that were filtered out for the Flight.\n","additionalProperties":{"x-additionalPropertiesName":"<EVENT-ID>","type":"number"}}}},{"oneOf":[{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/1/properties/groupedFiltered/properties/uncapped/allOf/1/oneOf/3"}]}]}}}},{"type":"object","title":"By Ad","properties":{"byAd":{"type":"object","description":"A map of number of uncapped clicks, impressions, revenue, and custom events affected to each Ad, indexed by Ad Id. Only shown if the `ResultsBy` parameter includes `ad`.\nIDs from reserved campaigns are prefixed with \"rc-\" (e.g., \"rc-123\").\n","additionalProperties":{"x-additionalPropertiesName":"<AD-ID>","allOf":[{"type":"object","properties":{"clicks":{"type":"number","description":"Number of uncapped forecasted clicks that were filtered out for the Ad.\n"},"impressions":{"type":"number","description":"Number of uncapped forecasted impressions that were filtered out for the Ad.\n"},"revenue":{"type":"number","description":"Amount of uncapped forecasted revenue that was filtered out for the Ad.\n"},"events":{"type":"object","description":"For each of the event types specified in the `.Params.Include.Events` parameter of the forecast request, the number of uncapped forecasted custom events that were filtered out for the Ad.\n","additionalProperties":{"x-additionalPropertiesName":"<EVENT-ID>","type":"number"}}}}]}}}}]}]},"booked":{"type":"object","properties":{"clicks":{"type":"number","description":"Number of forecasted clicks that were filtered out.\n"},"impressions":{"type":"number","description":"Number of forecasted impressions that were filtered out.\n"},"revenue":{"type":"number","description":"Amount of forecasted revenue that was filtered out.\n"},"events":{"type":"object","description":"For each of the event types specified in the `.Params.Include.Events` parameter of the forecast request, the number of forecasted custom events that were filtered out.\n","additionalProperties":{"x-additionalPropertiesName":"<EVENT-ID>","type":"number"}}}}}}},"example":{"total":{"available":{"clicks":712,"impressions":285048,"revenue":4560.06,"uniqueUsers":173090},"booked":{"clicks":362,"impressions":145048,"revenue":1234.5,"uniqueUsers":25090}},"grouped":[{"key":{"localDate":"2022-11-17"},"values":{"available":{"clicks":344,"impressions":137634,"revenue":567.43,"uniqueUsers":86560},"booked":{"clicks":0,"impressions":0,"revenue":0,"uniqueUsers":0}}},{"key":{"localDate":"2022-11-18"},"values":{"available":{"clicks":308,"impressions":123457,"revenue":437.43,"uniqueUsers":42500},"booked":{"clicks":3,"impressions":1234,"revenue":67.43,"uniqueUsers":4250}}}]}},{"title":"Deliverable Forecast Result","description":"The current deliverable forecast type results, when available (only partial and finished status).\n","type":"object","properties":{"total":{"type":"object","description":"The number of expected future clicks, impressions, revenue, unique users, and custom events computed as the result of the\nforecast request.\n","$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/0/properties/total"},"grouped":{"type":"array","description":"A list of objects with information about the number of expected future clicks, impressions, revenue, unique users, and\nunique users indexed by the group by keys specified in the forecast request.\n","items":{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/0/properties/grouped/items"}},"groupedFiltered":{"description":"The combined number of expected future clicks, impressions, revenue, and custom events that were filtered out with the\n`FilterGroupBy` rule.\n","type":"object","$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema/allOf/1/properties/result/oneOf/0/properties/groupedFiltered"}},"example":{"total":{"411981212":{"clicks":0,"impressions":50,"revenue":1,"uniqueUsers":34},"412081539":{"clicks":0,"impressions":0,"revenue":0,"uniqueUsers":0}},"grouped":[{"key":{"request.localDate":"2023-08-17"},"value":{"411981212":{"clicks":0,"impressions":46,"revenue":2,"uniqueUsers":32},"412081539":{"clicks":0,"impressions":0,"revenue":0,"uniqueUsers":0}}},{"key":{"request.localDate":"2023-08-18"},"value":{"411981212":{"clicks":0,"impressions":4,"revenue":0,"uniqueUsers":2},"412081539":{"clicks":0,"impressions":0,"revenue":0,"uniqueUsers":0}}}]}},{"title":"Forecast Result Error","type":"string"}]},"warnings":{"description":"A non-fatal warning that occurred during the simulation. Each type of warning has a specific short-code, a more descriptive message, and optionally a list of causes and metadata.\nThe existence of a warning does not mean that the forecast is incorrect, some of them are more informational, but if a forecast is exhibiting slow performance or strange results, it can give some insights into the underlying problem.\n","type":"array","nullable":true,"items":{"title":"Forecast Warning","type":"object","properties":{"code":{"description":"The short code specific to each type of warning, which are:\n\n* _DATETRF_: Raised whenever there are traffic modifiers applied during the simulation, containing the date of when the traffic modifiers were loaded into the simulation engine.\n* _MODTRF_: Raised whenever a traffic modifier is applied during a simulation.\n* _OVRTRF_: Raised whenever there is an overlap between two or more traffic modifiers that were applied in a simulation.\n* _PERFWRN_: Raised when a forecast request includes Traffic modifiers or non-default Multi winner ratio settings. These configurations are intended for exploratory use and can significantly impact forecast performance, so they should be avoided in standard workflows.\n* _TRCEND_: Raised only with available forecast requests and happens when the forecast end-date is automatically truncated to match the internal cache.\n* _UNRFLD_: Raised when the forecast request has unrecognized fields that will be ignored.\n* _UNSEVT_: Raised when the forecast request includes event types (through the `.Params.Include.Events` field) that aren't configured for the network.\n","type":"string","enum":["DATETRF","MODTRF","OVRTRF","PERFWRN","TRCEND","UNRFLD","UNSEVT"]},"message":{"description":"Descriptive message of the warning. When related to traffic modifiers, it contains the IDs of the relevant traffic modifiers.","type":"string"},"causes":{"description":"List of causes related to the warning that vary accordingly to the warning. When related to traffic modifiers, it contains the rules of the respective traffic modifiers. When it is about unrecognized fields, it contains the names of those fields.","nullable":true,"type":"array","items":{"type":"string"}},"metadata":{"nullable":true,"type":"object"}}}},"forecastEnvironment":{"description":"Information relative with the data considered at the time of the forecast.\n","type":"object","properties":{"campaignSyncDateTime":{"type":"string","description":"The synchronization date time in UTC for the campaigns considered for the forecast.\n"},"seasonalityUsed":{"type":"boolean","description":"Whether the seasonality was considered for the forecast.\n"},"reservedCampaignsSyncDateTime":{"type":"string","description":"The synchronization date time in UTC for the reserved campaigns considered for the forecast.\n"},"reservedCampaignSalesWeightCutOff":{"type":"integer","description":"The sales weight cut-off percentage used to filter reserved campaigns for the forecast.\n"},"staticAudiencesSyncDateTime":{"type":"string","nullable":true,"description":"The UTC date-time of the static-audiences snapshot used by the forecast. Uploads received before this\ntime are reflected in the result, and uploads received later are not. Absent when the forecast did not\nuse a static-audiences snapshot.\n"}}}}}]}}}},"202":{"description":"Normal response, containing JSON response object for a partial result.","content":{"application/json":{"schema":{"$ref":"#/paths/~1forecaster~1{Id}/get/responses/200/content/application~1json/schema"}}}},"400":{"description":"Error response, containing error message.","content":{"application/json":{"schema":{"$ref":"#/paths/~1forecaster/post/responses/400/content/application~1json/schema"}}}},"404":{"description":"Forecast ID not found.","content":{"application/json":{"schema":{"$ref":"#/paths/~1forecaster/post/responses/400/content/application~1json/schema"}}}}}},"delete":{"tags":["Forecast"],"summary":"Deletes a forecast","description":"Deletes a forecast that was previously executed or cancels a forecast that is running or queued.","parameters":[{"name":"Id","in":"path","required":true,"description":"The forecast id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Information about deleted forecast.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}},"examples":{"cancelled":{"value":{"message":"Forecast cancelled"}},"removed":{"value":{"message":"Forecast removed"}}}}}},"400":{"description":"Error response, containing error message (e.g. the forecast id is not a valid UUID).","content":{"application/json":{"schema":{"$ref":"#/paths/~1forecaster/post/responses/400/content/application~1json/schema"}}}},"404":{"description":"Forecast key not found","content":{"application/json":{"schema":{"$ref":"#/paths/~1forecaster/post/responses/400/content/application~1json/schema"},"examples":{"not_found":{"value":{"message":"Forecast key not found"}}}}}}}}},"/forecaster/modifiers/traffic":{"get":{"summary":"List traffic modifiers","description":"List all existing Forecast Traffic Modifiers.","tags":["Traffic Modifiers"],"responses":{"200":{"description":"Normal response, containing a JSON object of all existing traffic modifier IDs to their JSON representation.","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"object","title":"Map of ID to Traffic Modifier","properties":{"id":{"type":"string"},"trafficModifier":{"oneOf":[{"$ref":"#/paths/~1forecaster~1modifiers~1traffic/post/requestBody/content/application~1json/schema/oneOf/0"},{"$ref":"#/paths/~1forecaster~1modifiers~1traffic/post/requestBody/content/application~1json/schema/oneOf/1"},{"$ref":"#/paths/~1forecaster~1modifiers~1traffic/post/requestBody/content/application~1json/schema/oneOf/2"}]}}}}}}}}},"post":{"summary":"Create traffic modifier","description":"Create a Forecast Traffic Modifier","tags":["Traffic Modifiers"],"requestBody":{"description":"The JSON object with the traffic modifier.","required":true,"content":{"application/json":{"schema":{"oneOf":[{"title":"Ad Request Multiplier","description":"A traffic modifier that multiplies the targeted Ad Requests by a constant amount.\nIf this Traffic Modifier is active during a forecast, a `MODTRF` warning will be triggered.\n","allOf":[{"title":"Traffic Modifier","required":["Id","StartDate","EndDate"],"properties":{"Id":{"type":"string","description":"Unique identifier of the Traffic Modifier.","example":"e123e48"},"StartDate":{"type":"string","format":"date-time","description":"Start date for the traffic modifier, as `yyyy-mm-dd'T'HH:mm:SS` or `yyyy-mm-dd` (default time of `00:00:00`).\n","example":"2024-09-03T00:00:00"},"EndDate":{"type":"string","format":"date-time","description":"End date for the traffic modifier, as `yyyy-mm-dd'T'HH:mm:SS` or `yyyy-mm-dd` (default time of `23:59:59`).","example":"2024-09-04T23:59:59"},"TimeZone":{"default":"UTC","type":"string","description":"The time zone of the modifier's start and end dates ([available time zones](https://www.joda.org/joda-time/timezones.html)). Additionally, the rule is evaluated in the modifier's time zone, i.e. if the modifier is set to \"EST\" a rule like `$datetime.hour > 10` assumes that the given hour is in \"EST\".\n"},"Rule":{"type":"string","description":"The rule used to filter the Ad Requests (Zerkel query). The traffic modifier will only be applied to Ad Requests who conform to this rule.\n","example":"$location.countryCode = \"GB\""}}},{"required":["Type","Multiplier"],"properties":{"Type":{"type":"string","enum":["adRequestMultiplier"]},"Multiplier":{"type":"number","description":"How many times to multiply traffic in the range.","example":2}}}]},{"title":"Ad Request Count","description":"A traffic modifiers that sets the number of targeted Ad Requests to a constant amount.\nIf this Traffic Modifier is active during a forecast, a `MODTRF` warning will be triggered.\n\nNote that for this type of Traffic Modifier, it is required that the `EndDate` of the modifier is after the current time and before the `EndDate` of the forecast request.\n","allOf":[{"$ref":"#/paths/~1forecaster~1modifiers~1traffic/post/requestBody/content/application~1json/schema/oneOf/0/allOf/0"},{"required":["Type","Count"],"properties":{"Type":{"type":"string","enum":["adRequestCount"]},"Count":{"type":"number","description":"Target number of Ad Requests to achieve with the traffic modifier.","example":10000}}}]},{"title":"Placement Opportunity Ratio","description":"A traffic modifier that scales the per-placement opportunities of placements matched by the rule. Sibling placements in the same Ad Request are unaffected.\n\nUse `Rule` to target individual placements. If `Rule` is omitted, every placement is scaled.\n\nIf this Traffic Modifier is active during a forecast, a `MODTRF` warning will be triggered.\n","allOf":[{"$ref":"#/paths/~1forecaster~1modifiers~1traffic/post/requestBody/content/application~1json/schema/oneOf/0/allOf/0"},{"required":["Type","Ratio"],"properties":{"Rule":{"type":"string","description":"The rule used to filter the Placements (Zerkel query). The traffic modifier will only be applied to Placements who conform to this rule.\n","example":"$location.countryCode = \"GB\""},"Type":{"type":"string","enum":["placementOpportunityRatio"]},"Ratio":{"type":"number","minimum":0,"maximum":1,"description":"Fraction of placement opportunities to keep. `1.0` keeps every matching placement; `0.0` drops all matching placements.\n","example":0.5}}}]}]}}}},"responses":{"200":{"description":"The JSON object of the traffic modifier that was created successfully.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/paths/~1forecaster~1modifiers~1traffic/post/requestBody/content/application~1json/schema/oneOf/0"},{"$ref":"#/paths/~1forecaster~1modifiers~1traffic/post/requestBody/content/application~1json/schema/oneOf/1"},{"$ref":"#/paths/~1forecaster~1modifiers~1traffic/post/requestBody/content/application~1json/schema/oneOf/2"}]}}}},"400":{"$ref":"#/components/responses/InvalidBody"}}}},"/forecaster/modifiers/traffic/{trafficModifierId}":{"parameters":[{"name":"trafficModifierId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get traffic modifier","description":"Returns a Forecast Traffic Modifier based on its ID.","tags":["Traffic Modifiers"],"responses":{"200":{"description":"Normal response, containing a JSON object with the traffic modifier, if it exists.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/paths/~1forecaster~1modifiers~1traffic/post/requestBody/content/application~1json/schema/oneOf/0"},{"$ref":"#/paths/~1forecaster~1modifiers~1traffic/post/requestBody/content/application~1json/schema/oneOf/1"},{"$ref":"#/paths/~1forecaster~1modifiers~1traffic/post/requestBody/content/application~1json/schema/oneOf/2"}]}}}}}},"put":{"summary":"Replace traffic modifier","description":"Replace the existing Forecast Traffic Modifier with the one received from this request.","tags":["Traffic Modifiers"],"requestBody":{"description":"The JSON object with the traffic modifier.","required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/paths/~1forecaster~1modifiers~1traffic/post/requestBody/content/application~1json/schema/oneOf/0"},{"$ref":"#/paths/~1forecaster~1modifiers~1traffic/post/requestBody/content/application~1json/schema/oneOf/1"},{"$ref":"#/paths/~1forecaster~1modifiers~1traffic/post/requestBody/content/application~1json/schema/oneOf/2"}]}}}},"responses":{"200":{"description":"Normal response, containing the updated JSON object with the traffic modifier, if it existed before.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/paths/~1forecaster~1modifiers~1traffic/post/requestBody/content/application~1json/schema/oneOf/0"},{"$ref":"#/paths/~1forecaster~1modifiers~1traffic/post/requestBody/content/application~1json/schema/oneOf/1"},{"$ref":"#/paths/~1forecaster~1modifiers~1traffic/post/requestBody/content/application~1json/schema/oneOf/2"}]}}}},"400":{"$ref":"#/components/responses/InvalidBody"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"summary":"Delete traffic modifier","description":"Delete a traffic modifier.","tags":["Traffic Modifiers"],"responses":{"200":{"$ref":"#/components/responses/Ok"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/forecaster/network-settings":{"get":{"summary":"Get network settings","description":"Get the Yield Forecast settings of a network. Returns default values if none exists.","tags":["Yield Forecast"],"responses":{"200":{"description":"Normal response, containing JSON response with network settings.","content":{"application/json":{"schema":{"$ref":"#/paths/~1forecaster~1network-settings/post/requestBody/content/application~1json/schema"}}}}}},"post":{"summary":"Update network settings","description":"Update the Yield Forecast settings of a network.","tags":["Yield Forecast"],"requestBody":{"description":"The JSON object with the network settings.","required":true,"content":{"application/json":{"schema":{"title":"Network Settings","type":"object","properties":{"sampling":{"type":"integer","minimum":0,"maximum":3,"description":"The level of sampling to use (between 0 and 3). 3 provides the quickest response and 0 the highest accuracy.\n"},"dateRange":{"type":"integer","minimum":0,"description":"The default number of days for which forecasts will be calculated and results shown, starting from the current day.","example":90},"dateAggregation":{"type":"string","enum":["date","week","month"],"description":"The default date aggregation in the `groupBy` of the inventory results forecasts."},"groupBy":{"type":"array","items":{"type":"string"},"description":"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](ref:kevel-forecast-overview#group-by-fields), see this [section](ref:kevel-forecast-overview#grouping-by-and-time-zone-considerations).\nWhen 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).\nIt's also possible to expand the key-value pairs of `$user.custom` by suffixing the field name with `{}`.\n","example":["$adTypes","$zone.id"]},"filterGroupBy":{"type":"string","nullable":true,"description":"Filter the forecast grouped results breakdown by the given rule (Zerkel query) at the ad level.\nThis rule operates on the following set of numeric fields for all forecast types: `impressions`, `clicks`\nand `uniqueUsers`. Additionally, the Available forecast supports the `bookedImpressions`, `bookedClicks`\nand `bookedUniqueUsers` fields, and the Deliverable and Existing forecasts the `adId`, `flightId`,\n`campaignId`, `advertiserId`, `reservedAdId`, `reservedFlightId` and `reservedCampaignId` fields.\nAn extra key, `groupedFiltered`, is added to the forecast result containing all the results that were\nfiltered out by the rule. If used in combination with the `ResultsBy` parameter, the `advertiser`,\n`campaign` and `flight` levels won't include the `uniqueUsers` count.\n","example":"bookedImpressions < 100 and bookedUniqueUsers < 100 or impressions >= 1000"},"inventoryPriorities":{"type":"array","items":{"type":"integer"},"description":"The priority IDs to be considered as the first paid priority of each channel. It should be set one per channel.","example":[1111,12345]},"salesProbabilityWeight":{"type":"integer","nullable":true,"minimum":0,"maximum":100,"description":"The minimum sales probability weight threshold used to filter reserved campaigns. Reserved campaigns with a `salesProbabilityWeight` below this value will be excluded from forecasts. Set to `0` to include all reserved campaigns regardless of their sales probability.\n","example":50}}}}}},"responses":{"200":{"description":"The JSON object of the network settings, if successful.","content":{"application/json":{"schema":{"$ref":"#/paths/~1forecaster~1network-settings/post/requestBody/content/application~1json/schema"}}}},"400":{"$ref":"#/components/responses/InvalidBody"}}}},"/forecaster/ad-products":{"get":{"summary":"List ad products","description":"List existing Yield Forecast Ad Products.","tags":["Yield Forecast"],"parameters":[{"name":"showComplete","in":"query","description":"Whether to include the ad products' targeting sets in the response.","schema":{"type":"boolean","default":false},"required":false},{"name":"showHidden","in":"query","description":"Whether to filter out ad products that aren't enabled. It will also filter targeting sets if `showComplete` is `true`.","schema":{"type":"boolean","default":false},"required":false}],"responses":{"200":{"description":"Normal response, containing a JSON object of existing ad product IDs to their JSON representation.\nIt will return the Partial Ad Product when `showComplete` is false.\n","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"oneOf":[{"title":"Partial Ad Product","allOf":[{"$ref":"#/paths/~1forecaster~1ad-products~1{adProductId}/patch/requestBody/content/application~1json/schema"},{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier of the ad product.","example":4512},"targetingSetsCount":{"type":"object","description":"Count of existing and enabled targeting sets of the ad product.","properties":{"all":{"type":"number","description":"Number of all targeting sets the ad product contains.","example":4},"enabled":{"type":"number","description":"Number of enabled targeting sets the ad product contains.","example":2}}}}}]},{"$ref":"#/paths/~1forecaster~1ad-products/post/responses/200/content/application~1json/schema"}]}}}}}}},"post":{"summary":"Create ad product","description":"Create a Yield Forecast Ad Product in the network.\nAny passed targeting sets will be created for the ad product as well.\n","tags":["Yield Forecast"],"requestBody":{"description":"The JSON object with the ad product.","required":true,"content":{"application/json":{"schema":{"title":"Ad Product","allOf":[{"$ref":"#/paths/~1forecaster~1ad-products~1{adProductId}/patch/requestBody/content/application~1json/schema"},{"type":"object","properties":{"targetingSets":{"type":"array","items":{"allOf":[{"title":"Targeting Set with ID only","allOf":[{"type":"object","properties":{"id":{"type":"integer","description":"The ID of the targeting set.","example":9352}}},{"$ref":"#/paths/~1forecaster~1ad-products~1{adProductId}~1targeting-sets/post/requestBody/content/application~1json/schema"}]}]}}},"required":["name","enabled"]}]}}}},"responses":{"200":{"description":"The JSON object of the ad product that was created successfully.","content":{"application/json":{"schema":{"title":"Ad Product","allOf":[{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier of the ad product.","example":4512}}},{"$ref":"#/paths/~1forecaster~1ad-products~1{adProductId}/patch/requestBody/content/application~1json/schema"},{"type":"object","properties":{"targetingSets":{"type":"array","items":{"$ref":"#/paths/~1forecaster~1ad-products~1{adProductId}~1targeting-sets/post/responses/200/content/application~1json/schema"}}}}]}}}},"400":{"$ref":"#/components/responses/InvalidBody"}}}},"/forecaster/ad-products/{adProductId}":{"parameters":[{"name":"adProductId","in":"path","description":"The ad product ID.","required":true,"schema":{"type":"integer"}}],"get":{"summary":"Get ad product","description":"Returns a Yield Forecast Ad Product.","tags":["Yield Forecast"],"responses":{"200":{"description":"Normal response, containing a JSON object with the ad product, if it exists.","content":{"application/json":{"schema":{"$ref":"#/paths/~1forecaster~1ad-products/post/responses/200/content/application~1json/schema"}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"summary":"Update ad product","description":"Update a Yield Forecast Ad Product.\nThe defined targeting sets will be updated or created. Targeting sets not present will remain unchanged.\n","tags":["Yield Forecast"],"requestBody":{"description":"The JSON object with the ad product.","required":true,"content":{"application/json":{"schema":{"$ref":"#/paths/~1forecaster~1ad-products/post/requestBody/content/application~1json/schema"}}}},"responses":{"200":{"description":"Normal response, containing the updated JSON object with the ad product, if successful.","content":{"application/json":{"schema":{"$ref":"#/paths/~1forecaster~1ad-products/post/responses/200/content/application~1json/schema"}}}},"400":{"$ref":"#/components/responses/InvalidBody"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"summary":"Patch ad product","description":"Update one or more fields of a Yield Forecast Ad Product.","tags":["Yield Forecast"],"requestBody":{"description":"A JSON object with one or more of the ad product fields that are updatable.","content":{"application/json":{"schema":{"type":"object","description":"An ad product is a campaign template. It aggregates targeting sets (flight templates) for which a forecast is run.","properties":{"name":{"type":"string","description":"Name of the ad product.","example":"Awesome ad product"},"description":{"description":"An optional description of the ad product.","type":["string"],"nullable":true,"example":"This ad product is awesome and very cool."},"enabled":{"type":"boolean","description":"Whether the ad product is enabled. Only enabled ad products are considered when calculating results.\n"}}}}}},"responses":{"200":{"description":"Normal response, containing the full updated JSON object with the ad product, if successful.","content":{"application/json":{"schema":{"$ref":"#/paths/~1forecaster~1ad-products/post/responses/200/content/application~1json/schema"}}}},"400":{"$ref":"#/components/responses/InvalidBody"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"summary":"Delete ad product","description":"Delete a Yield Forecast Ad Product and its targeting sets, if any exist.","tags":["Yield Forecast"],"responses":{"200":{"$ref":"#/components/responses/Ok"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/forecaster/ad-products/{adProductId}/targeting-sets":{"parameters":[{"name":"adProductId","in":"path","description":"The ad product ID.","required":true,"schema":{"type":"integer"}}],"get":{"summary":"List targeting sets","description":"List existing Targeting Sets of a Yield Forecast Ad Product.","tags":["Yield Forecast"],"parameters":[{"name":"showHidden","in":"query","description":"Whether to filter out targeting sets that aren't enabled.","schema":{"type":"boolean","default":false},"required":false}],"responses":{"200":{"description":"Normal response, containing a JSON object of existing targeting set IDs to their JSON representation.","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"$ref":"#/paths/~1forecaster~1ad-products~1{adProductId}~1targeting-sets/post/responses/200/content/application~1json/schema"}}}}}}},"post":{"summary":"Create targeting set","description":"Create a Targeting Set in a Yield Forecast Ad Product.","tags":["Yield Forecast"],"requestBody":{"description":"The JSON object with the targeting set.","required":true,"content":{"application/json":{"schema":{"title":"Targeting Set without IDs","type":"object","description":"A targeting set is an object which contains all the fields in a flight that are relevant and supported in the forecast planner.\n","properties":{"name":{"type":"string","description":"The name of the targeting set.","example":"Awesome targeting set"},"enabled":{"type":"boolean","description":"Whether the targeting set is enabled. Only enabled targeting sets are considered when calculating and displaying results.\n"},"priorityId":{"type":"integer","nullable":true,"description":"The ID of the priority. It is required when the targeting set is enabled.","example":221170},"rate":{"type":"object","nullable":true,"description":"The rate at which the advertiser pays you. It is required when the targeting set is enabled.","properties":{"rateType":{"type":"number","enum":[1,2,3],"description":"The field used to estimate the revenue you have made from your advertisers. Currently supported rate types are:\n  * _1_: Flat\n  * _2_: CPM\n  * _3_: CPC\n"},"price":{"type":"number","description":"The amount being paid.","example":100}},"required":["rateType","price"]},"keywordTargeting":{"type":"string","nullable":true,"description":"Please head to [Keyword Logic](doc:keyword-logic) for more details.\n","example":"keyword1,keyword2\nkeyword3\n!keyword1,keyword2"},"frequencyCap":{"$ref":"#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/patch/requestBody/content/application~1json/schema/properties/frequencyCap"},"siteZoneTargeting":{"type":"array","nullable":true,"items":{"$ref":"#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/put/requestBody/content/application~1json/schema/properties/flights/items/properties/siteZoneTargeting/items"}},"geoTargeting":{"type":"array","nullable":true,"items":{"$ref":"#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/put/requestBody/content/application~1json/schema/properties/flights/items/properties/geoTargeting/items"}},"distanceTargeting":{"type":"array","nullable":true,"items":{"$ref":"#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/put/requestBody/content/application~1json/schema/properties/flights/items/properties/distanceTargeting/items"}},"customTargeting":{"type":"string","nullable":true,"description":"A string for custom targeting using the [Zerkel Language](doc:zerkel-queries).\n","example":"[\"order_confirmation\"] contains screen"},"duplicateMode":{"$ref":"#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/put/requestBody/content/application~1json/schema/properties/flights/items/properties/duplicateMode"},"adTypes":{"description":"The ad type IDs to use in forecasts. Required on an enabled targeting set, unless you provide `ads`. A targeting set that defines its ads directly uses `ads` instead. The `adTypes` list and the `ads` list are mutually exclusive.\n","oneOf":[{"type":"array","items":{"type":"number","description":"The ID of an ad type, which correlates to ad size.","example":4649}},{"type":"string","const":"all","description":"All existing ad types in the network will be considered in forecasts.\n"}]},"searchTerms":{"type":"array","nullable":true,"description":"Search term targeting rules. Please head to [Search Term Targeting](doc:search-term-targeting) for more details.\n","items":{"$ref":"#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/put/requestBody/content/application~1json/schema/properties/flights/items/properties/searchTerms/items"}},"bidModifiers":{"type":"array","nullable":true,"description":"Bid modifiers to apply to the flight's effective price for matching ad requests.\nPlease head to [Bid Modifiers](doc:bid-modifiers) for more details.\n","items":{"$ref":"#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/put/requestBody/content/application~1json/schema/properties/flights/items/properties/bidModifiers/items"}},"isCompanion":{"type":"boolean","nullable":true,"description":"When true, the ads in `ads` are treated as companion ads: when one wins a placement, the forecast co-allocates the other ads across the request's remaining placements. Requires a non-empty `ads` list. When absent or false, the `ads` entries are forecast as that many separate ads with no co-allocation.\n","example":true},"ads":{"type":"array","nullable":true,"description":"A fixed list (duplicates allowed) of the flight's ads. The `adTypes` list and the `ads` list are mutually exclusive. Each entry becomes a separate ad on the flight, carrying a single ad type. The list holds at most 1000 ads, or 19 when `isCompanion` is set. Set `isCompanion` to true to make these ads co-allocate as a companion flight.\n","items":{"type":"object","properties":{"adType":{"type":"number","description":"The ID of the ad type for this ad, which correlates to ad size.","example":4649}},"required":["adType"]}}},"required":["name","enabled"]}}}},"responses":{"200":{"description":"The JSON object of the targeting set that was created successfully.","content":{"application/json":{"schema":{"title":"Targeting Set","allOf":[{"type":"object","properties":{"adProductId":{"type":"integer","description":"The ID of the ad product the targeting set belongs to.\n","example":4512}}},{"$ref":"#/paths/~1forecaster~1ad-products/post/requestBody/content/application~1json/schema/allOf/1/properties/targetingSets/items/allOf/0"}]}}}},"400":{"$ref":"#/components/responses/InvalidBody"}}}},"/forecaster/ad-products/{adProductId}/targeting-sets/{targetingSetId}":{"parameters":[{"name":"adProductId","in":"path","required":true,"schema":{"type":"integer"}},{"name":"targetingSetId","in":"path","required":true,"schema":{"type":"integer"}}],"get":{"summary":"Get targeting set","description":"Get a Targeting Set in a Yield Forecast Ad Product.","tags":["Yield Forecast"],"responses":{"200":{"description":"Normal response, containing a JSON object with the targeting set, if it exists.","content":{"application/json":{"schema":{"$ref":"#/paths/~1forecaster~1ad-products~1{adProductId}~1targeting-sets/post/responses/200/content/application~1json/schema"}}}}}},"put":{"summary":"Update targeting set","description":"Update a Targeting Set in a Yield Forecast Ad Product.","tags":["Yield Forecast"],"requestBody":{"description":"The JSON object with the targeting set.","required":true,"content":{"application/json":{"schema":{"$ref":"#/paths/~1forecaster~1ad-products~1{adProductId}~1targeting-sets/post/requestBody/content/application~1json/schema"}}}},"responses":{"200":{"description":"Normal response, containing the updated JSON object with the targeting set, if successful.","content":{"application/json":{"schema":{"$ref":"#/paths/~1forecaster~1ad-products~1{adProductId}~1targeting-sets/post/responses/200/content/application~1json/schema"}}}},"400":{"$ref":"#/components/responses/InvalidBody"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"summary":"Patch targeting set","description":"Update one or more fields of a Targeting Set in a Yield Forecast Ad Product.","tags":["Yield Forecast"],"requestBody":{"description":"A JSON object with one or more of the targeting set fields that are updatable.","content":{"application/json":{"schema":{"$ref":"#/paths/~1forecaster~1ad-products~1{adProductId}~1targeting-sets/post/requestBody/content/application~1json/schema"}}}},"responses":{"200":{"description":"Normal response, containing the full updated JSON object with the ad product, if successful.","content":{"application/json":{"schema":{"$ref":"#/paths/~1forecaster~1ad-products/post/responses/200/content/application~1json/schema"}}}},"400":{"$ref":"#/components/responses/InvalidBody"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"summary":"Delete targeting set","description":"Delete a Targeting Set in a Yield Forecast Ad Product.","tags":["Yield Forecast"],"responses":{"200":{"$ref":"#/components/responses/Ok"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/forecaster/reserved-campaign":{"get":{"summary":"List reserved campaigns","description":"List all reserved campaigns.","tags":["Reserved Campaigns"],"responses":{"200":{"description":"Normal response, containing a JSON object of existing reserved campaign IDs to their JSON representation.\n","content":{"application/json":{"schema":{"title":"Reserved Campaigns Map","type":"object","description":"A map of reserved campaign IDs to their reserved campaign objects.","additionalProperties":{"$ref":"#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/put/requestBody/content/application~1json/schema"},"example":{"1234":{"id":1234,"name":"Holiday Campaign 2025","status":"reserved","salesProbabilityWeight":75,"advertiser":{"id":10},"flights":[{"id":5678,"priorityId":221170,"rate":{"rateType":2,"price":5.5},"startDate":"2025-01-01T00:00:00.000","timeZone":"UTC","goalType":1,"goalAmount":1000000,"ads":[{"id":9012,"adType":4649}]}]}}}}}}}},"post":{"summary":"Create reserved campaign","description":"Create a new reserved campaign.\nReserved campaigns are used to forecast inventory for campaigns that are reserved but not yet fully booked.\n","tags":["Reserved Campaigns"],"requestBody":{"description":"The JSON object with the reserved campaign details.","required":true,"content":{"application/json":{"schema":{"title":"Creatable Reserved Campaign","description":"Schema for creating a new reserved campaign. Same as ReservedCampaign but without the id field.","allOf":[{"$ref":"#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/put/requestBody/content/application~1json/schema"}]}}}},"responses":{"200":{"description":"The JSON object of the reserved campaign that was created successfully.","content":{"application/json":{"schema":{"$ref":"#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/put/requestBody/content/application~1json/schema"}}}},"400":{"$ref":"#/components/responses/InvalidBody"}}}},"/forecaster/reserved-campaign/{reservedCampaignId}":{"parameters":[{"name":"reservedCampaignId","in":"path","description":"The reserved campaign ID.","required":true,"schema":{"type":"integer"}}],"get":{"summary":"Get reserved campaign","description":"Returns a reserved campaign by its ID.","tags":["Reserved Campaigns"],"responses":{"200":{"description":"Normal response, containing a JSON object with the reserved campaign, if it exists.","content":{"application/json":{"schema":{"$ref":"#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/put/requestBody/content/application~1json/schema"}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"summary":"Update reserved campaign","description":"Fully replace an existing reserved campaign with the provided data.\nAll required fields must be provided.\n\n**Important: ID handling for flights and ads**\n\n- The campaign `id` is required and must match the path parameter.\n- Flights and ads **with an `id`**: Will be updated in-place if the ID exists.\n- Flights and ads **without an `id`**: Will be created as new entities with auto-generated IDs.\n- Existing flights and ads **not included** in the request: Will be **deleted**.\n\nThis means the PUT operation performs a full replacement of the reserved campaign structure.\nTo preserve existing flights or ads, you must include them in the request with their respective IDs.\n","tags":["Reserved Campaigns"],"requestBody":{"description":"The JSON object with the complete reserved campaign data.","required":true,"content":{"application/json":{"schema":{"title":"Reserved Campaign","type":"object","description":"A reserved campaign represents a campaign that is reserved (or booked) for a specific advertiser.\nIt is used to forecast how reserved campaigns will impact future inventory availability.\n","properties":{"id":{"type":"integer","description":"Unique identifier of the reserved campaign.\nAuto-generated on creation (do not include when creating).\nRequired when updating via PUT.\n","example":1234},"name":{"type":"string","description":"The name of the reserved campaign.","example":"Holiday Campaign 2025"},"status":{"type":"string","enum":["reserved","booked"],"default":"reserved","description":"The status of the campaign:\n  * _reserved_: The campaign is reserved but not yet booked.\n  * _booked_: The campaign has been confirmed and booked so it will not be considered as a reservation in the forecasts.\n"},"description":{"type":"string","nullable":true,"description":"An optional description of the reserved campaign.","example":"Premium holiday campaign for Q4"},"salesProbabilityWeight":{"type":"integer","minimum":0,"maximum":100,"description":"A weight (0-100) representing the probability that this reserved campaign will convert to a booked campaign.\n","example":75},"advertiser":{"$ref":"#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/patch/requestBody/content/application~1json/schema/properties/advertiser"},"capType":{"$ref":"#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/patch/requestBody/content/application~1json/schema/properties/capType"},"dailyCapAmount":{"$ref":"#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/patch/requestBody/content/application~1json/schema/properties/dailyCapAmount"},"lifetimeCapAmount":{"$ref":"#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/patch/requestBody/content/application~1json/schema/properties/lifetimeCapAmount"},"frequencyCap":{"$ref":"#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/patch/requestBody/content/application~1json/schema/properties/frequencyCap"},"flights":{"type":"array","minItems":1,"description":"The flights associated with this reserved campaign. At least one flight is required.\n","items":{"title":"Reserved Flight","type":"object","description":"A flight within a reserved campaign.\n","properties":{"id":{"type":"integer","description":"Unique identifier of the flight.\nAuto-generated on creation (do not include when creating).\nWhen updating via PUT: include to update in-place, omit to create as new.\n","example":5678},"priorityId":{"type":"integer","description":"The ID of the priority level for this flight.","example":221170},"rate":{"title":"Rate","type":"object","description":"The rate configuration for billing.","properties":{"rateType":{"type":"integer","enum":[1,2,3,4,5,6],"description":"The type of rate:\n  * _1_: Flat\n  * _2_: CPM (Cost Per Mille/Thousand Impressions)\n  * _3_: CPC (Cost Per Click)\n  * _4_: CPA View (Cost Per Action - View)\n  * _5_: CPA Click (Cost Per Action - Click)\n  * _6_: CPA Both (Cost Per Action - Both)\n","example":2},"price":{"type":"number","description":"The price amount for the rate.","example":5.5}},"required":["rateType","price"]},"keywordTargeting":{"type":"string","nullable":true,"description":"Keyword targeting rules. Please head to [Keyword Logic](doc:keyword-logic) for more details.\n","example":"keyword1,keyword2\nkeyword3\n!keyword1,keyword2"},"siteZoneTargeting":{"type":"array","nullable":true,"items":{"title":"Site Zone Targeting","type":"object","description":"Site and zone targeting rules. Please head to [Site/Zone Targeting](ref:create-sitezone-targeting) for more details.\n","properties":{"SiteId":{"type":"integer","example":1121285},"ZoneId":{"type":"integer","example":247884},"IsExclude":{"type":"boolean"}},"anyOf":[{"required":["SiteId"]},{"required":["ZoneId"]}]}},"geoTargeting":{"type":"array","nullable":true,"items":{"title":"Geo Targeting","type":"object","description":"Geographic targeting rules. Please head to [Geo Targeting](ref:create-geo-targeting) for more details.\n","properties":{"CountryCode":{"type":"string","description":"The two-character country code.","example":"US"},"Region":{"type":"string","description":"The two-character code for the state, region, or province.","example":"NY"},"MetroCode":{"type":"string","description":"The metro code, such as ZIP code.","example":"10001"},"CityGeonameId":{"type":"integer","description":"The numeric GeoNames ID for city-level targeting. This value is used for matching, not the city name. Please head to [Geo Targeting](ref:create-geo-targeting) for more details.","example":5128581},"IsExclude":{"type":"boolean","description":"Set to 'false' (default) to target; 'true' to exclude."}},"required":["CountryCode"]}},"distanceTargeting":{"type":"array","nullable":true,"items":{"title":"Distance Targeting","type":"object","description":"Distance-based geographic targeting. Please head to [Distance Targeting](ref:create-geodistance-targeting-geometry) for more details.\n","properties":{"distance":{"type":"number","description":"The radius distance in kilometers.","example":20},"latitude":{"type":"number","description":"The latitude of the center point.","example":41.40338},"longitude":{"type":"number","description":"The longitude of the center point.","example":2.17403}},"required":["distance","latitude","longitude"]}},"customTargeting":{"type":"string","nullable":true,"description":"A string for custom targeting using the [Zerkel Language](doc:zerkel-queries).\n","example":"[\"order_confirmation\"] contains screen"},"duplicateMode":{"title":"Duplicate Mode","type":"integer","nullable":true,"enum":[1,2,3,4],"description":"When defined, enables no duplicates and defines the type of the duplicate mode:\n  * _1_: Flight\n  * _2_: Campaign\n  * _3_: Advertiser\n  * _4_: Creative\n"},"ads":{"type":"array","minItems":1,"description":"The ads associated with this flight. At least one ad is required.\n","items":{"title":"Reserved Ad","type":"object","description":"An ad within a reserved flight.","properties":{"id":{"type":"integer","description":"Unique identifier of the ad.\nAuto-generated on creation (do not include when creating).\nWhen updating via PUT: include to update in-place, omit to create as new.\n","example":9012},"adType":{"type":"integer","description":"The ad type ID.","example":4649}},"required":["adType"]}},"segmentTargeting":{"type":"array","nullable":true,"description":"Segment-based audience targeting.","items":{"title":"Segment Targeting","type":"object","description":"Audience segment targeting configuration.","properties":{"segmentId":{"type":"integer","description":"The ID of the audience segment to target.","example":12345},"isExclude":{"type":"boolean","default":false,"description":"Whether to exclude (true) or include (false) users in this segment."},"category":{"type":"string","example":"Demographics","description":"The category the segment belongs to. Include segments are matched OR-within-category and AND-across-categories: a request must match at least one included segment in every targeted category. Optional; segments with no category are treated as a single uncategorized group, so all-one-category (or no category) reduces to the flat OR behavior. Ignored for excluded segments, because exclude is a flat deny."}},"required":["segmentId"]}},"startDate":{"type":"string","format":"date-time","description":"The start date and time of the flight.","example":"2025-01-01T00:00:00.000"},"endDate":{"type":"string","format":"date-time","nullable":true,"description":"The end date and time of the flight. Required for goal types other than Percentage (2), Daily Revenue (9), or Monthly Revenue (10).\nMust be after the start date and after the current date.\n","example":"2025-03-31T23:59:59.000"},"timeZone":{"type":"string","default":"UTC","description":"The time zone for the flight's schedule.","example":"America/New_York"},"goalType":{"type":"integer","enum":[1,2,3,7,8,9,10],"description":"The type of goal for this flight:\n  * _1_: Impressions\n  * _2_: Percentage\n  * _3_: Clicks\n  * _7_: Conversions\n  * _8_: Revenue\n  * _9_: Daily Revenue\n  * _10_: Monthly Revenue\n","example":1},"goalAmount":{"type":"integer","description":"The target amount for the goal (e.g., number of impressions, percentage, etc.).","example":1000000},"capType":{"$ref":"#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/patch/requestBody/content/application~1json/schema/properties/capType"},"dailyCapAmount":{"$ref":"#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/patch/requestBody/content/application~1json/schema/properties/dailyCapAmount"},"lifetimeCapAmount":{"$ref":"#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/patch/requestBody/content/application~1json/schema/properties/lifetimeCapAmount"},"frequencyCap":{"$ref":"#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/patch/requestBody/content/application~1json/schema/properties/frequencyCap"},"searchTerms":{"type":"array","nullable":true,"description":"Search term targeting rules. Please head to [Search Term Targeting](doc:search-term-targeting) for more details.\n","items":{"title":"Search Term Targeting","type":"object","description":"Search term targeting rule. Please head to [Search Term Targeting](doc:search-term-targeting) for more details.\n","properties":{"term":{"type":"string","description":"The search term to match against.","example":"running shoes"},"matchType":{"type":"string","enum":["broad","strict","exact"],"description":"How `term` is matched against the ad request's search term.","example":"broad"},"isExclude":{"type":"boolean","default":false,"description":"Whether to exclude (`true`) or include (`false`) requests that match this rule."}},"required":["term","matchType"]}},"bidModifiers":{"type":"array","nullable":true,"description":"Bid modifiers to apply to the flight's effective price for matching ad requests.\nPlease head to [Bid Modifiers](doc:bid-modifiers) for more details.\n","items":{"title":"Bid Modifier","type":"object","description":"A bid modifier that adjusts a flight's effective price for ad requests matching the given conditions.\nPlease head to [Bid Modifiers](doc:bid-modifiers) for more details.\n","properties":{"match":{"type":"object","description":"The match conditions for the bid modifier.","properties":{"Keyword":{"type":"string"},"Site":{"type":"integer","format":"int32"},"Zone":{"type":"integer","format":"int32"},"Segment":{"type":"integer","format":"int32"},"SearchTerm":{"type":"object","properties":{"Term":{"type":"string"}}}}},"price":{"type":"number","nullable":true,"description":"Fixed effective price to use when this modifier applies. Takes precedence over `multiplier`\nwhen both are set.\n","example":7.5},"multiplier":{"type":"number","nullable":true,"description":"Factor applied to the flight's price when this modifier applies. Ignored if `price` is set.\n","example":1.5}},"required":["match"]}},"isCompanion":{"type":"boolean","nullable":true,"default":false,"description":"Marks a companion flight. When true, the flight's ads are treated as companion ads: when one wins a placement,\nthe forecast co-allocates the flight's other ads across the request's remaining placements.\n","example":false}},"required":["priorityId","rate","ads","startDate","goalType","goalAmount"]}}},"required":["name","salesProbabilityWeight","advertiser","flights"]}}}},"responses":{"200":{"description":"Normal response, containing the updated JSON object with the reserved campaign, if successful.","content":{"application/json":{"schema":{"$ref":"#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/put/requestBody/content/application~1json/schema"}}}},"400":{"$ref":"#/components/responses/InvalidBody"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"summary":"Patch reserved campaign","description":"Partially update one or more fields of a reserved campaign.\nOnly the provided fields will be updated; other fields remain unchanged.\nNote: Array fields (like flights) are not supported in patch operations.\n","tags":["Reserved Campaigns"],"requestBody":{"description":"A JSON object with one or more of the reserved campaign fields to update.","content":{"application/json":{"schema":{"title":"Patchable Reserved Campaign","type":"object","description":"Schema for partially updating a reserved campaign. All fields are optional. Only the provided fields will be updated, other fields remain unchanged.","properties":{"name":{"type":"string","description":"The name of the reserved campaign."},"status":{"type":"string","enum":["reserved","booked"],"description":"The status of the campaign."},"description":{"type":"string","nullable":true,"description":"An optional description of the reserved campaign."},"salesProbabilityWeight":{"type":"integer","minimum":0,"maximum":100,"description":"A weight (0-100) representing the probability that this reserved campaign will convert to a booked campaign."},"advertiser":{"title":"Advertiser","type":"object","description":"The advertiser associated with the reserved campaign.","properties":{"id":{"type":"integer","description":"The unique identifier of the advertiser. Must be an existing advertiser.","example":10},"frequencyCap":{"$ref":"#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/patch/requestBody/content/application~1json/schema/properties/frequencyCap"},"placementLimit":{"type":"integer","nullable":true,"description":"Maximum number of placements for this advertiser."},"caps":{"type":"object","nullable":true,"description":"Ad caps for the advertiser."}},"required":["id"]},"capType":{"title":"Cap Type","type":"integer","nullable":true,"enum":[1,2,3,4],"description":"The type of cap:\n  * _1_: Impressions\n  * _2_: Clicks\n  * _3_: Conversions\n  * _4_: Revenue\n"},"dailyCapAmount":{"title":"Daily Cap Amount","type":"integer","nullable":true,"description":"The daily cap amount (based on capType).","example":10000},"lifetimeCapAmount":{"title":"Lifetime Cap Amount","type":"integer","nullable":true,"description":"The lifetime cap amount (based on capType).","example":1000000},"frequencyCap":{"title":"Frequency Cap","type":"object","nullable":true,"description":"Configuration for limiting ad frequency to users.","properties":{"type":{"type":"integer","enum":[1,2,3],"description":"The time unit for the frequency cap:\n  * _1_: Hour\n  * _2_: Day\n  * _3_: Minute\n","example":2},"duration":{"type":"integer","description":"The number of time units for the cap period.","example":1},"value":{"type":"integer","description":"The maximum number of impressions allowed within the duration.","example":5}},"required":["type","duration","value"]}}}}}},"responses":{"200":{"description":"Normal response, containing the full updated JSON object with the reserved campaign, if successful.","content":{"application/json":{"schema":{"$ref":"#/paths/~1forecaster~1reserved-campaign~1{reservedCampaignId}/put/requestBody/content/application~1json/schema"}}}},"400":{"$ref":"#/components/responses/InvalidBody"},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"summary":"Delete reserved campaign","description":"Delete a reserved campaign by its ID.","tags":["Reserved Campaigns"],"responses":{"200":{"$ref":"#/components/responses/Ok"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/forecaster/trigger-ad-products-forecasts":{"post":{"tags":["Yield Forecast"],"summary":"Trigger forecasts for ad products","description":"Triggers forecast requests for all enabled ad products in the network.\nGrouping and filtering of group by results is defined in the forecast settings.\n","requestBody":{"description":"The JSON object with optional parameters for the forecasts.","content":{"application/json":{"schema":{"$ref":"#/paths/~1forecaster~1trigger-inventory-forecast/post/requestBody/content/application~1json/schema"}}}},"responses":{"200":{"description":"Normal response, containing a JSON object of enabled ad product IDs to the result of its forecast trigger.","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"$ref":"#/paths/~1forecaster~1trigger-inventory-forecast/post/responses/200/content/application~1json/schema"}}}}}}}},"/forecaster/trigger-inventory-forecast":{"post":{"tags":["Yield Forecast"],"summary":"Trigger a forecast of all available inventory","description":"Triggers a forecast request of all available inventory, using the inventory priorities defined in the forecast settings.\nResults are grouped by three different date aggregation levels: daily, weekly, and monthly.\n","requestBody":{"description":"The JSON object with optional parameters for the forecasts.","content":{"application/json":{"schema":{"type":"object","description":"Parameters to forecast triggers endpoints.","properties":{"sampling":{"type":"integer","minimum":0,"maximum":3,"description":"The level of sampling to set in the forecast request(s) being triggered. Defaults to the default sampling defined for the network.\n"},"startDate":{"type":"string","format":"date","description":"The start date of the forecast request(s) being triggered. Defaults to the current date."},"endDate":{"type":"string","format":"date","description":"The end date of the forecast request(s) being triggered. Defaults to the date given by default date range defined for the network."}}}}}},"responses":{"200":{"description":"Normal response, containing a JSON object with the result of the forecast trigger.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","description":"Response when a forecast is successfully triggered.","properties":{"type":{"type":"string","const":"success"},"forecastId":{"type":"string","description":"The ID of the triggered forecast."}}},{"type":"object","description":"Response when a forecast wasn't triggered due to lack of data.","properties":{"type":{"type":"string","const":"no-result"},"noResultReason":{"type":"string","description":"The reason why the forecast wasn't triggered.","example":"Package does not contain valid targeting sets to derive forecast requests."}}},{"type":"object","description":"Response when a forecast trigger resulted in error.","properties":{"type":{"type":"string","const":"error"},"errorMessage":{"type":"string","description":"The error message detailing the error in the forecast trigger."}}}]}}}}}}},"/forecaster/udb/custom-properties/ingest-url":{"post":{"tags":["Static Audiences"],"summary":"Static user custom properties ingest URL","description":"This endpoint allows you to push static audiences, represented by user custom properties, directly to Kevel Forecast.\nWhen you create a new ingest URL, we'll give you back a signed URL for an Amazon S3 bucket.\n\nThe file needs to be in [JSON Lines](https://jsonlines.org/) format, containing an entry per user with the following format:\n\n```{\"userKey\": <user-key>, \"customProperties\": <json-object>}```\n\nFor example:\n\n```{\"userKey\": \"1234\", \"customProperties\": {\"favoriteColor\": \"blue\"}}```\n\nTo reduce the size of file transfers, Kevel recommends delivering the file gzipped. With this compression, the file extension must end in `gz` or `gzip`, e.g., `static-audiences.jsonl.gz`.\n\nAll user custom properties found in the file will be considered and saved as static. See the [Configure user custom properties endpoint](ref:post_forecaster-udb-custom-properties-settings) for more details on how to manage the set of static audiences and [Static Audiences page](ref:static-audiences) for more details on this feature.\n","requestBody":{"description":"The JSON object with name of the file to be uploaded","content":{"application/json":{"schema":{"type":"object","properties":{"filename":{"type":"string","description":"The name of the file to be pushed to the ingest URL.\n"}}}}}},"responses":{"200":{"description":"Normal response, containing a JSON object with the signed Amazon S3 URL","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"The signed URL for the Amazon S3 Bucket to where the file can be uploaded.\n"},"status":{"type":"string","description":"A fully-formed URL you can `GET` to track the ingestion status of this upload. The URL points\nat `/forecaster/udb/ingest-status` with the appropriate `type` and `file` query parameters\nalready filled in.\n"}}}}}}}}},"/forecaster/udb/custom-properties/settings":{"get":{"tags":["Static Audiences"],"summary":"List configured user custom properties","description":"Read back the user custom properties currently configured as static.\n\nThe response is the same JSON object shape accepted by the corresponding `POST` endpoint, so the body returned here can be sent straight back to reconfigure the set. Keys are the custom-property names and values are always `\"static\"`.\n","responses":{"200":{"description":"Normal response, containing a JSON object of the configured static user custom properties.","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"string","enum":["static"]},"example":{"favoriteColor":"static"}}}}}}},"post":{"tags":["Static Audiences"],"summary":"Configure user custom properties","description":"Modify how user custom properties are considered by Kevel Forecast by associating a forecast type.\nCurrently, the only type of user custom properties that can be defined is \"static\".\n\nTypically, Kevel Forecast considers the value of each user custom property as it existed at the time of the historical Ad Request.\nSetting a user custom property as static will cause Kevel Forecast to consider its value as the result of the ingested files.\nThese properties can be targeted by custom targeting rules (Zerkel query) such as `$user.custom.<static_property> = 1` (head to [Custom Targeting](doc:custom-targeting) for more details).\n\nNote that this endpoint fully replaces the existing set, so to remove all types association send an empty JSON object.\nSee [Static Audiences](ref:static-audiences) for more details on this feature.\n","requestBody":{"description":"The JSON object with user custom properties and their type.","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"string","enum":["static"]},"example":{"favoriteColor":"static"}}}}},"responses":{"200":{"description":"Normal response, containing a JSON object with a status code and message.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["success","error"]},"message":{"type":"string","description":"Descriptive message of result of the operation.","example":"Saved all static user custom properties successfully"}}}}}}}}},"/forecaster/udb/segments/ingest-url":{"post":{"tags":["Static Audiences"],"summary":"Static user segments ingest URL","description":"This endpoint allows you to push static audiences, represented by user segments, directly to Kevel Forecast.\nWhen you create a new ingest URL, we'll give you back a signed URL for an Amazon S3 bucket.\n\nThe file needs to be in [JSON Lines](https://jsonlines.org/) format, containing an entry per user with the following format:\n\n```{\"userKey\": <user-key>, \"segments\": <array-of-segment-ids>}```\n\nFor example:\n\n```{\"userKey\": \"1234\", \"segments\": [10, 42]}```\n\nTo reduce the size of file transfers, Kevel recommends delivering the file gzipped. With this compression, the file extension must end in `gz` or `gzip`, e.g., `static-audiences.jsonl.gz`.\n\nAll user segments found in the file will be considered and saved as static. See the [Configure user segments endpoint](ref:post_forecaster-udb-segments-settings) for more details on how to manage the set of static audiences and [Static Audiences page](ref:static-audiences) for more details on this feature.\n","requestBody":{"description":"The JSON object with name of the file to be uploaded","content":{"application/json":{"schema":{"type":"object","properties":{"filename":{"type":"string","description":"The name of the file to be pushed to the ingest URL.\n"}}}}}},"responses":{"200":{"description":"Normal response, containing a JSON object with the signed Amazon S3 URL","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"The signed URL for the Amazon S3 Bucket to where the file can be uploaded.\n"},"status":{"type":"string","description":"A fully-formed URL you can `GET` to track the ingestion status of this upload. The URL points\nat `/forecaster/udb/ingest-status` with the appropriate `type` and `file` query parameters\nalready filled in.\n"}}}}}}}}},"/forecaster/udb/segments/settings":{"get":{"tags":["Static Audiences"],"summary":"List configured user segments","description":"Read back the user segments currently configured as static.\n\nThe response is the same JSON object shape accepted by the corresponding `POST` endpoint, so the body returned here can be sent straight back to reconfigure the set. Keys are the numeric segment IDs (as strings) and values are always `\"static\"`.\n","responses":{"200":{"description":"Normal response, containing a JSON object of the configured static user segments.","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"string","enum":["static"]},"example":{"10":"static","42":"static"}}}}}}},"post":{"tags":["Static Audiences"],"summary":"Configure user segments","description":"Modify how user segments are considered by Kevel Forecast by associating a forecast type.\nCurrently, the only type of user segments that can be defined is \"static\".\n\nTypically, Kevel Forecast considers the user's segment membership as it existed at the time of the historical Ad Request.\nSetting a user segment as static will cause Kevel Forecast to consider its membership as the result of the ingested files.\nThese segments can be targeted by user segment targeting rules.\n\nThe keys of the JSON object must be the numeric segment IDs (as strings). Entries with non-numeric keys are rejected.\n\nNote that this endpoint fully replaces the existing set, so to remove all types association send an empty JSON object.\nSee [Static Audiences](ref:static-audiences) for more details on this feature.\n","requestBody":{"description":"The JSON object with user segment IDs and their type.","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"string","enum":["static"]},"example":{"10":"static","42":"static"}}}}},"responses":{"200":{"description":"Normal response, containing a JSON object with a status code and message.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["success","error"]},"message":{"type":"string","description":"Descriptive message of result of the operation.","example":"Saved all static user segments successfully"}}}}}}}}},"/forecaster/udb/ingest-status":{"get":{"tags":["Static Audiences"],"summary":"Static-audience upload status","description":"Returns the current state of a single static-audience upload (custom-properties or segments file). You\nreceive the full URL for this endpoint as the `status` field on the response of the corresponding ingest-url\nendpoint. You can also build the URL yourself with the `type` and `file` query parameters described below.\n\nThe `status` field of the response reports where the upload is in its lifecycle. When it is `completed`,\nthe `ingestedAt` field carries the timestamp of completion. To know whether a specific forecast already\nincludes this upload, compare `ingestedAt` against `forecastEnvironment.staticAudiencesSyncDateTime` on the\nforecast response. When `staticAudiencesSyncDateTime >= ingestedAt`, the snapshot the forecast used was\nsampled after the upload was persisted, so the upload is reflected.\n","parameters":[{"name":"type","in":"query","required":true,"schema":{"type":"string","enum":["custom-properties","segments"]},"description":"The audience type the upload belongs to.\n"},{"name":"file","in":"query","required":true,"schema":{"type":"string"},"description":"Composite identifier formatted as `<uploadedAt>-<filename>`, where `<uploadedAt>` is the epoch-millisecond\ntimestamp embedded in the upload's object key. Returned ready-to-use as part of the `status` URL on the\ningest-url response.\n"}],"responses":{"200":{"description":"The current state of the upload.","content":{"application/json":{"schema":{"title":"Ingest Status Response","type":"object","description":"The current state of a single file upload.\n","properties":{"status":{"type":"string","enum":["incoming","processing","completed","failed","not-found"],"description":"The current state of the upload:\n\n* `incoming`: the file was received but has not yet been picked up.\n* `processing`: the file is being parsed.\n* `completed`: the file was correctly processed, and the `ingestedAt` field carries the timestamp of\n  completion.\n* `failed`: an error was encountered while processing the file.\n* `not-found`: no upload matching the request is currently tracked.\n"},"ingestedAt":{"type":"string","nullable":true,"description":"UTC date-time at which the file was processed. Only present when `status` is `completed`.\n"}}}}}},"400":{"description":"The `type` or `file` parameter is missing or malformed."}}}},"/forecaster/auto-seasonality/ingest-url":{"post":{"tags":["Auto Seasonality"],"summary":"Boostrap Seasonality URL","description":"This endpoint allows you to bootstrap auto seasonality, by uploading a `*.csv` file directly to Kevel Forecast.\nWhen you create a new ingest URL, we'll give you back a signed URL to upload the file to.\n\nThe file needs to be in CSV format, containing the total events per day with the following format, where:\n\n* `events`: the total number of events for a given day.\n* `site:<ID>`: the total number of events for a specific site where `<ID>` is the the Kevel's Site identifier.\n\n```csv\ndate,events,site:4572,site:7643\n2025-01-01,236632,206845,29787\n2025-01-02,690062,288547,401515\n```\n\nKevel Forecast requires 13 months of data for the boostrap.\n\nSee [Auto Seasonality](ref:auto-seasonality) for more details on this feature.\n","requestBody":{"description":"The JSON object with name of the file to be uploaded","content":{"application/json":{"schema":{"type":"object","properties":{"filename":{"type":"string","description":"The name of the file to be pushed to the ingest URL.\n","example":"example.csv"}}}}}},"responses":{"200":{"description":"Normal response, containing a JSON object with the signed Amazon S3 URL","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"The signed URL for the Amazon S3 Bucket to where the file can be uploaded\n"},"status":{"type":"string","description":"A fully-formed URL you can `GET` to track the ingestion status of this upload. The URL points\nat `/forecaster/auto-seasonality/ingest-status` with the appropriate `file` query parameter\nalready filled in.\n"}}}}}}}}},"/forecaster/auto-seasonality/ingest-status":{"get":{"tags":["Auto Seasonality"],"summary":"Auto-seasonality upload status","description":"Returns the current state of a single seasonality CSV upload. You receive the full URL for this endpoint\nas the `status` field on the response of `/forecaster/auto-seasonality/ingest-url`. You can also build the\nURL yourself with the `file` query parameter described below.\n","parameters":[{"name":"file","in":"query","required":true,"schema":{"type":"string"},"description":"Composite identifier formatted as `<uploadedAt>-<filename>`, where `<uploadedAt>` is the epoch-millisecond\ntimestamp embedded in the upload's object key. Returned ready-to-use as part of the `status` URL on the\ningest-url response.\n"}],"responses":{"200":{"description":"The current state of the upload.","content":{"application/json":{"schema":{"$ref":"#/paths/~1forecaster~1udb~1ingest-status/get/responses/200/content/application~1json/schema"}}}},"400":{"description":"The `file` parameter is missing or malformed."}}}},"/forecaster/auto-seasonality/preview":{"get":{"summary":"Preview Seasonality","description":"Shows the derived seasonality event count.\n\nSee [Auto Seasonality](ref:auto-seasonality) for more details on this feature.\n","tags":["Auto Seasonality"],"responses":{"200":{"description":"Normal response, containing a JSON object with the preview data.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["success","no-seasonality-model-available","not-enough-data-points"],"description":"The status of the response.","example":"success"},"results":{"description":"The object with global results if available.\n","type":"object","properties":{"withSeasonality":{"type":"array","description":"Array of tuples with the total number of requests considering seasonality.\n","items":{"type":"array","prefixItems":[{"type":"string","format":"date","description":"Entry date"},{"type":"integer","description":"Entry count","example":165709}],"minItems":2,"maxItems":2,"additionalItems":false}},"withoutSeasonality":{"type":"array","description":"Array of tuples with the total number of requests not considering seasonality.\n","items":{"$ref":"#/paths/~1forecaster~1auto-seasonality~1preview/get/responses/200/content/application~1json/schema/properties/results/properties/withSeasonality/items"}}}},"bySite":{"type":"object","description":"The individual results broken down by Site.\nThe sum of these values may not equal the global results.\n","additionalProperties":{"x-additionalPropertiesName":"<SITE-ID>","$ref":"#/paths/~1forecaster~1auto-seasonality~1preview/get/responses/200/content/application~1json/schema/properties/results"}}}}}}}}}},"/forecaster/auto-seasonality/settings":{"get":{"summary":"Get auto seasonality settings","description":"Show the current seasonality settings.\n\nSee [Auto Seasonality](ref:auto-seasonality) for more details on this feature.\n","tags":["Auto Seasonality"],"responses":{"200":{"description":"Normal response, containing a JSON object with current seasonality settings.","content":{"application/json":{"schema":{"$ref":"#/paths/~1forecaster~1auto-seasonality~1settings/put/requestBody/content/application~1json/schema"}}}}}},"put":{"summary":"Update auto seasonality settings","description":"Updates the seasonality settings. Any change to these settings will take up to 24h be effective.\n\nSee [Auto Seasonality](ref:auto-seasonality) for more details on this feature.\n","tags":["Auto Seasonality"],"requestBody":{"description":"The JSON object with the seasonality settings.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether the auto seasonality is enabled or not."},"correlateImportedCounts":{"type":"boolean","description":"Whether to correlate the imported counts with the ones derived by Kevel. This setting should only be used if\nthe ad-server implementation is complete, partial implementations might introduce inaccuracies.\n"}}}}}},"responses":{"200":{"description":"Normal response, containing a JSON object with the applied settings\".","content":{"application/json":{"schema":{"$ref":"#/paths/~1forecaster~1auto-seasonality~1settings/put/requestBody/content/application~1json/schema"}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Adzerk-ApiKey"}},"responses":{"Ok":{"description":"Operation was successful.","content":{"text/plain":{"schema":{"type":"string"},"example":"OK"}}},"InvalidBody":{"description":"The entity in the body is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"NotFound":{"description":"The entity doesn't exist.","content":{"text/plain":{"schema":{"type":"string"},"example":"Traffic modifier with ID 123 doesn't exist"}}}},"schemas":{"ErrorFields":{"title":"Error entry","type":"object","properties":{"fieldName":{"type":"string"},"errors":{"type":"array","items":{"type":"string","description":"Descriptive message of the error"}}}},"ValidationErrorResponse":{"type":"object","description":"Response when the object has validation issues.","oneOf":[{"type":"object","title":"General validation error","description":"Occurs when there is a general validation error","properties":{"errorType":{"type":"string","enum":["GeneralValidationError"]},"message":{"type":"string","description":"Descriptive message of the error"}}},{"type":"object","title":"Field validation error","description":"Occurs when there are validation issues with specific fields","properties":{"errorType":{"type":"string","enum":["FieldValidationError"]},"message":{"type":"string","description":"Descriptive message of the error"},"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ErrorFields"}}}}]}}}}