Ads API •References / ad-sets / Get ad set by ID

Get ad set by ID

Get an ad set by ID.

Request

ad_account_id
string [uuid]
Required
A unique identifier for an Ad Account.
Example value: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
ad_set_id
string [uuid]
Required
A unique identifier for the entity.
Example value: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"

Response

Ad set response.

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.
Example value: "New Ad Set"Length between 2 and 120
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 value: "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 value: "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.
  Example value: "DAY"Allowed values: "DAY", "MONTH", "WEEK"
- 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.
  Example value: 1Minimum value: 1
- max_impressions
  integer [int32]
  Required
  Maximum impressions per user over the frequency period.
  Example value: 2Minimum value: 1
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 value: 1000000
delivery
string
Toggles the delivery of the entity ON or OFF.
Example value: "ON"Default value: "ON"Allowed values: "ON", "OFF"
id
string [uuid]
ID of the ad set.
Example value: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"Supported content-type(s):
category
string
Category ID of the ad set.
Example value: "ADV_1_1"
campaign_id
string [uuid]
ID associated with the campaign that will contain one or more ad sets within it.
Example value: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"Supported content-type(s):
cost_model
string
Method used to determine how advertises are charged for their ad campaigns.
- "CPM": Cost Per Thousand Impressions.
- "CPCL": Cost Per Thousand Listens.
Example value: "CPM"Allowed values: "CPM", "CPCL"
created_at
string [date-time]
Date the ad set was created. Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ
Example value: "2026-01-23T04:56:07Z"
updated_at
string [date-time]
Date the ad set was updated. Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ
Example value: "2026-01-23T04:56:07Z"
asset_format
string
Format of the ad set.
Example value: "AUDIO"Allowed values: "AUDIO", "VIDEO"
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 value: 15000000
- type
  string
  Required
  Example value: "DAILY"Allowed values: "DAILY", "LIFETIME"
- currency
  string
  Read only
  Example value: "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.
  Example value: "ARTIST_PROMO"Allowed values: "ARTIST_PROMO", "PODCAST_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 value: "4q3ewBCX7sLwd24euuV69X"
- Unique items
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.
Example value: "MAX_BID"Allowed values: "MAX_BID", "UNSET"
reject_reason
string
The reason why the ad set was rejected.
Example value: "Your ad wasn’t approved. Create a new ad, or contact us at adstudio@spotify.com."
status
string
Status of the ad set.
Example value: "ACTIVE"Allowed values: "ACTIVE", "APPROVED", "ARCHIVED", "COMPLETED", "PENDING_APPROVAL", "READY", "REJECTED"
The targets used during the creation of an ad set.
- Age range(s) to target.
- artist_ids
  array of strings
  Unique items
  ID(s) of artist(s) to target.
  Example value: ["06HL4z0CvFAxyc27GXpf02"]
- Geographical areas to target.
- genders
  array of strings
  Unique items
  Name(s) of the gender to target. MALE, FEMALE and NON_BINARY are allowed.
  Example value: ["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 value: ["rock","blues"]
- interest_ids
  array of strings
  Unique items
  ID(s) of the interest(s) to target.
  Example value: ["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 value: ["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 value: ["automotive","books-and-literature"]
- sensitive_topic_exclusion_ids
  array of strings
  Unique items
  Exclude sensitive topics. Allowed values: alcohol, crime-violence, drugs, gambling, hate-speech, pornography, terrorism, tobacco, weapons
  Example value: ["alcohol","crime-violence"]
- language
  string
  ID of the language to target.
  Example value: "en"Length between 2 and 2
- playlist_ids
  array of strings
  Unique items
  ID(s) of the playlist(s) to target.
  Example value: ["holidays","cooking"]
- exclude_placements
  array of strings
  Unique items
  The placements to exclude for targeting.
  Example value: ["PODCAST"]
  Allowed values: "PODCAST"

Response sample

{  "name": "test reject - Test Ad set",  "start_time": "2023-09-23T04:56:07Z",  "end_time": "2023-09-26T04:56:07Z",  "frequency_caps": [    {      "frequency_unit": "DAY",      "frequency_period": 1,      "max_impressions": 2    }  ],  "bid_micro_amount": 10000000,  "delivery": "ON",  "id": "d936ecbb-3a93-4cfa-b756-c61811c6cdc3",  "category": "ADV_1_1",  "campaign_id": "5bbc4fec-c9a5-4fc6-98f4-e950f40b74c7",  "cost_model": "CPM",  "created_at": "2023-07-28T17:55:12Z",  "updated_at": "2023-09-28T17:55:12Z",  "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",  "status": "PENDING_APPROVAL",  "targets": {    "age_ranges": [      {        "min": 18,        "max": 65      }    ],    "artist_ids": ["1dfeR4HaWDbWqFHLkxsg1d"],    "geo_targets": {      "country_code": "US",      "city_ids": [],      "dma_ids": ["503", "500"],      "postal_code_ids": ["US:73170"],      "region_ids": ["5101760"]    },    "genders": ["MALE", "FEMALE"],    "genre_ids": ["blues", "alternative"],    "interest_ids": ["365a5223-0024-4579-a881-3b08e8720021", "46b303e4-09a4-4c8e-998b-37186ff8120a"],    "platforms": ["IOS"],    "podcast_episode_topic_ids": ["books-and-literature", "automotive"],    "sensitive_topic_exclusion_ids": ["alcohol", "crime-violence"],    "language": "en",    "playlist_ids": ["cooking", "holidays"],    "exclude_placements": []  }}