Skip to content
Ads APIReferences / ad-sets / Create ad set

Create ad set

Create a new ad set.

Request

  • ad_account_id
    string [uuid]
    Required

    A unique identifier for an Ad Account.

    Example value: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"

Represents a create request.

  • name
    string
    Required

    Name given to identify the ad set.

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

    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"
  • category
    string
    Required

    Category ID of the ad set.

    Example value: "ADV_1_1"
  • Required

    Users should specify one budget when creating an ad set.

  • Required

    The targets used during the creation of an ad set.

  • bid_strategy
    string
    Required

    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.
    Example value: "MAX_BID"Allowed values: "MAX_BID"
  • This would be artist promo or podcast promo.

  • campaign_id
    string [uuid]
    Required

    ID of the campaign under which the ad set will be created.

    Example value: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"Supported content-type(s):
  • asset_format
    string
    Required

    Format of the ad set.

    Example value: "AUDIO"Allowed values: "AUDIO", "VIDEO"

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