Ads API •References / estimates / Estimate audience

Estimate audience

Returns audience estimates based on specific ad set parameters.

Request

POST/estimates/audience

ad_account_idstring [uuid]
Required
A unique identifier for the entity.
Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
start_datestring [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: "2023-09-23T04:56:07Z"
end_datestring [date-time]
Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ
Example: "2023-09-23T04:56:07Z"
asset_formatstring
Required
Format of the asset.
Allowed values: "AUDIO", "VIDEO", "IMAGE"Example: "AUDIO"
objectivestring
Required
Deprecated
Deprecated: Use delivery_goal_group and delivery_goal on ad sets instead. Objective for a campaign. UNSET should not be used.
Default: "EVEN_IMPRESSION_DELIVERY"Allowed values: "UNSET", "REACH", "EVEN_IMPRESSION_DELIVERY", "CLICKS", "VIDEO_VIEWS", "PODCAST_STREAMS", "APP_INSTALLS", "WEBSITE_VISITS"Example: "EVEN_IMPRESSION_DELIVERY"
bid_strategystring
Required
Strategy for how bids will be applied in the auction.
- "MAX_BID": the bid_micro_amount will act as a bid cap, meaning the maximum amount paid per 1000 impressions.
Allowed values: "COST_PER_RESULT", "MAX_BID", "UNSET"Example: "MAX_BID"
bid_micro_amountinteger [int64]
Required
Bid for the ad set per 1,000 impressions multiplied by x10 to the 6th power. Ex: In order to set a bid of 15, you would specify a bid_micro_amount of 15000000. Must be greater than 0 unless use_recommended_bid is true.
Minimum value: 0Example: 15000000
Required
Budget used for estimation.
- micro_amountinteger [int64]
  Required
  Total budget for the ad set multiplied by x10 to the 6th power. Ex: In order to set a budget of $250, you would specify a budget_micro_amount of 250000000.
  Example: 15000000
- typestring
  Required
  Allowed values: "DAILY", "LIFETIME"Example: "DAILY"
- currencystring
  Required
  Currency should be in ISO 4217 format.
  Length between 3 and 3Example: "USD"
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 in the CREATE request, OR if an empty array [] is sent in the PATCH request.
Array maximum length: 3
Can utilize the 3 parameters to set a Frequency Cap by Day, Week and Month.
- frequency_unitstring
  Required
  Unit of time for the frequency cap.
  Allowed values: "DAY", "MONTH", "WEEK"Example: "DAY"
- frequency_periodinteger [int32]
  Required
  Period of time for the frequency cap. Ex: To specify a cap for a 1 day/week/month period, input 1 as the frequency_period.
  Minimum value: 1Example: 1
- max_impressionsinteger [int32]
  Required
  Maximum impressions per user over the frequency period.
  Minimum value: 1Example: 2
Required
The targeting used for this ad set.
- Age range(s) to target.
  mininteger [int32]
  Minimum age to target.
  Range: 13 - 99Example: 13
  maxinteger [int32]
  Maximum age to target.
  Default: 99Range: 13 - 99Example: 65
- artist_idsarray of strings
  Unique items
  ID(s) of artist(s) to target. In compliance with the Digital Services Act, fan targeting may not apply when targeting only minors in the United States, the United Kingdom, or a European Union member country, If the age targeting includes but is not limited to minors, fan targeting will apply but minors may be excluded.
  Example: ["06HL4z0CvFAxyc27GXpf02"]
- Geographical areas to target.
  - country_codestring
    Two-letter ISO code of the country to target.
    Example: "US"
  - city_idsarray of strings
    Unique items
    ID(s) of the city/cities to target.
    Example: ["4174700"]
  - dma_idsarray of strings
    Unique items
    ID(s) of the DMA(s) to target.
    Example: ["501"]
  - postal_code_idsarray of strings
    Unique items
    ID(s) of the postal codes(s) to target.
    Example: ["US:73170"]
  - region_idsarray of strings
    Unique items
    ID(s) of the region(s) to target.
    Example: ["5279468"]
- gendersarray of strings
  Unique items
  Name(s) of the gender to target. In compliance with the Digital Services Act, gender targeting may not apply when targeting only minors in the United States, the United Kingdom, or a European Union member country, If the age targeting includes but is not limited to minors, gender targeting will apply but minors may be excluded.
  Example: ["MALE","FEMALE","NON_BINARY"]
  Allowed values: "MALE", "FEMALE", "NON_BINARY"
- genre_idsarray of strings
  Unique items
  ID(s) of the genre(s) to target.
  Example: ["rock","blues"]
- interest_idsarray of strings
  Unique items
  ID(s) of the interest(s) to target. In compliance with the Digital Services Act, interest targeting may not apply when targeting only minors in the United States, the United Kingdom, or a European Union member country, If the age targeting includes but is not limited to minors, interest targeting will apply but minors may be excluded.
  Example: ["7ebe6459-5fea-4a50-887d-273c06080c78","46b303e4-09a4-4c8e-998b-37186ff8120a"]
- platformsarray of strings
  Unique items
  ID(s) of the platform(s) to target. If no platform targeting is passed, ["ANDROID", "DESKTOP", "IOS"] will be targeted by default in the CREATE request, OR if an empty array [] is sent in the PATCH request.
  Example: ["IOS"]
  Allowed values: "ANDROID", "DESKTOP", "IOS"
- podcast_episode_topic_idsarray of strings
  Unique items
  Podcast episode topics to target. Allowed values: automotive, books-and-literature, business-and-finance, careers, education, events-and-attractions, family-and-relationships, fine-art, food-and-drink, healthy-living, hobbies-and-interests, home-and-garden, medical-health, movies, music-and-audio, news-and-politics, personal-finance, pets, pop-culture, real-estate, religion-and-spirituality, science, shopping, sports, style-and-fashion, technology-and-computing, television, travel, video-gaming.
  Example: ["automotive","books-and-literature"]
- Exclude sensitive topics with a given filter level or pass a filter level for all sensitive topics. For example, passing tobacco with a restricted filter will prevent any ad targeting on podcast episodes associated with tobacco. Another example, passing a global filter will apply the filter to all available sensitive topics. Both topic-level filters and global filters cannot be passed at the same time. Allowed filter levels: standard, limited, partial, restricted Allowed sensitive topic ids: alcohol, crime-violence, drugs, gambling, hate-speech, pornography, terrorism, tobacco, weapons.
  
  Here is an example JSON for passing in topic-level filters:
  
  _10sensitive_topic_exclusions: { topics: [ { id: "alcohol", filter_option: "RESTRICTED" } ] }
  
  Here is an example JSON for passing in a global filter:
  
  _10sensitive_topic_exclusions: { filter_option: "PARTIAL" }
  - idstring
    Required
    filter_optionstring
    Required
    How restrictive the ads system should be when considering serving an ad on a particular podcast episode based on the sensitive topics associated with the episode. These filters can either be applied on a per topic basis or globally for all sensitive topics, but cannot be applied at both levels.
    Allowed values: "STANDARD", "PARTIAL", "LIMITED", "RESTRICTED"Example: "LIMITED"
  - filter_optionstring
    How restrictive the ads system should be when considering serving an ad on a particular podcast episode based on the sensitive topics associated with the episode. These filters can either be applied on a per topic basis or globally for all sensitive topics, but cannot be applied at both levels.
    Allowed values: "STANDARD", "PARTIAL", "LIMITED", "RESTRICTED"Example: "LIMITED"
- languagestring
  ID of the language to target. If no language targeting is passed, all languages will be targeted.
  Length between 2 and 2Example: "en"
- playlist_idsarray of strings
  Unique items
  ID(s) of the playlist(s) to target.
  Example: ["holidays","cooking"]
- placementsarray of strings
  Unique items
  This field is REQUIRED. Indicates surfaces in the client where the ad(s) will be served.
  Example: ["PODCAST","MUSIC"]
  Placement of the ad.
  Allowed values: "MUSIC", "PODCAST"Example: "MUSIC"
- audience_idsarray of strings
  ID(s) of audiences to target.
  A unique identifier for the entity.
  Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
- audience_ids_exclusionsarray of strings
  ID(s) of audiences to exclude from targeting.
  A unique identifier for the entity.
  Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
video_delivery_formatsarray of strings
Unique items
The allowed delivery formats of the ad set, which define how the ads within them will be shown to users. This field is only applicable for video ad sets. For video views campaigns, the only allowed value (and default value) is OPT_IN, for clicks campaigns, the only allowed value (and default value) is IN_STREAM, and for all other campaigns with video ad sets, the default is both OPT_IN and IN_STREAM.
Example: ["IN_STREAM","OPT_IN"]
Allowed values: "IN_STREAM", "OPT_IN"
categorystring
Category ID of the ad set.
Example: "ADV_1_1"

Response

Audience estimates response

The estimated audience size for daily or lifetime budget.
Array length between 1 and 3
- estimated_frequency_maxnumber [double]
  The estimated maximum number of times each user will be served your ad over the lifetime of the campaign.
  Minimum value: 0Example: 2.1
- estimated_frequency_minnumber [double]
  The estimated minimum number of times each user will be served your ad over the lifetime of the campaign.
  Minimum value: 0Example: 1
- estimated_impressions_maxinteger [int64]
  The estimated maximum number of ads that will be served.
  Minimum value: 0Example: 22000
- estimated_impressions_mininteger [int64]
  The estimated minimum number of ads that will be served.
  Minimum value: 0Example: 10000
- estimated_reach_maxinteger [int64]
  The estimated maximum number of unique users who will be served your ad at least once.
  Minimum value: 0Example: 21000
- estimated_reach_mininteger [int64]
  The estimated minimum number of unique users who will be served your ad at least once.
  Minimum value: 0Example: 10000
- estimated_cpm_maxinteger [int64]
  The estimated maximum CPM amount in micros for your ads. The currency of this amount is the same as the currency of the budget from the request.
  Example: 21000000
- estimated_cpm_mininteger [int64]
  The estimated minimum CPM amount in micros for your ads. The currency of this amount is the same as the currency of the budget from the request.
  Minimum value: 0Example: 14000000
- forecast_typestring
  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.
  Allowed values: "DAILY", "WEEKLY", "MONTHLY", "LIFETIME"Example: "DAILY"
- projected_unique_usersinteger [int64]
  The estimated number of unique users who are expected to be part of a particular audience segment or target group over a specified period.
  Minimum value: 0Example: 200
- raw_unique_usersinteger [int64]
  Exact unique users count in the past 7 days without extrapolating based on the frequency cap, budget and schedule.
- bid_estimate_mininteger [int64]
  The estimated smallest micro amount to bid in order to hit the desired audience.
  Example: 14000000
- bid_estimate_maxinteger [int64]
  The estimated largest micro amount to bid in order to hit the desired audience.
  Example: 21000000
- cost_modelstring
  Method used to determine how advertisers are charged for their ad campaigns.
  
  "CPM": Cost Per Thousand Impressions.
  
  "CPCL": Cost Per Thousand Listens.
  Allowed values: "CPM", "CPCL"Example: "CPM"
- currencystring
  Currency should be in ISO 4217 format.
  Length between 3 and 3Example: "USD"
likely_to_deliver_budgetboolean
Indicates the likelihood of spending most of the budget.
Example: 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"    }  ],  "bid_suggestion": {    "bid_estimate_min": 14000000,    "bid_estimate_max": 21000000,    "cost_model": "CPM",    "currency": "USD"  },  "likely_to_deliver_budget": true}