Skip to content
Ads APIReferences / ad-sets / Get Ad Sets by Ad Account ID

Get Ad Sets by Ad Account ID

Get all ad sets for the ad account.

Request

  • ad_account_id
    string [uuid]
    Required

    A unique identifier for an Ad Account.

    Example: ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a
  • limit
    integer

    Limit or page size for a given response.

    Default: limit=50Range: 1 - 50Example: limit=50
  • offset
    integer

    Starting position of the next record to assist in data pagination.

    Default: offset=0Example: offset=0
  • sort_direction
    string

    Field by which to order the results of the query.

    Default: sort_direction=DESCAllowed values: "ASC", "DESC"Example: sort_direction=ASC
  • sort_field
    string

    Field by which to sort list of adsets.

    Default: sort_field=CREATED_ATAllowed values: "CREATED_AT", "UPDATED_AT"Example: sort_field=CREATED_AT
  • campaign_ids
    array of strings

    A list of Campaign IDs to fetch Ad Sets for only the given subset of Campaigns

    A unique identifier for the entity.

    Example: campaign_ids=ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a

Response

Ad set response.

    • page_size
      integer [int32]
    • total_results
      integer [int32]
    • offset
      integer [int32]
    • current_page
      integer [int32]
  • An ad set is the core component of your Ad Studio advertising campaign. It contains all the essential information Ad Studio needs to execute your campaign. For example, an ad set contains: Information about how, when, and where your campaign runs (e .g., start and end dates, budgets, targeting, etc). A single ad set can’t be used across multiple campaigns. A single ad set is associated with only one campaign.

    • name
      string

      Name given to identify the ad set.

      Length between 2 and 120Example: "New Ad Set"
    • start_time
      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"
    • end_time
      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"
    • 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
    • bid_micro_amount
      integer [int64]

      The amount of your bid per 1000 impressions, multiplied by x10 to the 6th power. Behavior of this field depends on the bid_strategy specified. Ex: In order to set a bid of $20, you would specify a bid_micro_amount of 20000000.

      Example: 1000000
    • delivery
      string

      Toggles the delivery of the entity ON or OFF.

      Allowed values: "ON", "OFF"Example: "ON"
    • id
      string [uuid]

      ID of the ad set.

      Supported content-type(s): Example: "39ff503e-4baa-4e7a-9dd2-4b3f49653801"
    • category
      string

      Category ID of the ad set.

      Example: "ADV_1_1"
    • campaign_id
      string [uuid]

      ID associated with the campaign that will contain one or more ad sets within it.

      Supported content-type(s): Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
    • 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"
    • created_at
      string [date-time]

      Date the entity was created. Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ

      Example: "2026-01-23T04:56:07Z"
    • updated_at
      string [date-time]

      Date the entity was updated. Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ

      Example: "2026-01-23T04:56:07Z"
    • asset_format
      string

      Format of the ad set.

      Allowed values: "AUDIO", "VIDEO"Example: "AUDIO"
    • Users should specify one budget when creating an ad set.

      • 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
        Read only
        Example: "USD"
    • This would be artist promo or podcast promo.

      • promotion_goal
        string
        Required

        "ARTIST_PROMO": Promote an artist's music on Spotify. With this goal, Streaming Conversion Metrics ("SCM"), which track how the ad set drove results for the artist on Spotify, will be enabled for the ad set. | "PODCAST_PROMO": Promote a podcast show.

        Allowed values: "ARTIST_PROMO", "PODCAST_PROMO"Example: "ARTIST_PROMO"
      • promotion_target_id
        string

        ID of the artist or podcast show to promote. This is required for "ARTIST_MUSIC_PROMO" and "PODCAST_PROMO".

        Example: "4q3ewBCX7sLwd24euuV69X"
      • Unique items

        For streaming conversion metrics.

        • tracking_event_type
          string
          Required

          The event type that will be tracked as a conversion.

          Allowed values: "IMPRESSION", "CLICKED", "COMPLETE"Example: "IMPRESSION"
        • window_duration_ms
          integer [int32]
          Required

          The window of time after an impression during which a conversion will be counted, expressed in milliseconds. Ex: To specify a conversion window of 14 days, input 121000000000 as the window_duration_ms.

          Range: 86400000 - 2147483647Example: 86400000
    • bid_strategy
      string

      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.
      • "UNSET": Ad sets that were pre-auction will not have a bid strategy set.
      Allowed values: "MAX_BID", "UNSET"Example: "MAX_BID"
    • reject_reason
      string

      The reason why the ad set was rejected.

      Example: "Your ad wasn’t approved. Create a new ad, or contact us at adstudio@spotify.com."
    • status
      string

      Status of the ad set.

      Allowed values: "ACTIVE", "APPROVED", "ARCHIVED", "COMPLETED", "PENDING_APPROVAL", "READY", "REJECTED"Example: "ACTIVE"
    • 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"
    • pacing
      string

      Set a pacing option to deliver your ads throughout the schedule of your ad set with standard pacing("PACING_EVEN"), or accelerated pacing("PACING_ASAP") to deliver your ads as quickly as possible.

      Default: "PACING_EVEN"Allowed values: "PACING_ASAP", "PACING_EVEN"Example: "PACING_EVEN"

