---
title: "Impressions, clicks and spend forecast"
method: POST
path: "/v1/ads/targeting/supply-forecast"
tags: ["Ad Targeting"]
---

# Impressions, clicks and spend forecast

`POST /v1/ads/targeting/supply-forecast`

LinkedIn-only. Forecasted impressions, clicks, spend and ~20 other
metrics for a targeting spec over a time range. Wraps LinkedIn's
`adSupplyForecasts` finder.

Each returned series carries a `metricType` (IMPRESSION, CLICK, SPENDING,
MAX_POTENTIAL_BUDGET, COST_PER_MILLION_IMPRESSIONS, ...) and a
`granularity` (DAILY, SEVEN_DAY, THIRTY_DAY, CUSTOM). LinkedIn caps the
daily spending forecast at 1.2x the daily budget and returns 0 once the
total budget is exhausted.

Non-LinkedIn accounts return `available: false`.

## Request body

- object
  - `accountId` string, required
  - `adAccountId` string, required
  - `spec` TargetingSpec, required — Normalized, platform-agnostic ad-targeting spec. Every field is optional, an empty object targets the platform's default broadest audience. Field names are camelCase and identical across `POST /v1/ads/create` (the `targeting` object), `POST /v1/ads/targeting/reach-estimate`, and `saved_targeting` audiences, so a spec resolved once can be reused verbatim. Entity ids (`regions[].key`, `cities[].key`, `zips[].key`, `metros[].key`, `interests[].id`, `behaviors[].id`) are the platform's opaque identifiers resolved via `GET /v1/ads/targeting/search`. A spec is therefore meaningful only for the platform it was built against, except the portable fields (`countries`, `ageMin`/`ageMax`, `gender`, `incomeTier`, `languages`) which carry across platforms. Fields a platform cannot honour are rejected at create time with `INVALID_FIELD_VALUE` naming the offending field (not silently dropped).
    - `countries` string[] — ISO 3166-1 alpha-2 country codes (e.g. ['US']).
    - `regions` object[] — Region/state targeting. `key` is the platform location ID from /v1/ads/targeting/search?dimension=geo&geoType=region.
      - `key` string, required
      - `name` string
    - `cities` object[] — City targeting. Optional `radius` + `distanceUnit` extend beyond the city limits; both must be set together or both omitted. `radius` is only honoured on platforms whose capability map allows city radius (Meta).
      - `key` string, required
      - `name` string
      - `radius` number — Radius around the city. Requires distanceUnit. Meta enforces a minimum city radius (~17 km / 10 mi); smaller values resolve to a 0-size audience and the ad fails at launch. For a tighter catchment use customLocations (lat/lng), which allows a smaller radius.
      - `distanceUnit` 'mile' | 'kilometer' — Required if radius is set.
    - `zips` object[] — Postal/ZIP targeting. `key` is the platform's postal location ID (e.g. Meta `US:94304`). Supported on Meta, Google, TikTok, Pinterest, X.
      - `key` string, required
      - `name` string
    - `metros` object[] — DMA / metro-area targeting. `key` is the platform's metro ID (e.g. Meta `DMA:807`).
      - `key` string, required
      - `name` string
    - `customLocations` object[] — Point-radius (lat/lng) targeting (Meta custom_locations / Google proximity). Honoured only where the capability map allows radius (Meta).
      - `latitude` number, required
      - `longitude` number, required
      - `radius` number, required — Positive radius around the point.
      - `distanceUnit` 'mile' | 'kilometer', required
      - `name` string
      - `address` string — Optional label, sent to Meta as `address_string`. latitude/longitude take precedence for the pin location.
    - `excludedLocations` object — Geo to exclude from the audience. Mirrors the inclusion geo shape: excluded cities can carry a radius catchment and excluded custom (lat/lng) pins are supported, both on Meta (excluded_geo_locations).
      - `countries` string[]
      - `regions` object[]
        - `key` string, required
        - `name` string
      - `cities` object[] — Cities to exclude. Optional `radius` + `distanceUnit` exclude a catchment around the city (both must be set together or both omitted); Meta honours the radius on excluded cities.
        - `key` string, required
        - `radius` number — Radius around the excluded city. Requires distanceUnit.
        - `distanceUnit` 'mile' | 'kilometer' — Required if radius is set.
      - `zips` object[]
        - `key` string, required
        - `name` string
      - `places` object[] — Named points of interest to exclude. `key` from /v1/ads/targeting/search.
        - `key` string, required
      - `neighborhoods` object[] — Named neighbourhood areas to exclude. `key` from /v1/ads/targeting/search.
        - `key` string, required
      - `customLocations` object[] — Point-radius (lat/lng) pins to exclude (Meta excluded_geo_locations.custom_locations). Mirrors the inclusion customLocations shape.
        - `latitude` number, required
        - `longitude` number, required
        - `radius` number, required — Positive radius around the point.
        - `distanceUnit` 'mile' | 'kilometer', required
        - `name` string
        - `address` string — Optional label, sent to Meta as `address_string`. latitude/longitude take precedence for the pin location.
    - `ageMin` integer
    - `ageMax` integer
    - `gender` 'all' | 'male' | 'female' — Restrict by gender. 'all' (default) targets everyone. Applied on Meta, TikTok and Pinterest. Ignored on Google, LinkedIn and X.
    - `incomeTier` 'top_5' | 'top_10' | 'top_10_25' | 'top_25_50' — Normalized household-income tier (ZIP/percentile based). Meta and TikTok express all four. Google maps only `top_10` (its INCOME_RANGE_90_UP); other tiers on Google, and any income tier on LinkedIn / X / Pinterest, are rejected. On Meta, income/zip targeting requires the relevant `specialAdCategories` to be unset (housing/employment/credit ads cannot use it).
    - `languages` string[] — Language codes restricting the audience by language. On Meta, ISO 639-1 codes (e.g. ['en']); a bare code targets all regional variants ("en" = all English), or use a region-qualified code ("en_GB", "pt_BR") for a specific one. Unknown codes are rejected.
    - `interests` object[] — Interest entities from /v1/ads/targeting/search?dimension=interest. Each carries the platform's opaque id.
      - `id` string, required
      - `name` string
    - `behaviors` object[] — Behaviour entities from /v1/ads/targeting/search?dimension=behavior. Supported on Meta and TikTok.
      - `id` string, required
      - `name` string
    - `industries` string[] — LinkedIn B2B only. Industry URN id fragments.
    - `companySizes` string[] — LinkedIn B2B only.
    - `seniorities` string[] — LinkedIn B2B only.
    - `jobFunctions` string[] — LinkedIn B2B only.
    - `audienceInclude` string[] — Platform audience IDs to include.
    - `audienceExclude` string[] — Platform audience IDs to exclude.
  - `campaignType` 'SPONSORED_UPDATES' | 'SPONSORED_INMAILS' | 'DYNAMIC' — Defaults to SPONSORED_UPDATES.
  - `timeRangeStart` integer, required — Unix ms. Must be in the future.
  - `timeRangeEnd` integer, required — Unix ms. Must be after start and within LinkedIn's max horizon.
  - `objectiveType` string
  - `optimizationTarget` string — When set, the forecast assumes auto-bidding. When unset, competingBid is required.
  - `dailyBudget` number — Either dailyBudget or totalBudget is required.
  - `totalBudget` number
  - `currency` string — ISO 4217, defaults to USD.
  - `competingBid` object — Required for manual-bid forecasts (when optimizationTarget is not set).
    - `bidType` 'CPM' | 'CPC' | 'CPV', required
    - `amount` number, required
  - `enableAudienceNetwork` boolean — Defaults to false. Required true for connectedTelevisionOnly.
  - `enableAudienceExpansion` boolean — Defaults to false.
  - `connectedTelevisionOnly` boolean — Defaults to false.

## Response `200`

Forecast series

- object
  - `available` boolean, required
  - `forecast` object[]
    - `metricType` string
    - `granularity` 'DAILY' | 'SEVEN_DAY' | 'THIRTY_DAY' | 'CUSTOM'
    - `timeSeries` object[]
      - `timestamp` integer
      - `value` number
      - `adForecastRange` object
        - `lowEnd` number
        - `highEnd` number

## Other responses

- `400` — Invalid targeting, missing budget, or LinkedIn forecast validation error (e.g. END_DATE_MAX_HORIZON_FOR_FORECAST).
- `401` — Unauthorized
- `403` — Ads access required.
- `404` — Resource not found

---

[API](https://skmtc.net/zernio/apis/zernio-api.md) · [All operations](https://skmtc.net/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zernio/zernio-api/versions/51932b099b2f/schema)