--- title: "Get forecast" method: GET path: "/forecaster/{Id}" tags: ["Forecast"] --- # Get forecast `GET /forecaster/{Id}` Get the status and potential results of a running forecast. ## Path parameters - `Id` string, required ## Response `200` Normal response, containing JSON response object for a final result. - object - `id` string — The id of the requested forecast. It must be used when querying for the forecast results. - `desc` string — A textual description of the forecast execution status. - `eta` string — 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). - `status` 'enqueued' | 'started' | 'cancelled' | 'partial' | 'finished' | 'failed' — The status of the forecast execution. When forecasts are requested the result will always be "enqueued". Forecasts can transition between states during their processing. The states have the following meaning: * _enqueued_: The forecast request was accepted but hasn't started being processed yet. * _started_: The forecast request has started to be processed, but there are no partial results yet. * _cancelled_: The forecast request was cancelled by a user. * _partial_: The forecast has partial results. * _finished_: The forecast was completed. * _failed_: The forecast failed its execution. - `progress` number — The progress of the forecast request. It can be a number between 0.0 and 100.0. A forecast with progress 100.0 is finished. - `requestDateTime` string — The time at which the request for this forecast was received, in UTC. - `lastUpdateDateTime` string — The time at which the information for the forecast request was last updated, in UTC. - `startDateTime` string — 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). - `endDateTime` string — 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%). - `forecastStartDate` string, date-time — 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, but it can suffer some adjustments due to the availability of future traffic. - `forecastEndDate` string, date-time — 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. - `resultStatus` 'success' | 'failure' — Whether an error happened while executing the forecast. - `result` union — 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. - object — The current existing forecast type results, when available (only partial and finished status). - `total` union — The number of clicks, impressions, revenue, unique users, and custom events computed as the result of the forecast request. Clicks, impressions, and revenue are calculated over the entire lifetime of each ad, including values from past delivery. The number of unique users represents the projected reach -- that is, users the ad is expected to reach in the future. - object - object - object - object - `byAd` object — 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`. IDs from reserved campaigns are prefixed with "rc-" (e.g., "rc-123"). - `grouped` object[] — A list of objects with information about the number of expected future clicks, impressions, revenue, unique users, and unique users indexed by the `GroupBy` keys specified in the forecast request. - `key` object — 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. - `value` Total — unresolved $ref - `groupedFiltered` union — The combined number of expected future clicks, impressions, revenue, and custom events that were filtered out with the `FilterGroupBy` rule. - object - object - object - object - `byAd` object — 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`. IDs from reserved campaigns are prefixed with "rc-" (e.g., "rc-123"). - object — The current availability forecast type results, when available (only for partial and finished status). - `total` object — The number of expected future available and booked clicks, impressions, revenue, unique users, and custom events computed as the result of the forecast request. - `available` union - object - `clicks` number — Number of total forecasted available clicks. - `impressions` number — Number of total forecasted available impressions. - `revenue` number — Amount of total forecasted available revenue. - `uniqueUsers` number — Number of total forecasted available unique users. - `events` object — 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. - `metrics` Metrics — unresolved $ref - object - `clicks` number — Number of total forecasted available clicks. - `impressions` number — Number of total forecasted available impressions. - `revenue` number — Amount of total forecasted available revenue. - `uniqueUsers` number — Number of total forecasted available unique users. - `events` object — 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. - `metrics` Metrics — unresolved $ref - object - `clicks` number — Number of total forecasted available clicks. - `impressions` number — Number of total forecasted available impressions. - `revenue` number — Amount of total forecasted available revenue. - `uniqueUsers` number — Number of total forecasted available unique users. - `events` object — 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. - `metrics` Metrics — unresolved $ref - object - `clicks` number — Number of total forecasted available clicks. - `impressions` number — Number of total forecasted available impressions. - `revenue` number — Amount of total forecasted available revenue. - `uniqueUsers` number — Number of total forecasted available unique users. - `events` object — 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. - `metrics` Metrics — unresolved $ref - `byAd` object — 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`. IDs from reserved campaigns are prefixed with "rc-" (e.g., "rc-123"). - `uncapped` union - object - `clicks` number — Number of total forecasted available clicks ignoring frequency and daily caps. - `impressions` number — Number of total forecasted available impressions ignoring frequency and daily caps. - `revenue` number — Amount of total forecasted available revenue ignoring frequency and daily caps. - `uniqueUsers` number — Number of total forecasted available unique users ignoring frequency and daily caps. - `events` object — 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. - `metrics` Metrics — unresolved $ref - object - `clicks` number — Number of total forecasted available clicks ignoring frequency and daily caps. - `impressions` number — Number of total forecasted available impressions ignoring frequency and daily caps. - `revenue` number — Amount of total forecasted available revenue ignoring frequency and daily caps. - `uniqueUsers` number — Number of total forecasted available unique users ignoring frequency and daily caps. - `events` object — 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. - `metrics` Metrics — unresolved $ref - object - `clicks` number — Number of total forecasted available clicks ignoring frequency and daily caps. - `impressions` number — Number of total forecasted available impressions ignoring frequency and daily caps. - `revenue` number — Amount of total forecasted available revenue ignoring frequency and daily caps. - `uniqueUsers` number — Number of total forecasted available unique users ignoring frequency and daily caps. - `events` object — 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. - `metrics` Metrics — unresolved $ref - object - `clicks` number — Number of total forecasted available clicks ignoring frequency and daily caps. - `impressions` number — Number of total forecasted available impressions ignoring frequency and daily caps. - `revenue` number — Amount of total forecasted available revenue ignoring frequency and daily caps. - `uniqueUsers` number — Number of total forecasted available unique users ignoring frequency and daily caps. - `events` object — 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. - `metrics` Metrics — unresolved $ref - `byAd` object — 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`. IDs from reserved campaigns are prefixed with "rc-" (e.g., "rc-123"). - `booked` union - object - `clicks` number — Number of total forecasted booked clicks. - `impressions` number — Number of total forecasted booked impressions. - `revenue` number — Amount of total forecasted booked revenue. - `uniqueUsers` number — Number of total forecasted booked unique users. - `events` object — 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. - `metrics` Metrics — unresolved $ref - object - `clicks` number — Number of total forecasted booked clicks. - `impressions` number — Number of total forecasted booked impressions. - `revenue` number — Amount of total forecasted booked revenue. - `uniqueUsers` number — Number of total forecasted booked unique users. - `events` object — 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. - `metrics` Metrics — unresolved $ref - object - `clicks` number — Number of total forecasted booked clicks. - `impressions` number — Number of total forecasted booked impressions. - `revenue` number — Amount of total forecasted booked revenue. - `uniqueUsers` number — Number of total forecasted booked unique users. - `events` object — 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. - `metrics` Metrics — unresolved $ref - object - `clicks` number — Number of total forecasted booked clicks. - `impressions` number — Number of total forecasted booked impressions. - `revenue` number — Amount of total forecasted booked revenue. - `uniqueUsers` number — Number of total forecasted booked unique users. - `events` object — 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. - `metrics` Metrics — unresolved $ref - `byAd` object — 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`. IDs from reserved campaigns are prefixed with "rc-" (e.g., "rc-123"). - `inventory` object - `bookedAtHigher` object - `clicks` number — Number of total forecasted clicks booked by existing ads with a higher priority/bid. - `impressions` number — Number of total forecasted impressions booked by existing ads with a higher priority/bid. - `revenue` number — Amount of total forecasted revenue booked by existing ads with a higher priority/bid. - `uniqueUsers` number — Number of total forecasted unique users booked by existing ads with a higher priority/bid. - `events` object — 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. - `metrics` Metrics — unresolved $ref - `bookedAtLower` object - `clicks` number — Number of total forecasted clicks inventory booked by existing ads with a lower priority/bid. - `impressions` number — Number of total forecasted impressions inventory booked by existing ads with a lower priority/bid. - `revenue` number — Amount of total forecasted revenue inventory booked by existing ads with a lower priority/bid. - `uniqueUsers` number — Number of total forecasted unique users inventory booked by existing ads with a lower priority/bid. - `events` object — 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. - `metrics` Metrics — unresolved $ref - `empty` object - `clicks` number — Number of total forecasted clicks inventory not booked by any existing ad. - `impressions` number — Number of total forecasted impressions inventory not booked by any existing ad. - `uniqueUsers` number — Number of total forecasted unique users inventory not booked by any existing ad. - `events` object — 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. - `metrics` Metrics — unresolved $ref - `metrics` object — Aggregated metric values keyed by the user-chosen names from `.Params.Include.Metrics`. The value is the configured aggregation of the metric's source over forecasted data. Sources that have no match over forecasted data omit the metric field entirely. - `grouped` object[] — A list of objects containing information about the number of expected future available, uncapped, and booked clicks, impressions, revenue, unique users, and custom events indexed by the `GroupBy` keys specified in the forecast request. - `key` object — 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. - `values` object - `booked` Booked — unresolved $ref - `inventory` Inventory — unresolved $ref - `groupedFiltered` object — The combined number of expected future available, uncapped, and booked clicks, impressions, revenue, and custom events that were filtered out with the `FilterGroupBy` rule. - `booked` object - `clicks` number — Number of forecasted clicks that were filtered out. - `impressions` number — Number of forecasted impressions that were filtered out. - `revenue` number — Amount of forecasted revenue that was filtered out. - `events` object — 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. - object — The current deliverable forecast type results, when available (only partial and finished status). - `total` Total — unresolved $ref - `grouped` Items[] — A list of objects with information about the number of expected future clicks, impressions, revenue, unique users, and unique users indexed by the group by keys specified in the forecast request. — unresolved $ref - `groupedFiltered` GroupedFiltered — unresolved $ref - string - `warnings` object[], nullable — 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. The 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. - `code` 'DATETRF' | 'MODTRF' | 'OVRTRF' | 'PERFWRN' | 'TRCEND' | 'UNRFLD' | 'UNSEVT' — The short code specific to each type of warning, which are: * _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. * _MODTRF_: Raised whenever a traffic modifier is applied during a simulation. * _OVRTRF_: Raised whenever there is an overlap between two or more traffic modifiers that were applied in a simulation. * _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. * _TRCEND_: Raised only with available forecast requests and happens when the forecast end-date is automatically truncated to match the internal cache. * _UNRFLD_: Raised when the forecast request has unrecognized fields that will be ignored. * _UNSEVT_: Raised when the forecast request includes event types (through the `.Params.Include.Events` field) that aren't configured for the network. - `message` string — Descriptive message of the warning. When related to traffic modifiers, it contains the IDs of the relevant traffic modifiers. - `causes` string[], nullable — 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. - `metadata` object, nullable - `forecastEnvironment` object — Information relative with the data considered at the time of the forecast. - `campaignSyncDateTime` string — The synchronization date time in UTC for the campaigns considered for the forecast. - `seasonalityUsed` boolean — Whether the seasonality was considered for the forecast. - `reservedCampaignsSyncDateTime` string — The synchronization date time in UTC for the reserved campaigns considered for the forecast. - `reservedCampaignSalesWeightCutOff` integer — The sales weight cut-off percentage used to filter reserved campaigns for the forecast. ## Other responses - `202` — Normal response, containing JSON response object for a partial result. - `400` — Error response, containing error message. - `404` — Forecast ID not found. --- [API](https://skmtc.net/kevel/apis/engine-apis.md) · [All operations](https://skmtc.net/kevel/apis/engine-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kevel/engine-apis/revisions/0ca55f45aa7d/schema)