Get ad set by ID
Get an ad set by ID.
Request
- ad_account_idstring [uuid]Required
A unique identifier for an Ad Account.
Example value:"ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
- ad_set_idstring [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.
- namestring
Name given to identify the ad set.
Example value:"New Ad Set"
Length between2
and120
- start_timestring [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_timestring [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_unitstringRequired
Unit of time for the frequency cap.
Example value:"DAY"
Allowed values:"DAY"
,"MONTH"
,"WEEK"
- 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.
Example value:1
Minimum value:1
- max_impressionsinteger [int32]Required
Maximum impressions per user over the frequency period.
Example value:2
Minimum value:1
- 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 value:1000000
- deliverystring
Toggles the delivery of the entity ON or OFF.
Example value:"ON"
Default value:"ON"
Allowed values:"ON"
,"OFF"
- idstring [uuid]
ID of the ad set.
Example value:"ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
Supported content-type(s): - categorystring
Category ID of the ad set.
Example value:"ADV_1_1"
- campaign_idstring [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_modelstring
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_atstring [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_atstring [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_formatstring
Format of the ad set.
Example value:"AUDIO"
Allowed values:"AUDIO"
,"VIDEO"
Users should specify one budget when creating an ad set.
- micro_amountinteger [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
- typestringRequiredExample value:
"DAILY"
Allowed values:"DAILY"
,"LIFETIME"
- currencystringRead onlyExample value:
"USD"
This would be artist promo or podcast promo.
- promotion_goalstringRequired
"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_idstring
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_strategystring
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_reasonstring
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."
- statusstring
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_idsarray of stringsUnique items
ID(s) of artist(s) to target.
Example value:["06HL4z0CvFAxyc27GXpf02"]
Geographical areas to target.
- gendersarray of stringsUnique 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_idsarray of stringsUnique items
ID(s) of the genre(s) to target.
Example value:["rock","blues"]
- interest_idsarray of stringsUnique items
ID(s) of the interest(s) to target.
Example value:["7ebe6459-5fea-4a50-887d-273c06080c78","46b303e4-09a4-4c8e-998b-37186ff8120a"]
- platformsarray of stringsUnique items
ID(s) of the platform(s) to target.
Example value:["IOS"]
Allowed values:"IOS"
,"DESKTOP"
,"ANDROID"
- podcast_episode_topic_idsarray of stringsUnique 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_idsarray of stringsUnique items
Exclude sensitive topics. Allowed values: alcohol, crime-violence, drugs, gambling, hate-speech, pornography, terrorism, tobacco, weapons
Example value:["alcohol","crime-violence"]
- languagestring
ID of the language to target.
Example value:"en"
Length between2
and2
- playlist_idsarray of stringsUnique items
ID(s) of the playlist(s) to target.
Example value:["holidays","cooking"]
- exclude_placementsarray of stringsUnique 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": [] }}