Skip to content
Ads API •References / 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 value: "ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a"
  • limit
    integer

    Limit or page size for a given response.

    Example value: 50Default value: 50Range: 1 - 50
  • offset
    integer

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

    Example value: 0Default value: 0
  • sort_direction
    string

    Field by which to order the results of the query.

    Example value: "ASC"Default value: "DESC"Allowed values: "ASC", "DESC"
  • sort_field
    string

    Field by which to sort list of adsets.

    Example value: "CREATED_AT"Default value: "CREATED_AT"Allowed values: "CREATED_AT", "UPDATED_AT"

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.

      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
    • 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.

    • This would be artist promo or podcast promo.

    • 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.

Response sample

{  "paging": {    "page_size": 50,    "total_results": 116,    "offset": 0  },  "results": [    {      "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",      "bid_optimization_goal": "CLICKS",      "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_exclusion_ids": ["alcohol", "crime-violence"],        "language": "en",        "playlist_ids": ["holidays", "cooking"],        "exclude_placements": []      }    },    {      "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_exclusion_ids": ["alcohol", "crime-violence"],        "language": "en",        "playlist_ids": ["holidays", "cooking"],        "exclude_placements": []      }    }  ]}