Ads API •References / estimates / Estimate bid

Estimate bid

Returns a bid estimate (recommended bid range) based on specific ad set parameters.

Request

POST

/estimates/bid

start_date
string [date-time]
Deprecated
Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ
Supported content-type(s): Example: "2023-09-23T04:56:07Z"
end_date
string [date-time]
Deprecated
Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ
Supported content-type(s): Example: "2023-09-23T04:56:07Z"
asset_format
string
Required
Format of the ad set.
Allowed values: "AUDIO", "VIDEO"Example: "AUDIO"
objective
string
Required
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"Example: "EVEN_IMPRESSION_DELIVERY"
bid_strategy
string
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: "MAX_BID"Example: "MAX_BID"
currency
string
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.
Array maximum length: 3
Can utilize the 3 parameters to set a Frequency Cap by Day, Week and Month.
- frequency_unit
  string
  Required
  Unit of time for the frequency cap.
  Allowed values: "DAY", "MONTH", "WEEK"Example: "DAY"
- frequency_period
  integer [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_impressions
  integer [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.
  min
  integer [int32]
  Minimum age to target.
  Range: 13 - 99Example: 13
  max
  integer [int32]
  Maximum age to target.
  Default: 99Range: 13 - 99Example: 65
- artist_ids
  array 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_code
    string
    Two-letter ISO code of the country to target.
    Example: "US"
  - city_ids
    array of strings
    Unique items
    ID(s) of the city/cities to target.
    Example: ["4174700"]
  - dma_ids
    array of strings
    Unique items
    ID(s) of the DMA(s) to target.
    Example: ["501"]
  - postal_code_ids
    array of strings
    Unique items
    ID(s) of the postal codes(s) to target.
    Example: ["US:73170"]
  - region_ids
    array of strings
    Unique items
    ID(s) of the region(s) to target.
    Example: ["5279468"]
- genders
  array 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_ids
  array of strings
  Unique items
  ID(s) of the genre(s) to target.
  Example: ["rock","blues"]
- interest_ids
  array 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"]
- platforms
  array of strings
  Unique items
  ID(s) of the platform(s) to target.
  Example: ["IOS"]
  Allowed values: "IOS", "DESKTOP", "ANDROID"
- podcast_episode_topic_ids
  array 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"]
- sensitive_topic_exclusion_ids
  array of strings
  Unique items
  Deprecated
  Sensitive topics to avoid targeting in podcast episodes. Allowed sensitive topic ids: alcohol, crime-violence, drugs, gambling, hate-speech, pornography, terrorism, tobacco, weapons. In the future, this field is being deprecated and no longer supported in favor of sensitive_topic_exclusions.
  Example: ["alcohol","crime-violence"]
- 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" }
  - id
    string
    Required
    filter_option
    string
    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_option
    string
    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"
- language
  string
  ID of the language to target. If no language targeting is passed, all languages will be targeted.
  Length between 2 and 2Example: "en"
- playlist_ids
  array of strings
  Unique items
  ID(s) of the playlist(s) to target.
  Example: ["holidays","cooking"]
- exclude_placements
  array of strings
  Unique items
  The placements to exclude for targeting.
  Example: ["PODCAST"]
  Allowed values: "PODCAST"

Response

Bid estimate response

bid_estimate_min
integer [int64]
The estimated smallest micro amount to bid in order to hit the desired audience.
Example: 14000000
bid_estimate_max
integer [int64]
The estimated largest micro amount to bid in order to hit the desired audience.
Example: 21000000
cost_model
string
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"
currency
string
Currency should be in ISO 4217 format.
Length between 3 and 3Example: "USD"

Response sample

{  "bid_estimate_min": 14000000,  "bid_estimate_max": 21000000,  "cost_model": "CPM",  "currency": "USD"}