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: "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: "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: "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"
  • bid_micro_amount
    integer [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.

    Minimum value: 1Example: 15000000
  • Required

    Budget used for estimation.

    • micro_amount
      integer [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
    • type
      string
      Required
      Allowed values: "DAILY", "LIFETIME"Example: "DAILY"
    • 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:


      _10
      sensitive_topic_exclusions: { topics: [ { id: "alcohol", filter_option: "RESTRICTED" } ] }

      Here is an example JSON for passing in a global filter:


      _10
      sensitive_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

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.

      Minimum value: 0Example: 2.1
    • estimated_frequency_min
      number [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_max
      integer [int64]

      The estimated maximum number of ads that will be served.

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

      The estimated minimum number of ads that will be served.

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

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

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

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

      Minimum value: 0Example: 10000
    • 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.

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

    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"    }  ],  "likely_to_deliver_budget": true}