Ads API •References / ad-sets / Get Ad Set Drafts

Get Ad Set Drafts

Get a list of draft ad sets for the ad account.

Request

ad_account_idstring [uuid]
Required
A unique identifier for an Ad Account.
Example: ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a
limitinteger
Limit or page size for a given response.
Default: limit=50Range: 1 - 50Example: limit=50
offsetinteger
Starting position of the next record to assist in data pagination.
Default: offset=0Example: offset=0
campaign_idsarray 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
statusesarray of strings
Unique items
The set of enums that will be used to filter Ad Set by statuses. The filter will match any Ad Set that has one of the given statuses.
Status of the ad set.
Allowed values: "ACTIVE", "ACTIVE_RESTRICTED", "APPROVED", "ARCHIVED", "COMPLETED", "PENDING_APPROVAL", "READY", "REJECTED"Example: statuses=ACTIVE

Response

Ad Set Drafts response.

- page_sizeinteger [int32]
- total_resultsinteger [int32]
- offsetinteger [int32]
- current_pageinteger [int32]
- statusstring
  Status of the ad set.
  Allowed values: "ACTIVE", "ACTIVE_RESTRICTED", "APPROVED", "ARCHIVED", "COMPLETED", "PENDING_APPROVAL", "READY", "REJECTED"Example: "ACTIVE"
- draft_hierarchy_versioninteger
  Read only
  The version of the draft hierarchy. Required when publishing the campaign draft.
  Minimum value: 1Example: 1
- idstring [uuid]
  A unique identifier for the entity.
  Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
