Skip to content
Ads APIReferences / estimates / Estimate audience

Estimate audience

Returns audience estimates based on specific ad set parameters.

Request

POST
/estimates/audience
  • ad_account_id
    string [uuid]
    Required

    A unique identifier for the entity.

    Example value: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
  • start_date
    string [date-time]
    Required

    Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ

    Example value: "2023-09-23T04:56:07Z"
  • end_date
    string [date-time]

    Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ

    Example value: "2023-09-23T04:56:07Z"
  • asset_format
    string
    Required

    Format of the ad set.

    Example value: "AUDIO"Allowed values: "AUDIO", "VIDEO"
  • objective
    string
    Required

    Objective for a campaign (UNSET cannot be provided as an input)

    Example value: "EVEN_IMPRESSION_DELIVERY"Default value: "EVEN_IMPRESSION_DELIVERY"Allowed values: "REACH", "EVEN_IMPRESSION_DELIVERY", "CLICKS", "UNSET"
  • bid_strategy
    string
    Required

    Strategy for how bids will be applied in the auction. Allowed values:

    • "MAX_BID": The bid_micro_amount will act as a bid cap, meaning the maximum amount paid per 1000 impressions.
    Example value: "MAX_BID"Allowed values: "MAX_BID"
  • Required

    Budget used for estimation.

  • Unique items

    Specify maximum impressions per user over a given period of time. Will default to the maximum (5 per day, 35 per week, 50 per month) if not specified.

    Array maximum length: 3
  • Required

    The targets used during the creation of an ad set.

Response

Audience estimates response

  • The estimated audience size for daily or lifetime budget.

    Array length between 1 and 3
    • estimated_frequency_max
      number [double]

      The estimated maximum number of times each user will be served your ad over the lifetime of the campaign.

      Example value: 2.1Minimum value: 0
    • estimated_frequency_min
      number [double]

      The estimated minimum number of times each user will be served your ad over the lifetime of the campaign.

      Example value: 1Minimum value: 0
    • estimated_impressions_max
      integer [int64]

      The estimated maximum number of ads that will be served.

      Example value: 22000Minimum value: 0
    • estimated_impressions_min
      integer [int64]

      The estimated minimum number of ads that will be served.

      Example value: 10000Minimum value: 0
    • estimated_reach_max
      integer [int64]

      The estimated maximum number of unique users who will be served your ad at least once.

      Example value: 21000Minimum value: 0
    • estimated_reach_min
      integer [int64]

      The estimated minimum number of unique users who will be served your ad at least once.

      Example value: 10000Minimum value: 0
    • forecast_type
      string

      The time granularity of the forecast -- if a "LIFETIME" budget type is specified, the API will return a single "LIFETIME" forecast type and if a "DAILY" budget type is specified, the API will return "DAILY", "WEEKLY" and "MONTHLY" forecast types.

      Example value: "DAILY"Allowed values: "DAILY", "WEEKLY", "MONTHLY", "LIFETIME"
  • likely_to_deliver_budget
    boolean

    Indicates the likelihood of spending most of the budget.

    Example value: true

Response sample

{  "audience_forecast": [    {      "estimated_frequency_max": 2.1,      "estimated_frequency_min": 1,      "estimated_impressions_max": 22000,      "estimated_impressions_min": 10000,      "estimated_reach_max": 21000,      "estimated_reach_min": 10000,      "forecast_type": "DAILY"    },    {      "estimated_frequency_max": 2.1,      "estimated_frequency_min": 1,      "estimated_impressions_max": 144000,      "estimated_impressions_min": 70000,      "estimated_reach_max": 142000,      "estimated_reach_min": 70000,      "forecast_type": "WEEKLY"    },    {      "estimated_frequency_max": 2.1,      "estimated_frequency_min": 1,      "estimated_impressions_max": 660000,      "estimated_impressions_min": 340000,      "estimated_reach_max": 650000,      "estimated_reach_min": 320000,      "forecast_type": "MONTHLY"    }  ],  "likely_to_deliver_budget": true}