Response sample

{  "paging": {    "page_size": 50,    "total_results": 116,    "offset": 0  },  "ad_sets": [    {      "name": "test reject - Test Ad set",      "start_time": "2023-08-23T04:56:07Z",      "end_time": "2023-08-26T04:56:07Z",      "frequency_caps": [        {          "frequency_unit": "DAY",          "frequency_period": 1,          "max_impressions": 2        }      ],      "bid_micro_amount": 10000000,      "delivery": "ON",      "id": "39ff503e-4baa-4e7a-9dd2-4b3f49653801",      "category": "ADV_1_1",      "campaign_id": "709076fe-2570-4dd9-94db-acc163e60fd8",      "cost_model": "CPM",      "created_at": "2023-07-26T05:54:47Z",      "updated_at": "2023-08-20T05:54:47Z",      "asset_format": "AUDIO",      "budget": {        "micro_amount": 500000000,        "type": "DAILY",        "currency": "USD"      },      "promotion": {        "promotion_goal": "ARTIST_PROMO",        "promotion_target_id": "1dfeR4HaWDbWqFHLkxsg1d",        "conversion_events": [          {            "tracking_event_type": "IMPRESSION",            "window_duration_ms": 86400000          }        ]      },      "bid_strategy": "MAX_BID",      "reject_reason": "",      "status": "PENDING_APPROVAL",      "targets": {        "age_ranges": [          {            "min": 18,            "max": 65          }        ],        "artist_ids": ["1dfeR4HaWDbWqFHLkxsg1d"],        "geo_targets": {          "country_code": "US",          "city_ids": [],          "dma_ids": ["500", "503"],          "postal_code_ids": ["US:73170"],          "region_ids": ["5101760"]        },        "genders": ["MALE"],        "genre_ids": ["alternative", "blues"],        "interest_ids": ["46b303e4-09a4-4c8e-998b-37186ff8120a", "365a5223-0024-4579-a881-3b08e8720021"],        "platforms": ["IOS"],        "podcast_episode_topic_ids": ["automotive", "books-and-literature"],        "sensitive_topic_exclusions": {          "topics": [            {              "id": "tobacco",              "filter_option": "RESTRICTED"            },            {              "id": "alcohol",              "filter_option": "PARTIAL"            }          ]        },        "language": "en",        "playlist_ids": ["holidays", "cooking"],        "exclude_placements": []      },      "bid_optimization_goal": "CLICKS"    },    {      "name": "test reject - Test Ad set",      "start_time": "2023-08-23T04:56:07Z",      "end_time": "2023-08-26T04:56:07Z",      "frequency_caps": [        {          "frequency_unit": "DAY",          "frequency_period": 1,          "max_impressions": 2        }      ],      "bid_micro_amount": 10000000,      "delivery": "ON",      "id": "86b54faf-3430-480b-80fd-4b1bad9cee7c",      "category": "ADV_1_1",      "campaign_id": "709076fe-2570-4dd9-94db-acc163e60fd8",      "cost_model": "CPM",      "created_at": "2023-07-25T23:11:27Z",      "updated_at": "2023-08-25T23:11:27Z",      "asset_format": "AUDIO",      "budget": {        "micro_amount": 500000000,        "type": "DAILY",        "currency": "USD"      },      "promotion": {        "promotion_goal": "ARTIST_PROMO",        "promotion_target_id": "1dfeR4HaWDbWqFHLkxsg1d",        "conversion_events": [          {            "tracking_event_type": "IMPRESSION",            "window_duration_ms": 86400000          }        ]      },      "bid_strategy": "MAX_BID",      "reject_reason": "",      "status": "PENDING_APPROVAL",      "targets": {        "age_ranges": [          {            "min": 18,            "max": 65          }        ],        "artist_ids": ["1dfeR4HaWDbWqFHLkxsg1d"],        "geo_targets": {          "country_code": "US",          "city_ids": [],          "dma_ids": ["500", "503"],          "postal_code_ids": ["US:73170"],          "region_ids": ["5101760"]        },        "genders": ["MALE"],        "genre_ids": ["alternative", "blues"],        "interest_ids": ["46b303e4-09a4-4c8e-998b-37186ff8120a", "365a5223-0024-4579-a881-3b08e8720021"],        "platforms": ["IOS"],        "podcast_episode_topic_ids": ["automotive", "books-and-literature"],        "sensitive_topic_exclusions": {          "topics": [            {              "id": "tobacco",              "filter_option": "RESTRICTED"            },            {              "id": "alcohol",              "filter_option": "PARTIAL"            }          ]        },        "language": "en",        "playlist_ids": ["holidays", "cooking"],        "exclude_placements": []      }    }  ]}