POST /v3/universalforecasting/generate → forecastCreate

Overview

Parity note: forecastCreate creates a persisted forecast entity (optionally calculated asynchronously). It does not accept the REST UniversalForecastingRequest body or return the ephemeral universal forecast response from REST generate. Inputs such as bid-list arrays, forecasting audiences, Nielsen demographic settings, and budget-point generation flags are Not currently available in GraphQL. Synchronous outputs such as inline MetricResults, BudgetMetrics, and ReachCurveData are Not currently available in GraphQL on create—poll Forecast.status and read adGroupLevelForecastResults after calculation completes.

Multi-step operations

GraphQL forecastCreate creates a forecast record and may compute results asynchronously (isAsync). After creation, query the forecast by id and inspect status and adGroupLevelForecastResults for calculated metrics. REST path: /v3/universalforecasting/generate (not /v3/forecasting/universal).

Input field mapping

Input type: ForecastCreateInput

Output field mapping

Output type: PayloadWithErrorsOfForecast → data: Forecast

Endpoint-specific nested types and enums

Most inputs below are Not currently available in GraphQL on forecastCreate.

BidLine (within NewBidList.BidLines)

REST BidLine objects on UniversalForecastingBidLists are Not currently available in GraphQL on forecastCreate. When creating bid lists through GraphQL bid-list mutations, use BidLineCreateInput.

NewBidList

ForecastingAudience

DataGroup (within ForecastingAudience)

NielsenDemographicSettings

UniversalForecastingInsightMetricResult

UniversalForecastInsightMetricType

Impressions, Spend, FrequencyUsers, FrequencyPeople, FrequencyHousehold, ReachUsers, ReachPeople, ReachHousehold, Reach, Frequency, OTP, LinearTVReach, DigitalReach, UsDemographicPercentages, SambaUniqueUserCount, and additional REST-only forecast metric fields. Not currently available in GraphQL.

UniversalForecastingContractMetricResult

UniversalForecastingContractGroupMetricResult

UniversalForecastingContractGeoTypeMetricResult

UniversalForecastingContractGeoMetricResult

GeoSegmentFilter

CustomOnly, StandardOnly, All, Country, Region, City, Zip, Metro (Deprecated on REST), CongressionalDistrict, NielsenDma. Not currently available in GraphQL.

IncrementalForecast

Range

ReachPerChannel

ReachCurveDataPoint

UniversalForecastingScaledFrequencyMapsResult

Audience (response nested object)

Code examples

REST example

POST /v3/universalforecasting/generate HTTP/1.1
Content-Type: application/json
TTD-Auth: AUTH_TOKEN_PLACEHOLDER

{
  "AdvertiserId": "adv-abc123",
  "TimeWindow": 30,
  "AverageBidCPMInAdvertiserCurrency": 5.50,
  "AudienceId": "aud-xyz789",
  "UseCrossDevice": true,
  "UseCtvCrossDevice": true,
  "GenerateBudgetPoints": true,
  "Demographic": {
    "StartAge": "TwentyFive",
    "EndAge": "FortyNine",
    "Gender": "All"
  }
}

GraphQL example

POST /graphql HTTP/1.1
Content-Type: application/json
TTD-Auth: AUTH_TOKEN_PLACEHOLDER

mutation CreateForecast($input: ForecastCreateInput!) {
  forecastCreate(input: $input) {
    data {
      id
      name
      status
      isAsync
      advertiser {
        id
      }
      adGroupLevelForecastResults {
        lastCalculatedAt
        durationInDays
        availsNumber
        spend
        curves {
          budget
          impressions
          personsReach
          averageFrequency
        }
        valuesAtInputBudget {
          impressions
          personsReach
          averageFrequency
          relevance
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}

Variables:

{
  "input": {
    "name": "Q3 reach forecast",
    "advertiserId": "adv-abc123",
    "forecastMode": "STANDARD",
    "reachType": "PERSON",
    "cpm": {
      "amount": 5.50,
      "currencyCode": "USD"
    },
    "isAsync": true
  }
}