Overview

Use the Forecast API to automate predictions for available inventory in future time ranges.

Discovery forecast

The forecast API data matches the data in the Discovery forecast within the Equativ Monetization Platform. The legacy forecast, described in Use the forecast, doesn't use this API. As the underlying systems differ, you might see discrepancies.

Authentication

To learn how to authenticate, see Get started with Equativ APIs.

API limit

This API is subject to the global limit described in Get started with Equativ APIs: 60 requests per user, per minute.

Endpoint and use case

To retrieve forecast data, send a POST request to the following endpoint:

https://supply-api.eqtv.io/report

In the request body, include the configuration for your forecast data. You must set the useCaseId to forecast, as shown in the following snippet:

{
  "useCaseId": "forecast"
}

Properties

The following table provides all properties of the forecast API with details, descriptions and examples: 

The following snippet shows a configuration of forecast data with the properties mentioned in the previous section:

{
  "startDate": "2026-02-14T00:00:00",
  "endDate": "2026-02-15T00:00:00",
  "timezone": "Etc/UTC",
  "periodicity": "Day",
  "metrics": [
    "totalInventory",
    "availableImpressions",
    "bookedImpressions"
  ],
  "dimensions": [
    "appOrsiteId",
    "appOrsiteName"
  ],
  "filters": [],
  "sortBy": "availableImpressions",
  "sortAsc": "desc",
  "useCaseId": "forecast"
}  

Metrics

The Forecast API provides the following metrics:

• totalInventory: The available inventory (impressions available for sale), including reserved inventory from competing, guaranteed insertions.
• availableImpressions: The sum of available inventory and inventory booked by non-guaranteed insertions (priority lower than Normal 4).
• bookedImpressions: Inventory booked by guaranteed insertions (insertion priority greater than or equal to Normal 4).

Dimensions and filters

The following table lists each dimension and filter with the following information:

• Dimension / Filter: The name of the dimension and/or filter. Note that some exist only as filters, including audienceSegmentIdArray, packIdArray, or semanticSegmentIdArray. 
• Compatible filter operators: The operators you can use for filtering when requesting the given field.
• Reference endpoints: Use these endpoints to get all items of a given dimension. For example, use the reference endpoint GET /VideoAdBreakTypes to retrieve all video ad break types, including their Ids.
• Description: The description of the dimension or filter.  

Filter operators

Use the following operators to filter forecast data. To check compatibility by dimension, see column “Compatible filter operators” in the previous table.

Items within a list (inside a pair of squared brackets) are joined by OR logic, while the lists themselves are joined by AND logic.

The following snippet shows how to keep only the data matching the values 1234 or 5678 of the appOrSiteId field:

"startDate": "2026-02-14T00:00:00",
  "endDate": "2026-02-15T00:00:00",
  "timezone": "Etc/UTC",
  "periodicity": "Day",
  "metrics": [
    "totalInventory",
    "availableImpressions",
    "bookedImpressions"
  ],
  "dimensions": [
    "appOrsiteId",
    "appOrsiteName"
  ],
   "filters": [
    [
      {
        "operator": "in",
        "field": "appOrSiteId",
        "values": [
          1234,5678
        ]
      }
    ]
  ],
  "sortBy": "availableImpressions",
  "sortAsc": "desc"
  "useCaseId": "forecast"
}

To get only guaranteed competing insertions, you can set the gt (greater than) filter on the insertionPriorityId field. The following snippet gets competing insertions on the appOrSiteId with the Id 1234. The filter insertionPriorityId is set to “greater than 50” to include only the insertions on guaranteed priority levels.

{
 "metrics": [
   "bookedImpressions"
 ],
 "dimensions": [
   "insertionId",
   "insertionName",
   "insertionPriorityId"
 ],
 "startDate": "2026-02-14T00:00:00",
 "endDate": "2026-02-15T00:00:00",
 "filters": [
   [
     {
       "operator": "gt",
       "field": "insertionPriorityId",
       "values": [
         50
       ]
     }
   ],
       [
     {
       "operator": "IN",
       "field": "appOrSiteId",
       "values": [
         1234
       ]
     }
   ]
 ],

 "sortAsc": "desc",
 "timezone": "Etc/UTC",
 "useCaseId": "forecast"
}

Forecast data for complete day  

To request forecast data for a complete day, set the endDate to 00:00:00 of the following day.

For example, to cover all of September 1, 2025, set the following:

"startDate": "2025-09-01T00:00:00",
"endDate": "2025-09-02T00:00:00"

Setting the endDate to 2025-09-01T23:59:59 only includes forecast data from 2025-09-01T00:00:00 till 2025-09-01T23:00:00.

Output names

You can specify a custom outputName for a dimension or metric. The retrieved forecast data will then use the specified output name as column header, rather than the default name.

The following snippet shows how to change the field name seatName to customSeatName in the API response:

{
...
  "dimensions": [
    {
      "Field": "seatName",
      "OutputName": "customSeatName"
    }
  ]
...
}

Response sample

The following snippet shows an example of a response containing forecast data. A successful request returns a 200 OK status.

[
   {
       "totalInventory": 85369330,
       "bookedImpressions": 5454910,
       "availableImpressions": 79914420,
       "day": "1771027200000",
       "appOrSiteId": 1234,
       "appOrSiteName": "siteA"
   },
   {
       "totalInventory": 23462300,
       "bookedImpressions": 475870,
       "availableImpressions": 22986430,
       "day": "1771027200000",
       "appOrSiteId": 5678,
       "appOrSiteName": "siteB"
   }
]