- created_atstring [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_atstring [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"
- campaign_idstring [uuid]
  Required
  A unique identifier for the entity.
  Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
- namestring
  Name given to identify the draft ad set.
  Maximum length: 200Example: "New Draft Ad Set"
- start_timestring
- end_timestring
- 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
- dataset_idstring
  The unique identifier for a dataset attached to an ad set.
  Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
- categorystring
  Category ID of the ad set.
  Example: "ADV_1_1"
- 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"
- base_rate_micro_amountinteger [int64]
  The base rate per 1000 impressions or actions, multiplied by x10 to the 6th power. Ex: In order to set a base rate of $15, you would specify a base_rate_micro_amount of 15000000.
  Example: 15000000
- List of cost modifiers to apply to the base rate.
  Cost modifier object containing rate adjustment information.
  idstring [uuid]
  Required
  Unique identifier for the cost modifier.
  Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
  namestring
  Required
  Name of the cost modifier.
  Example: "Premium Placement"
  ratenumber [double]
  Required
  Rate multiplier for the cost modifier.
  Example: 1.25
- Users should specify one budget when creating an ad set.
  micro_amountinteger [int64]
  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
  Allowed values: "DAILY", "LIFETIME"Example: "DAILY"
- bid_micro_amountinteger [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
- 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"
  Unique items
  Day parting targeting for the spotify user's time zone.
  Day parting targeting for the ad set.
  day_of_weekarray of strings
  List of days of the week to target.
  Allowed values: "SUNDAY", "MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY"
  List of hour ranges (0-23) to target.
  mininteger [int32]
  Start of the hour range (0-23, inclusive). Hour values represent the start of each 1-hour slot; for example, 9 means 9:00 AM.
  Range: 0 - 23
  maxinteger [int32]
  End of the hour range (0-23, inclusive). The end hour slot is fully included; for example, a max of 9 means targeting runs through the 9:00–10:00 AM slot, ending at 10:00 AM.
  Range: 0 - 23
- pacingstring
  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.
  Allowed values: "PACING_ASAP", "PACING_EVEN"Example: "PACING_EVEN"
- asset_formatstring
  Format of the asset.
  Allowed values: "AUDIO", "VIDEO", "IMAGE", "CATALOG"Example: "AUDIO"
- bid_strategystring
  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.
  
  "AUTOBID": bids are automatically set to optimize delivery.
  
  Allowed values: "COST_PER_RESULT", "MAX_BID", "AUTOBID", "UNSET"Example: "MAX_BID"
- mobile_app_idstring
  ID of the mobile app to be tied to this ad set.
  Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
- reservation_idstring
  ID of the reservation to be tied to this ad set.
  Example: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
- delivery_goalstring
  The delivery goal for the ad set.
  Allowed values: "UNSET", "IMPRESSIONS", "REACH", "VIDEO_VIEWS", "CLICKS", "PAGE_VIEWS", "APP_INSTALLS", "STREAMS", "LEADS"
- This would be artist promo or podcast promo.
  promotion_goalstring
  "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_idstring
  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_typestring
  Required
  The event type that will be tracked as a conversion.
  Allowed values: "IMPRESSION", "CLICKED", "COMPLETE"Example: "IMPRESSION"
  window_duration_msinteger [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: 28800000 - 2147483647Example: 86400000
- video_delivery_formatsarray of strings
  Unique items
  Example: ["IN_STREAM","OPT_IN"]
  Allowed values: "IN_STREAM", "OPT_IN"
- ias_campaign_idstring
  The unique identifier for ias enabled campaign.
- skad_enabledboolean
  Toggle to enable/disable SKAd network tracking for an iOS app id.
  Example: true
- success_metricstring
  Success metric for the AB Test.
  Length between 3 and 100Example: "E_CPC"
- slot_positionsarray of strings
  Allowed slot positions for ads in this ad set (constraint). Restricts which positions CREMA can select when creating ads. Values: PRE_ROLL, MID_ROLL, POST_ROLL.
  Slot position within podcast/video content. PRE_ROLL is before content, MID_ROLL is during, POST_ROLL is after. Used as ad set constraint (allowed positions) and ad placement. Shared with Ad slot_positions.
  Allowed values: "PRE_ROLL", "MID_ROLL", "POST_ROLL"

Response sample

{  "paging": {    "page_size": 0,    "total_results": 0,    "offset": 0,    "current_page": 0  },  "ad_set_drafts": [    {      "status": "ACTIVE",      "draft_hierarchy_version": 1,      "id": "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a",      "created_at": "2026-01-23T04:56:07Z",      "updated_at": "2026-01-23T04:56:07Z",      "campaign_id": "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a",      "name": "New Draft Ad Set",      "start_time": "string",      "end_time": "string",      "frequency_caps": [        {          "frequency_unit": "DAY",          "frequency_period": 1,          "max_impressions": 2        },        {          "frequency_unit": "WEEK",          "frequency_period": 1,          "max_impressions": 2        },        {          "frequency_unit": "MONTH",          "frequency_period": 1,          "max_impressions": 2        }      ],      "dataset_id": "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a",      "category": "ADV_1_1",      "cost_model": "CPM",      "base_rate_micro_amount": 15000000,      "cost_modifiers": [        {          "id": "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a",          "name": "Premium Placement",          "rate": 1.25        }      ],      "budget": {        "micro_amount": 15000000,        "type": "DAILY"      },      "bid_micro_amount": 1000000,      "targets": {        "age_ranges": [          {            "min": 13,            "max": 65          }        ],        "artist_ids": ["06HL4z0CvFAxyc27GXpf02"],        "geo_targets": {          "country_code": "US",          "city_ids": ["4174700"],          "dma_ids": ["501"],          "postal_code_ids": ["US:73170"],          "region_ids": ["5279468"]        },        "genders": ["MALE", "FEMALE", "NON_BINARY"],        "genre_ids": ["rock", "blues"],        "interest_ids": ["7ebe6459-5fea-4a50-887d-273c06080c78", "46b303e4-09a4-4c8e-998b-37186ff8120a"],        "platforms": ["IOS"],        "podcast_episode_topic_ids": ["automotive", "books-and-literature"],        "sensitive_topic_exclusions": {          "sensitive_topic_exclusions": {            "topics": [              {                "id": "alcohol",                "filter_option": "RESTRICTED"              },              {                "id": "tobacco",                "filter_option": "LIMITED"              }            ]          }        },        "language": "en",        "playlist_ids": ["holidays", "cooking"],        "placements": ["PODCAST", "MUSIC"],        "audience_ids": ["ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"],        "audience_ids_exclusions": ["ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"],        "user_day_parts": [          {            "day_of_week": ["SUNDAY"],            "hour_of_day": [              {                "min": 23,                "max": 23              }            ]          }        ]      },      "pacing": "PACING_EVEN",      "asset_format": "AUDIO",      "bid_strategy": "MAX_BID",      "mobile_app_id": "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a",      "reservation_id": "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a",      "delivery_goal": "UNSET",      "promotion": {        "promotion_goal": "ARTIST_PROMO",        "promotion_target_id": "4q3ewBCX7sLwd24euuV69X",        "conversion_events": [          {            "tracking_event_type": "IMPRESSION",            "window_duration_ms": 97400000          },          {            "tracking_event_type": "IMPRESSION",            "window_duration_ms": 86400000          }        ]      },      "video_delivery_formats": ["IN_STREAM", "OPT_IN"],      "ias_campaign_id": "string",      "skad_enabled": true,      "success_metric": "E_CPC",      "slot_positions": ["PRE_ROLL"]    }  ]}