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": []      }    }  ]}