openapi: 3.0.3 info: contact: name: Ads API Team url: https://developer.spotify.com/documentation/ads-api email: fossboard@spotify.com description: The Spotify Ads API. title: Ads API version: 3.0.0 servers: - url: https://api-partner.spotify.com/ads/v3 description: Production server. security: - oauth2: [] tags: - name: ab-tests description: Operations to manage AB tests. - name: ad-accounts description: Operations to manage ad accounts. - name: ad-accounts-internal description: Operations to manage ad accounts internally. - name: ad-categories description: Operations to manage ad categories. - name: ads-manager-config description: Operations to manage ads manager configuration. - name: ad-sets description: Operations to manage ad sets. - name: ads description: Operations to manage ads. - name: assets description: Operations to manage assets. - name: audiences description: Operations to manage audiences. - name: audit-logs description: Operations to manage audit logs. - name: billing description: Operations to manage billing. - name: businesses description: Operations to manage businesses. - name: campaigns description: Operations to manage campaigns. - name: client-accounts description: Client Accounts internal endpoints. - name: deals description: Operations to manage deals. - name: drafts description: Operations to manage drafts. - name: estimates description: Operations to manage audience forecasting. - name: experiments description: Operations to manage experiments. - name: mobile-measurement description: Operations to manage mobile measurement. - name: pixel-measurement description: Operations to manage pixel measurement. - name: capi-measurement description: Operations to manage Conversion API measurement. - name: measurement-datasets description: Operations to manage measurement datasets. - name: offers description: Operations to manage offers. - name: partnerships description: Operations to manage partnerships. - name: podcast-shows description: Operations to fetch podcast shows. - name: podcast-episodes description: Operations to fetch podcast episodes. - name: prepay description: Operations to manage prepay transactions - name: pricing description: Operations to manage pricing. - name: reports description: Operations to manage reporting. - name: vat description: Operations to manage vat. - name: promo-codes description: Operations to manage promo codes. - name: reservations description: Operations to manage reservations. - name: salesforce description: Operations to manage Salesforce. - name: targets description: Operations to manage targeting. - name: tests description: Operations to manage test data. - name: users description: Operations to manage users. paths: /ad_accounts/{ad_account_id}: get: description: Returns a single ad account based on query parameters. operationId: getAdAccount parameters: - $ref: '#/components/parameters/ad_account_id' responses: '200': description: An ad account. content: application/json: schema: $ref: '#/components/schemas/AdAccountResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get Ad Account by ID tags: - ad-accounts patch: description: Update an ad account operationId: updateAdAccount parameters: - $ref: '#/components/parameters/ad_account_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateAdAccountRequest' responses: '200': description: Metadata of business' permission to an ad account. content: application/json: schema: $ref: '#/components/schemas/AdAccountResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Update Ad Account tags: - ad-accounts /ad_categories: get: description: | Returns ad category information based on given query parameter. If no query parameter is provided, all categories will be returned. operationId: getAdCategories parameters: - $ref: '#/components/parameters/q' responses: '200': description: A list of ad categories. content: application/json: schema: $ref: '#/components/schemas/AdCategoriesResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get Ad Categories tags: - ad-categories /ad_accounts/{ad_account_id}/ad_sets/{ad_set_id}: get: description: Get an ad set by ID. operationId: getAdSetById parameters: - $ref: '#/components/parameters/ad_account_id' - $ref: '#/components/parameters/ad_set_id' responses: '200': description: Ad set response. content: application/json: schema: $ref: '#/components/schemas/AdSetResponse' example: name: 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' pacing: PACING_EVEN 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 placements: - PODCAST - MUSIC 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_exclusions: topics: - id: tobacco filter_option: RESTRICTED - id: alcohol filter_option: PARTIAL language: en playlist_ids: - cooking - holidays links: GetCampaignForCampaignId: operationId: getCampaign parameters: ad_account_id: $request.path.ad_account_id campaign_id: $response.body#/campaign_id fields: ./campaigns-v3.yaml#/components/parameters/fields description: | Returns list of campaigns linked to an ad account. GetReservationsForAdSet: operationId: getReservations parameters: ad_account_id: $request.path.ad_account_id adset_id: $response.body#/id GetArtistForTargets: operationId: getArtistTargets parameters: ids: $response.body#/targets/artist_ids description: | Returns artist information based on given artist id. GetGenreForTargets: operationId: getGenreTargets parameters: ids: $response.body#/targets/genre_ids GetGeoForTargets: operationId: getGeoTargets parameters: ids: $response.body#/targets/geo_ids GetInterestForTargets: operationId: getInterestTargets parameters: ids: $response.body#/targets/interest_ids description: | Returns interest information based on given interest ids. GetPlaylistForTargets: operationId: getPlaylistTargets parameters: ids: $response.body#/targets/playlist_ids '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get Ad Set by ID tags: - ad-sets patch: description: Partially update an ad set information based on payload. operationId: updateAdSet parameters: - $ref: '#/components/parameters/ad_account_id' - $ref: '#/components/parameters/ad_set_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AdSetPatchRequest' example: name: Test Ad set delivery: 'ON' targets: age_ranges: - min: 23 max: 65 placements: - PODCAST - MUSIC geo_targets: country_code: US city_ids: [] dma_ids: [] postal_code_ids: - US:73170 region_ids: [] genders: - FEMALE genre_ids: - blues interest_ids: - 365a5223-0024-4579-a881-3b08e8720021 sensitive_topic_exclusions: filter_option: RESTRICTED platforms: - IOS playlist_ids: - holidays responses: '200': description: Ad set response with updated fields. content: application/json: schema: $ref: '#/components/schemas/AdSetResponse' example: name: 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 pacing: PACING_EVEN 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 placements: - PODCAST - MUSIC 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_exclusions: filter_option: RESTRICTED language: en playlist_ids: - cooking - holidays '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Update Ad Set tags: - ad-sets /ad_accounts/{ad_account_id}/ad_sets: post: description: Create a new ad set. operationId: createAdSet x-spotify-flow-step: flow: campaign-creation step: 2 previous: createCampaign next: createAd description: Create an ad set under the campaign. Requires campaign_id from step 1. Pass the returned ad set ID to createAd. parameters: - $ref: '#/components/parameters/ad_account_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AdSetCreateRequest' example: name: Test Ad set category: ADV_1_1 campaign_id: 5bbc4fec-c9a5-4fc6-98f4-e950f40b74c7 start_time: '2023-09-23T04:56:07Z' end_time: '2023-09-26T04:56:07Z' pacing: PACING_EVEN frequency_caps: - frequency_unit: DAY frequency_period: 1 max_impressions: 2 budget: micro_amount: 500000000 type: DAILY asset_format: AUDIO targets: age_ranges: - min: 18 max: 65 artist_ids: - 1dfeR4HaWDbWqFHLkxsg1d geo_targets: country_code: US region_ids: - '5101760' dma_ids: - '500' - '503' postal_code_ids: - US:73170 genders: - MALE - FEMALE genre_ids: - alternative - blues interest_ids: - 365a5223-0024-4579-a881-3b08e8720021 - 46b303e4-09a4-4c8e-998b-37186ff8120a placements: - PODCAST - MUSIC platforms: - IOS podcast_episode_topic_ids: - automotive - books-and-literature sensitive_topic_exclusions: topics: - id: tobacco filter_option: RESTRICTED - id: alcohol filter_option: PARTIAL language: en playlist_ids: - holidays - cooking promotion: promotion_goal: ARTIST_PROMO promotion_target_id: 1dfeR4HaWDbWqFHLkxsg1d conversion_events: - tracking_event_type: IMPRESSION window_duration_ms: 86400000 bid_strategy: MAX_BID bid_micro_amount: 10000000 responses: '201': description: Ad set response. content: application/json: schema: $ref: '#/components/schemas/AdSetResponse' example: name: 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 placements: - PODCAST - MUSIC podcast_episode_topic_ids: - books-and-literature - automotive sensitive_topic_exclusions: topics: - id: tobacco filter_option: RESTRICTED - id: alcohol filter_option: PARTIAL language: en playlist_ids: - cooking - holidays links: CreateAdForAdSet: operationId: createAd description: | Create an ad under this ad set. Pass the returned ad set ID as ad_set_id in the ad creation request body. GetCreatedAdSet: operationId: getAdSetById parameters: ad_account_id: $request.path.ad_account_id ad_set_id: $response.body#/id description: Retrieve the newly created ad set. UpdateCreatedAdSet: operationId: updateAdSet parameters: ad_account_id: $request.path.ad_account_id ad_set_id: $response.body#/id description: Update the ad set. '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Create an Ad Set tags: - ad-sets get: description: Get all ad sets for the ad account. operationId: getAdSetsByAdAccountId parameters: - $ref: '#/components/parameters/ad_account_id' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/sort_direction' - $ref: '#/components/parameters/adset_sort_field' - $ref: '#/components/parameters/campaign_ids' - $ref: '#/components/parameters/name' - $ref: '#/components/parameters/statuses' responses: '200': description: Ad set response. content: application/json: schema: $ref: '#/components/schemas/AdSetsResponse' example: paging: page_size: 50 total_results: 116 offset: 0 ad_sets: - name: 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 placements: - PODCAST - MUSIC podcast_episode_topic_ids: - automotive - books-and-literature sensitive_topic_exclusions: topics: - id: tobacco filter_option: RESTRICTED - id: alcohol filter_option: PARTIAL language: en playlist_ids: - holidays - cooking - name: 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 placements: - PODCAST - MUSIC podcast_episode_topic_ids: - automotive - books-and-literature sensitive_topic_exclusions: topics: - id: tobacco filter_option: RESTRICTED - id: alcohol filter_option: PARTIAL language: en playlist_ids: - holidays - cooking links: GetAdsForAdSets: operationId: getAds parameters: ad_account_id: $request.path.ad_account_id ad_set_ids: $response.body#/ad_set.id '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get Ad Sets by Ad Account ID tags: - ad-sets /ad_accounts/{ad_account_id}/ads: post: description: Create a new Ad. operationId: createAd x-spotify-flow-step: flow: campaign-creation step: 3 previous: createAdSet description: Create an ad under the ad set. Requires ad_set_id from step 2. For AUDIO format, also requires asset IDs from prior uploads. parameters: - $ref: '#/components/parameters/ad_account_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAdRequest' responses: '201': description: Ad response. content: application/json: schema: $ref: '#/components/schemas/AdResponse' links: GetCreatedAd: operationId: getAd parameters: ad_account_id: $request.path.ad_account_id ad_id: $response.body#/id description: Retrieve the newly created ad. GetAdSetForAd: $ref: '#/components/links/GetAdSetForAd' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Create an Ad tags: - ads get: description: Returns a list of ads for the given ad account. operationId: getAds parameters: - $ref: '#/components/parameters/ad_account_id' - $ref: '#/components/parameters/ad_fields' - $ref: '#/components/parameters/ad_set_ids' - $ref: '#/components/parameters/asset_ids' - $ref: '#/components/parameters/parameters-name' - $ref: '#/components/parameters/parameters-statuses' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/sort_direction' - $ref: '#/components/parameters/ad_sort_field' responses: '200': description: A list of ads. content: application/json: schema: $ref: '#/components/schemas/AdsListResponse' example: paging: page_size: 50 total_results: 116 offset: 0 ads: - advertiser_name: Heart Dance Recordings assets: asset_id: ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a companion_asset_id: ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a logo_asset_id: ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a call_to_action: text: LEARN_MORE language: ENGLISH clickthrough_url: https://www.spotify.com name: Entity_1 tagline: Good Food for Good Dogs third_party_tracking: - measurement_partner: IAS url: https://www.example.com/your-landing-page/?utm_campaign=test-campaign&utm_source=email ad_account_id: ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a id: ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a created_at: '2026-01-23T04:56:07Z' updated_at: '2026-01-23T04:56:07Z' start_time: '2026-01-24T00:00:00Z' end_time: '2026-02-24T23:59:59Z' delivery: 'ON' ad_set_id: ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a status: PENDING reject_reason: Your ad wasn’t approved. Create a new ad, or contact us at adstudio@spotify.com. ad_preview_url: https://www.adstudio.spotify.com/campaigns/ads/8ae1f562-1b4e-11ee-be56-0242ac120002/preview - advertiser_name: Heart Dance Recordings assets: asset_id: ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a companion_asset_id: ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a logo_asset_id: ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a call_to_action: text: LEARN_MORE language: ENGLISH clickthrough_url: https://www.spotify.com name: Entity_1 tagline: Good Food for Good Dogs third_party_tracking: - measurement_partner: IAS url: https://www.example.com/your-landing-page/?utm_campaign=test-campaign&utm_source=email ad_account_id: ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a id: ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a created_at: '2026-01-23T04:56:07Z' updated_at: '2026-01-23T04:56:07Z' start_time: '2026-01-24T00:00:00Z' end_time: '2026-02-24T23:59:59Z' delivery: 'ON' ad_set_id: ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a status: PENDING reject_reason: Your ad wasn’t approved. Create a new ad, or contact us at adstudio@spotify.com. ad_preview_url: https://www.adstudio.spotify.com/campaigns/ads/8ae1f562-1b4e-11ee-be56-0242ac120002/preview '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get Ads by Ad Account ID tags: - ads /ad_accounts/{ad_account_id}/ads/{ad_id}: get: description: Returns ad for a given ad ID. operationId: getAd parameters: - $ref: '#/components/parameters/ad_account_id' - $ref: '#/components/parameters/ad_id' - $ref: '#/components/parameters/ad_fields' responses: '200': description: Metadata for the given ad. content: application/json: schema: $ref: '#/components/schemas/AdResponse' links: GetAdSetForAd: $ref: '#/components/links/GetAdSetForAd' GetAssetForAssetId: operationId: getAsset parameters: ad_account_id: $parameters.ad_account_id asset_id: $response.body#/assets/asset_id description: | Returns asset metadata for a given asset ID. GetCompanionForAssetId: operationId: getAsset parameters: ad_account_id: $parameters.ad_account_id asset_id: $response.body#/assets/companion_asset_id description: | Returns companion asset metadata for a given asset ID. GetLogoForAssetId: operationId: getAsset parameters: ad_account_id: $parameters.ad_account_id asset_id: $response.body#/assets/logo_asset_id description: | Returns logo asset metadata for a given asset ID. GetCanvasForAssetId: operationId: getAsset parameters: ad_account_id: $parameters.ad_account_id asset_id: $response.body#/assets/canvas_asset_id description: | Returns canvas asset metadata for a given asset ID. '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get Ad by ID tags: - ads patch: description: | Updates the given existing ad. There is no DELETE endpoint for ads. To archive an ad, set status to "ARCHIVED". operationId: updateAd parameters: - $ref: '#/components/parameters/ad_account_id' - $ref: '#/components/parameters/ad_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateAdRequest' responses: '200': description: Metadata for a single ad. content: application/json: schema: $ref: '#/components/schemas/AdResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Update an Ad tags: - ads /ad_accounts/{ad_account_id}/assets: get: description: Returns list of asset metadata in descending order via the creation time within each asset type for a given ad account ID. operationId: getAssetsByAdAccount parameters: - $ref: '#/components/parameters/ad_account_id' - $ref: '#/components/parameters/parameters-asset_ids' - $ref: '#/components/parameters/asset_types' - $ref: '#/components/parameters/asset_subtypes' - $ref: '#/components/parameters/asset_statuses' - $ref: '#/components/parameters/aspect_ratios' - $ref: '#/components/parameters/components-parameters-name' - $ref: '#/components/parameters/parameters-sort_direction' - $ref: '#/components/parameters/sort_field' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/offset' responses: '200': description: List of asset metadata objects. content: application/json: schema: $ref: '#/components/schemas/AssetsResponse' example: paging: page_size: 50 total_results: 116 offset: 0 assets: - id: ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a name: logoImage.png status: READY url: https://i.scdn.co/image/123 created_at: '2026-01-23T04:56:07Z' updated_at: '2026-01-23T04:56:07Z' file_type: JPEG asset_type: IMAGE - id: ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a name: logoImage.png status: READY url: https://i.scdn.co/image/123 created_at: '2026-01-23T04:56:07Z' updated_at: '2026-01-23T04:56:07Z' file_type: JPEG asset_type: IMAGE '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get Assets by Ad Account tags: - assets post: description: Creates an asset belonging to provided ad account and returns asset metadata. Asset type can be either image, audio, or video. operationId: createAsset parameters: - $ref: '#/components/parameters/ad_account_id' requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateAssetRequest' responses: '200': description: The newly created asset metadata content: application/json: schema: $ref: '#/components/schemas/AssetResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Create Asset tags: - assets /ad_accounts/{ad_account_id}/assets/{asset_id}: get: description: Returns asset metadata for a given asset ID. operationId: getAsset parameters: - $ref: '#/components/parameters/ad_account_id' - $ref: '#/components/parameters/asset_id' responses: '200': description: Asset object. content: application/json: schema: $ref: '#/components/schemas/AssetResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get Asset by ID tags: - assets patch: description: Updates the given existing asset. operationId: updateAsset parameters: - $ref: '#/components/parameters/ad_account_id' - $ref: '#/components/parameters/asset_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateAssetRequest' responses: '200': description: The newly updated asset metadata. content: application/json: schema: $ref: '#/components/schemas/AssetResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Update Asset tags: - assets /ad_accounts/{ad_account_id}/assets/{asset_id}/upload: post: description: Uploads an asset to storage and returns asset metadata. Supports uploads of files up to 20MB in size. Asset type can be either image, audio, or video. See [here](https://ads.spotify.com/en-US/ad-experiences/audio-ads-specs/) for detailed list of requirements for audio assets and [here](https://ads.spotify.com/en-US/ad-experiences/video-takeover-ad-specs/) for video assets. operationId: uploadAsset parameters: - $ref: '#/components/parameters/ad_account_id' - $ref: '#/components/parameters/asset_id' requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/UploadAssetRequest' encoding: media: contentType: image/png, image/jpeg, audio/ogg, audio/mp3, audio/wav, audio/mpeg, audio/x-wav, video/mp4, video/quicktime responses: '200': description: The newly created asset metadata content: application/json: schema: $ref: '#/components/schemas/AssetResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Upload Asset tags: - assets /ad_accounts/{ad_account_id}/assets/{asset_id}/chunked_upload/start: post: description: | Start a chunked asset upload process and retrieve upload session id. Asset type can be image, audio, or video. Client is expected to use max_chunk_size_mb in the response to dynamically determine how big each file chunk should be. operationId: startUploadChunkedAsset parameters: - $ref: '#/components/parameters/ad_account_id' - $ref: '#/components/parameters/asset_id' responses: '200': description: Contains a unique upload session ID to be used in subsequent transfer requests. Also, the maximum file chunk size in megabytes. content: application/json: schema: $ref: '#/components/schemas/ChunkedUploadSession' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Start Upload Chunked Asset tags: - assets /ad_accounts/{ad_account_id}/assets/{asset_id}/chunked_upload/transfer: post: description: Continues the upload session of a chunked asset by transferring one section of binary media data. Supports uploads of file chunks up to 20MB in size. Asset type can be either image, audio, or video. operationId: transferChunkedAsset parameters: - $ref: '#/components/parameters/ad_account_id' - $ref: '#/components/parameters/asset_id' requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/TransferChunkedAssetRequest' encoding: media: contentType: image/png, image/jpeg, audio/ogg, audio/mp3, audio/wav, audio/mpeg, audio/x-wav, video/mp4, video/quicktime responses: '200': description: A boolean success indicator. content: application/json: schema: $ref: '#/components/schemas/TransferChunkedAssetResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Transfer Chunked Asset tags: - assets /ad_accounts/{ad_account_id}/assets/{asset_id}/chunked_upload/complete: post: description: Completes the upload session of a chunked asset. Asset type can be either image, audio, or video. operationId: completeUploadChunkedAsset parameters: - $ref: '#/components/parameters/ad_account_id' - $ref: '#/components/parameters/asset_id' requestBody: content: application/json: schema: $ref: '#/components/schemas/ChunkedUploadComplete' responses: '200': description: The newly uploaded asset metadata content: application/json: schema: $ref: '#/components/schemas/AssetResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Complete Upload Chunked Asset tags: - assets /ad_accounts/{ad_account_id}/audiences: post: description: Creates a new audience. operationId: createAudience summary: Create an Audience tags: - audiences parameters: - $ref: '#/components/parameters/ad_account_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAudienceRequest' responses: '201': description: An audience. content: application/json: schema: $ref: '#/components/schemas/AudienceResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' get: description: Returns a list of audiences accessible to the ad account. operationId: batchGetAudiences summary: List Audiences accessible to an Ad Account tags: - audiences parameters: - $ref: '#/components/parameters/ad_account_id' - $ref: '#/components/parameters/audience_ids' - $ref: '#/components/parameters/audience_types' - $ref: '#/components/parameters/q' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/sort_direction' - $ref: '#/components/parameters/audience_sort_field' responses: '200': description: A list of audiences. content: application/json: schema: $ref: '#/components/schemas/AudiencesListResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /ad_accounts/{ad_account_id}/audiences/{audience_id}: delete: description: Deletes an audience. operationId: deleteAudience summary: Delete an Audience tags: - audiences parameters: - $ref: '#/components/parameters/ad_account_id' - $ref: '#/components/parameters/audience_id' responses: '200': description: The audience was deleted successfully. content: application/json: schema: $ref: '#/components/schemas/DeleteAudienceResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' get: description: Returns an audience. operationId: getAudience summary: Get an Audience tags: - audiences parameters: - $ref: '#/components/parameters/audience_id' - $ref: '#/components/parameters/ad_account_id' responses: '200': description: An audience. content: application/json: schema: $ref: '#/components/schemas/AudienceResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' patch: description: Edits an audience. operationId: editAudience summary: Edit an Audience tags: - audiences parameters: - $ref: '#/components/parameters/audience_id' - $ref: '#/components/parameters/ad_account_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EditAudienceRequest' responses: '200': description: An audience. content: application/json: schema: $ref: '#/components/schemas/AudienceResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /ad_accounts/{ad_account_id}/audiences/upload_url: post: description: Get Signed GCS upload URL. operationId: createUploadUrl summary: Get Signed GCS upload URL to upload a user list file tags: - audiences parameters: - $ref: '#/components/parameters/ad_account_id' responses: '200': description: A signed GCS upload URL. content: application/json: schema: $ref: '#/components/schemas/CreateUploadUrlResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /ad_accounts/{ad_account_id}/audiences/upload_url/{audience_id}: post: description: Get Signed GCS upload URL to replace an existing audience operationId: replaceUploadUrl summary: Get Signed GCS upload URL to upload a user list file for an existing audience tags: - audiences parameters: - $ref: '#/components/parameters/ad_account_id' - $ref: '#/components/parameters/audience_id' responses: '200': description: A signed GCS upload URL. content: application/json: schema: $ref: '#/components/schemas/CreateUploadUrlResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /ad_accounts/{ad_account_id}/audiences/datasets: get: description: A list of datasets eligible for creating custom audiences operationId: getAudienceEligibleDatasets summary: List Datasets eligible for creating Custom Audiences tags: - audiences parameters: - $ref: '#/components/parameters/ad_account_id' - $ref: '#/components/parameters/q' - $ref: '#/components/parameters/limit' responses: '200': description: A list of audiences. content: application/json: schema: $ref: '#/components/schemas/GetAudienceEligibleDatasetsResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /businesses: post: description: Creates a new business operationId: createBusiness requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateBusinessRequest' responses: '200': description: A business object. content: application/json: schema: $ref: '#/components/schemas/BusinessResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Create Business tags: - businesses get: description: Gets businesses for logged-in user. operationId: getBusinesses x-enable-public-developer-portal-docs: false responses: '200': description: Array of business objects content: application/json: schema: $ref: '#/components/schemas/GetBusinessesResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get Businesses for Current User tags: - businesses /businesses/{business_id}: get: description: Returns business based on a given business id. operationId: getBusiness parameters: - $ref: '#/components/parameters/business_id' responses: '200': description: A business object. content: application/json: schema: $ref: '#/components/schemas/BusinessResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get Business by ID tags: - businesses patch: description: Update the given existing business. operationId: updateBusiness parameters: - $ref: '#/components/parameters/business_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateBusinessRequest' responses: '200': description: Metadata for a business. content: application/json: schema: $ref: '#/components/schemas/BusinessResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Update Business tags: - businesses /businesses/{business_id}/ad_accounts: post: description: Create Ad Account. operationId: createAdAccountForBusiness parameters: - $ref: '#/components/parameters/business_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAdAccountRequest' responses: '200': description: Metadata of business' permission to an ad account. content: application/json: schema: $ref: '#/components/schemas/AdAccountResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Create Ad Account tags: - ad-accounts get: description: Returns ad account(s) under a given business for the current authenticated user operationId: getAdAccountsInBusiness parameters: - $ref: '#/components/parameters/business_id' responses: '200': description: A list of BusinessPermissionToAdAccount objects content: application/json: schema: $ref: '#/components/schemas/AdAccountsResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get Ad Accounts for Current User by Business ID tags: - ad-accounts /ad_accounts/{ad_account_id}/campaigns: get: description: Returns list of campaigns linked to an ad account. operationId: getCampaigns parameters: - $ref: '#/components/parameters/ad_account_id' - $ref: '#/components/parameters/campaignIds' - $ref: '#/components/parameters/campaigns-v3_components-parameters-name' - $ref: '#/components/parameters/adSetStatuses' - $ref: '#/components/parameters/campaignStatuses' - $ref: '#/components/parameters/fields' - $ref: '#/components/parameters/parameters-sort_field' - $ref: '#/components/parameters/sort_direction' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/offset' responses: '200': description: A list of campaigns. content: application/json: schema: $ref: '#/components/schemas/CampaignsListResponse' links: GetAdSetsForCampaign: operationId: getAdSetsByAdAccountId parameters: ad_account_id: $request.path.ad_account_id campaign_ids: $response.body#/campaign.id GetSalesforceOpportunityForCampaign: operationId: getOpportunitiesByAdAccountId parameters: ad_account_id: $request.path.ad_account_id search_key: $response.body#/campaign.salesforceOpportunity '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get Campaigns by Ad Account ID tags: - campaigns post: description: Creates campaign under a given ad account. operationId: createCampaign x-spotify-flow-step: flow: campaign-creation step: 1 next: createAdSet description: Create a campaign first. Pass the returned campaign ID to createAdSet. parameters: - $ref: '#/components/parameters/ad_account_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCampaignRequest' responses: '200': description: Metadata of created campaign. content: application/json: schema: $ref: '#/components/schemas/CampaignResponse' links: CreateAdSetForCampaign: operationId: createAdSet description: | Create an ad set under this campaign. Pass the returned campaign ID as campaign_id in the ad set creation request body. GetCreatedCampaign: operationId: getCampaign parameters: ad_account_id: $request.path.ad_account_id campaign_id: $response.body#/id description: Retrieve the newly created campaign. UpdateCreatedCampaign: operationId: updateCampaign parameters: ad_account_id: $request.path.ad_account_id campaign_id: $response.body#/id description: Update the campaign (e.g. change status to PAUSED or ARCHIVED). '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Create a Campaign tags: - campaigns /ad_accounts/{ad_account_id}/campaigns/{campaign_id}: get: description: Returns campaign based on a given campaign ID. operationId: getCampaign parameters: - $ref: '#/components/parameters/ad_account_id' - $ref: '#/components/parameters/campaign_id' - $ref: '#/components/parameters/fields' responses: '200': description: Metadata for a single campaign. content: application/json: schema: $ref: '#/components/schemas/CampaignResponse' links: GetAdSetsForCampaign: operationId: getAdSetsByAdAccountId parameters: ad_account_id: $request.path.ad_account_id campaign_ids: $response.body#/campaigns.id GetSalesforceOpportunityForCampaign: operationId: getOpportunitiesByAdAccountId parameters: ad_account_id: $request.path.ad_account_id search_key: $response.body#/campaigns.salesforceOpportunity '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get Campaign by ID tags: - campaigns patch: description: | Updates the given existing campaign. There is no DELETE endpoint for campaigns. To archive a campaign, set status to "ARCHIVED". To pause, set status to "PAUSED". operationId: updateCampaign parameters: - $ref: '#/components/parameters/ad_account_id' - $ref: '#/components/parameters/campaign_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateCampaignRequest' responses: '200': description: Metadata for a single campaign. content: application/json: schema: $ref: '#/components/schemas/CampaignResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Update a Campaign tags: - campaigns /estimates/audience: post: description: Returns audience estimates based on specific ad set parameters. operationId: estimateAudience requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AudienceEstimateRequest' responses: '200': description: Audience estimates response content: application/json: schema: $ref: '#/components/schemas/AudienceEstimateResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/AudienceEstimateErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Estimate audience tags: - estimates /estimates/bid: post: description: Returns a bid estimate (recommended bid range) based on specific ad set parameters. operationId: estimateBid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BidEstimateRequest' responses: '200': description: Bid estimate response content: application/json: schema: $ref: '#/components/schemas/BidEstimateResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Estimate bid tags: - estimates /ad_accounts/{ad_account_id}/experiments/{experiment_id}/questions/{survey_question_id}: patch: description: Update a survey question operationId: updateSurveyQuestion parameters: - $ref: '#/components/parameters/ad_account_id' - $ref: '#/components/parameters/experiment_id' - $ref: '#/components/parameters/survey_question_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateSurveyQuestionRequest' responses: '204': description: Successfully updated the survey question. '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Update survey question. tags: - experiments /businesses/{business_id}/mobile_apps: get: description: Get all mobile apps for the business. operationId: getMobileAppsByBusinessId parameters: - $ref: '#/components/parameters/business_id' responses: '200': description: A list of mobile apps. content: application/json: schema: $ref: '#/components/schemas/MobileAppsResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get all mobile apps for a business tags: - mobile-measurement post: description: Create a mobile app. operationId: createMobileAppInBusiness parameters: - $ref: '#/components/parameters/business_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateMobileAppRequest' responses: '201': description: Mobile app created. content: application/json: schema: $ref: '#/components/schemas/MobileApp' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Create mobile app tags: - mobile-measurement /businesses/{business_id}/mobile_apps/{mobile_app_id}: get: description: Get the mobile app by its id. operationId: getMobileAppByBusinessAndId parameters: - $ref: '#/components/parameters/business_id' - $ref: '#/components/parameters/mobile_app_id' responses: '200': description: Mobile app response. content: application/json: schema: $ref: '#/components/schemas/MobileApp' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get the mobile app by its id. tags: - mobile-measurement patch: description: Update the specified mobile app. operationId: updateMobileAppByBusinessAndId parameters: - $ref: '#/components/parameters/business_id' - $ref: '#/components/parameters/mobile_app_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MobileApp' responses: '200': description: Mobile app response with updated values. content: application/json: schema: $ref: '#/components/schemas/MobileApp' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Update the specified mobile app. tags: - mobile-measurement /businesses/{business_id}/ad_accounts/{ad_account_id}/mobile_apps: get: description: Get all mobile apps for the ad account. operationId: getMobileAppsByBusinessIdAndAdAccountId parameters: - $ref: '#/components/parameters/business_id' - $ref: '#/components/parameters/ad_account_id' responses: '200': description: A list of mobile apps. content: application/json: schema: $ref: '#/components/schemas/MobileAppsResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get all mobile apps for an ad account tags: - mobile-measurement /businesses/{business_id}/mobile_apps/{mobile_app_id}/ad_accounts/{ad_account_id}: post: description: Share a mobile app with an ad account within a business. operationId: shareBusinessMobileAppWithAdAccount parameters: - $ref: '#/components/parameters/business_id' - $ref: '#/components/parameters/ad_account_id' - $ref: '#/components/parameters/mobile_app_id' responses: '204': description: No content. The mobile app was shared successfully. '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Share A Mobile App With An Ad Account tags: - mobile-measurement delete: description: Unshare a mobile app with an ad account within a business. operationId: unshareBusinessMobileAppWithAdAccount parameters: - $ref: '#/components/parameters/business_id' - $ref: '#/components/parameters/ad_account_id' - $ref: '#/components/parameters/mobile_app_id' responses: '204': description: No content. The mobile app was unshared successfully. '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Unshare A Mobile App With An Ad Account tags: - mobile-measurement /businesses/{business_id}/pixels: get: description: Get all pixels for the business account. operationId: getPixelsByBusinessId parameters: - $ref: '#/components/parameters/business_id' - $ref: '#/components/parameters/include_events' - $ref: '#/components/parameters/include_historical_events' - $ref: '#/components/parameters/historical_events_start_date' - $ref: '#/components/parameters/historical_events_end_date' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/offset' responses: '200': description: Pixels response. content: application/json: schema: $ref: '#/components/schemas/PixelsResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get all pixels for a business account tags: - pixel-measurement post: description: | Create a new pixel. operationId: createPixelInBusiness parameters: - $ref: '#/components/parameters/business_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePixelRequest' responses: '201': description: The pixel was created successfully. content: application/json: schema: $ref: '#/components/schemas/Pixel' '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Create pixel tags: - pixel-measurement /businesses/{business_id}/pixels/{pixel_id}: get: description: Get pixel by id for a given business. operationId: getPixelById parameters: - $ref: '#/components/parameters/business_id' - $ref: '#/components/parameters/pixel_id_path_param' responses: '200': description: Pixel content: application/json: schema: $ref: '#/components/schemas/Pixel' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get pixel by id for a given business. tags: - pixel-measurement patch: description: | Update an existing pixel. operationId: updatePixelById parameters: - $ref: '#/components/parameters/business_id' - $ref: '#/components/parameters/pixel_id_path_param' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdatePixelRequest' responses: '200': description: The pixel was updated successfully. content: application/json: schema: $ref: '#/components/schemas/UpdatePixelResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Update pixel tags: - pixel-measurement /businesses/{business_id}/capi: post: summary: Create CAPI Integration description: Create a CAPI integration in a business operationId: createCapiIntegration tags: - capi-measurement parameters: - $ref: '#/components/parameters/business_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCapiIntegrationRequest' responses: '201': description: The created CAPI integration. content: application/json: schema: $ref: '#/components/schemas/CapiIntegration' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /businesses/{business_id}/capi/{capi_connection_id}: get: summary: Get CAPI Integration description: Get a CAPI Integration by ID operationId: getCapiIntegrationById tags: - capi-measurement parameters: - $ref: '#/components/parameters/business_id' - $ref: '#/components/parameters/capi_connection_id' responses: '200': description: The requested CAPI integration. content: application/json: schema: $ref: '#/components/schemas/CapiIntegration' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' patch: summary: Update CAPI Integration description: Update CAPI Integration operationId: updateCapiIntegrationById tags: - capi-measurement parameters: - $ref: '#/components/parameters/business_id' - $ref: '#/components/parameters/capi_connection_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateCapiIntegrationRequest' responses: '200': description: The updated CAPI integration. content: application/json: schema: $ref: '#/components/schemas/CapiIntegration' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /businesses/{business_id}/capi/{capi_connection_id}/tokens: post: summary: Create CAPI Auth Token description: Create a new long-lived JSON Web Token to authenticate CAPI requests operationId: createCapiAuthToken tags: - capi-measurement parameters: - $ref: '#/components/parameters/business_id' - $ref: '#/components/parameters/capi_connection_id' responses: '201': description: A new JWT token for Authentication. content: application/json: schema: $ref: '#/components/schemas/CapiCreateAuthTokenResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' get: summary: Get CAPI Auth Token(s) description: Gets all active authentication token(s) operationId: getCapiAuthTokens tags: - capi-measurement parameters: - $ref: '#/components/parameters/business_id' - $ref: '#/components/parameters/capi_connection_id' responses: '200': description: List of active CAPI auth tokens. content: application/json: schema: $ref: '#/components/schemas/CapiGetAuthTokenResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /businesses/{business_id}/capi/{capi_connection_id}/tokens/{capi_auth_token_id}: delete: summary: Delete CAPI Auth Token description: Soft delete the authentication token operationId: deleteCapiAuthToken tags: - capi-measurement parameters: - $ref: '#/components/parameters/business_id' - $ref: '#/components/parameters/capi_connection_id' - $ref: '#/components/parameters/capi_auth_token_id' responses: '204': description: The token has been deleted. '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /businesses/{business_id}/datasets: get: summary: Get Datasets for Business description: Get all Datasets for a business operationId: getDatasetsByBusinessId tags: - measurement-datasets parameters: - $ref: '#/components/parameters/business_id' responses: '200': description: Datasets response. content: application/json: schema: $ref: '#/components/schemas/DatasetsResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' post: summary: Create Dataset description: Create a Dataset in a business account operationId: createDataset tags: - measurement-datasets parameters: - $ref: '#/components/parameters/business_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateDatasetRequest' responses: '201': description: The created Dataset. content: application/json: schema: $ref: '#/components/schemas/Dataset' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /businesses/{business_id}/datasets/{dataset_id}: get: summary: Get Dataset description: Get Dataset by ID operationId: getDatasetById tags: - measurement-datasets parameters: - $ref: '#/components/parameters/business_id' - $ref: '#/components/parameters/dataset_id' responses: '200': description: The requested Dataset. content: application/json: schema: $ref: '#/components/schemas/Dataset' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' patch: summary: Update Dataset description: Update Dataset operationId: updateDatasetById tags: - measurement-datasets parameters: - $ref: '#/components/parameters/business_id' - $ref: '#/components/parameters/dataset_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateDatasetRequest' responses: '200': description: The updated Dataset. content: application/json: schema: $ref: '#/components/schemas/Dataset' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /businesses/{business_id}/datasets/{dataset_id}/integrations/{integration_id}: delete: summary: Remove Integration From Dataset description: Remove integration from dataset - moves integration to its own new dataset. operationId: removeIntegrationFromDataset tags: - measurement-datasets parameters: - $ref: '#/components/parameters/business_id' - $ref: '#/components/parameters/dataset_id' - $ref: '#/components/parameters/integration_id' responses: '200': description: The new dataset the removed integration now belongs to. content: application/json: schema: $ref: '#/components/schemas/Dataset' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /businesses/{business_id}/ad_accounts/{ad_account_id}/datasets: get: summary: Get Datasets for Ad Account description: Get all Datasets delegated to an Ad Account operationId: getDatasetsByAdAccountId tags: - measurement-datasets parameters: - $ref: '#/components/parameters/business_id' - $ref: '#/components/parameters/ad_account_id' responses: '200': description: Datasets response. content: application/json: schema: $ref: '#/components/schemas/DatasetsResponse' '400': description: Bad request.` content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /businesses/{business_id}/datasets/{dataset_id}/diagnostics: get: summary: Get diagnostics for a dataset. description: Get diagnostics for a dataset. operationId: getDiagnosticsByDatasetId tags: - measurement-datasets parameters: - $ref: '#/components/parameters/business_id' - $ref: '#/components/parameters/dataset_id' - $ref: '#/components/parameters/granularities' - $ref: '#/components/parameters/datasource_ids' responses: '200': description: Diagnostics response. content: application/json: schema: $ref: '#/components/schemas/DiagnosticsResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /businesses/{business_id}/datasets/{dataset_id}/ad_accounts/{ad_account_id}: post: description: Share a dataset with an ad account within a business. operationId: shareBusinessDatasetWithAdAccount summary: Share A Dataset With An Ad Account tags: - measurement-datasets parameters: - $ref: '#/components/parameters/business_id' - $ref: '#/components/parameters/ad_account_id' - $ref: '#/components/parameters/dataset_id' responses: '204': description: No content. The dataset was shared successfully. '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' delete: description: Unshare a dataset with an ad account within a business. operationId: unshareBusinessDatasetWithAdAccount summary: Unshare A Dataset With An Ad Account tags: - measurement-datasets parameters: - $ref: '#/components/parameters/business_id' - $ref: '#/components/parameters/ad_account_id' - $ref: '#/components/parameters/dataset_id' responses: '204': description: No content. The dataset was unshared successfully. '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /podcast_shows: get: description: Returns podcast information based on given query parameter. operationId: getPodcastShows parameters: - $ref: '#/components/parameters/show_ids' - $ref: '#/components/parameters/q' - $ref: '#/components/parameters/market' responses: '200': description: A list of podcasts. content: application/json: schema: $ref: '#/components/schemas/PodcastShowsResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get Podcast Shows tags: - podcast-shows /ad_accounts/{ad_account_id}/aggregate_reports: get: description: Returns aggregated ad campaign metrics based on requested fields and dimensions. operationId: getAggregateReport parameters: - $ref: '#/components/parameters/ad_account_id' - $ref: '#/components/parameters/entity_type' - $ref: '#/components/parameters/report_fields' - $ref: '#/components/parameters/report_start' - $ref: '#/components/parameters/report_end' - $ref: '#/components/parameters/granularity' - $ref: '#/components/parameters/include_parent_entity' - $ref: '#/components/parameters/entity_ids' - $ref: '#/components/parameters/entity_ids_type' - $ref: '#/components/parameters/entity_status_type' - $ref: '#/components/parameters/entity_statuses' - $ref: '#/components/parameters/continuation_token' - $ref: '#/components/parameters/limit' responses: '200': description: | An aggregated ad campaign report broken down by requested entity dimension. content: application/json: schema: $ref: '#/components/schemas/AggregateReportResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get Aggregate Report by Ad Account ID tags: - reports /ad_accounts/{ad_account_id}/insight_reports: get: description: | Returns ad campaign metrics broken out by audience (i.e., targeting) insights based on requested fields and dimensions. operationId: getAudienceInsightReport parameters: - $ref: '#/components/parameters/ad_account_id' - $ref: '#/components/parameters/insight_dimension' - $ref: '#/components/parameters/report_fields' - $ref: '#/components/parameters/entity_ids' - $ref: '#/components/parameters/entity_ids_type' - $ref: '#/components/parameters/entity_status_type' - $ref: '#/components/parameters/entity_statuses' responses: '200': description: An ad campaign report broken down by requested dimensions. content: application/json: schema: $ref: '#/components/schemas/AudienceInsightResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get Insight Report by Ad Account ID tags: - reports /ad_accounts/{ad_account_id}/async_reports: post: description: | Create a CSV report asynchronously. The status of the CSV generation and the CSV itself (once available) can be found either in the 'Reports' section of Spotify Ads Manager or from the Get Async Report endpoint. operationId: createAsyncReport parameters: - $ref: '#/components/parameters/ad_account_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAsyncReportRequest' example: name: My daily campaign report granularity: DAY dimensions: - CAMPAIGN_NAME - CAMPAIGN_OBJECTIVE campaign_ids: - 7f4c1cc9-9a1d-4b65-b05c-46e5e33b6705 statuses: - ACTIVE - COMPLETED metrics: - CLICKS - STREAMS report_start: '2024-01-23T00:00:00Z' report_end: '2024-01-26T00:00:00Z' responses: '201': description: Response containing the CSV report ID. content: application/json: schema: $ref: '#/components/schemas/CreateAsyncReportResponse' example: id: ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Create a CSV Report Asynchronously tags: - reports /ad_accounts/{ad_account_id}/async_reports/{report_id}: get: description: | Returns the status of a CSV report and its download URL (once available). The `report_id` can be found in the response from calling the Create Async Report endpoint. operationId: getAsyncReport parameters: - $ref: '#/components/parameters/ad_account_id' - $ref: '#/components/parameters/report_id' responses: '200': description: | The status of a CSV report and its download URL (once available). content: application/json: schema: $ref: '#/components/schemas/AsyncReportResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Report not found. '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get CSV Report Status by ID tags: - reports /targets/artists: get: description: Returns artist information based on given query parameter. operationId: getArtistTargets parameters: - $ref: '#/components/parameters/artist_ids' - $ref: '#/components/parameters/q' responses: '200': description: A list of artists. content: application/json: schema: $ref: '#/components/schemas/ArtistTargetsResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get Artist Targets tags: - targets /targets/genres: get: description: Returns genre information. If no query parameter is provided, all genres will be returned. operationId: getGenreTargets parameters: - $ref: '#/components/parameters/genre_ids' - $ref: '#/components/parameters/q' responses: '200': description: A list of genres. content: application/json: schema: $ref: '#/components/schemas/GenreTargetsResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get Genre Targets tags: - targets /targets/geos: get: description: Returns geo information filterable by query parameters. At least one query parameter must be provided. operationId: getGeoTargets parameters: - $ref: '#/components/parameters/country_code' - $ref: '#/components/parameters/geo_ids' - $ref: '#/components/parameters/types' - $ref: '#/components/parameters/q' - $ref: '#/components/parameters/geo_limit' - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/language' responses: '200': description: A list of geos. content: application/json: schema: $ref: '#/components/schemas/GeoTargetsResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get Geo Targets tags: - targets /targets/interests: get: description: Returns interest targets information. If no query parameter is provided, all interest targets will be returned. operationId: getInterestTargets parameters: - $ref: '#/components/parameters/interest_ids' - $ref: '#/components/parameters/q' responses: '200': description: A list of interest targets. content: application/json: schema: $ref: '#/components/schemas/InterestTargetsResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get Interest Targets tags: - targets /targets/languages: get: description: Returns language targets information. If no query parameter is provided, all language targets will be returned. operationId: getLanguageTargets parameters: - $ref: '#/components/parameters/language_ids' - $ref: '#/components/parameters/q' - $ref: '#/components/parameters/ad_account_id_query' responses: '200': description: A list of language targets. content: application/json: schema: $ref: '#/components/schemas/LanguageTargetsResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get Language Targets tags: - targets /targets/playlists: get: description: Returns playlist information. If no query parameter is provided, all playlists will be returned. operationId: getPlaylistTargets parameters: - $ref: '#/components/parameters/playlist_ids' - $ref: '#/components/parameters/q' responses: '200': description: A list of playlists. content: application/json: schema: $ref: '#/components/schemas/PlaylistTargetsResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get Playlist Targets tags: - targets /targets/episode_topics: get: description: Returns Podcast episode topic information. If no query parameter is provided, all episode topics will be returned. operationId: getEpisodeTopicTargets parameters: - $ref: '#/components/parameters/episode_topic_ids' - $ref: '#/components/parameters/q' responses: '200': description: A list of podcast episode topics. content: application/json: schema: $ref: '#/components/schemas/EpisodeTopicTargetsResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get Podcast Episode Topic Targets tags: - targets /targets/sensitive_topics: get: description: Returns sensitive topics information. If no query parameter is provided, all sensitive topics will be returned. operationId: getSensitiveTopicTargets parameters: - $ref: '#/components/parameters/sensitive_topic_ids' - $ref: '#/components/parameters/q' responses: '200': description: A list of sensitive topics. content: application/json: schema: $ref: '#/components/schemas/SensitiveTopicTargetsResponse' '400': description: Bad request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get Sensitive Topic Targets tags: - targets components: securitySchemes: bearerAuth: type: http scheme: bearer oauth2: type: oauth2 flows: authorizationCode: authorizationUrl: https://accounts.spotify.com/authorize/ tokenUrl: https://accounts.spotify.com/api/token scopes: {} schemas: Uuid: type: string format: uuid description: A unique identifier for the entity. example: ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a CreatedAt: type: string format: date-time description: | Date the entity was created. Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ example: '2026-01-23T04:56:07Z' UpdatedAt: type: string format: date-time description: | Date the entity was updated. Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ example: '2026-01-23T04:56:07Z' AdAccountBaseResponse: type: object properties: id: $ref: '#/components/schemas/Uuid' business_id: $ref: '#/components/schemas/Uuid' created_at: $ref: '#/components/schemas/CreatedAt' updated_at: $ref: '#/components/schemas/UpdatedAt' AdAccountCountryCode: type: string description: The country or region of the geo in ISO alpha-2 country code format. example: US AdAccountIndustry: type: string description: The Ad Account's listed industry. example: Media & Entertainment AdAccountWebsite: type: string description: The website associated with the ad account. example: https://www.spotify.com AddressName: type: string minLength: 1 maxLength: 120 pattern: ^\S(.*\S)?$ description: Billing name for the account that will appear on bills and invoices. example: Entity_1 AddressStreet: type: string description: Street number and address of ad account. example: 123 Spotify Avenue AddressCity: type: string description: city of ad account example: Los Angeles AddressRegion: type: string description: Region where city is located. example: California AddressPostalCode: type: string description: Postal code for address. example: '90210' BillingAddress: type: object properties: name: $ref: '#/components/schemas/AddressName' street: $ref: '#/components/schemas/AddressStreet' city: $ref: '#/components/schemas/AddressCity' region: $ref: '#/components/schemas/AddressRegion' postal_code: $ref: '#/components/schemas/AddressPostalCode' tax_region: type: string description: Geo in ISO alpha-2 country code format for taxable country. example: ES LegalEntityName: type: string description: The legal name of the entity funding ads for the ad account. example: Spotify AB AdAccountStatus: type: string enum: - ACTIVE - INACTIVE - GREY_LISTED - SUSPEND_LISTED - BLACKLISTED description: The status of the ad account. AdAccountRole: type: string enum: - AD_ACCOUNT_ADMIN - AD_ACCOUNT_CONTRIBUTOR - AD_ACCOUNT_VIEWER description: The role of a user in an ad account. AdAccountTaxId: type: string description: The tax ID on record for the ad account. example: ATU82660371 AdAccountCurrency: type: string description: The billing currency for the account example: USD maxLength: 3 AdAccountResponse: allOf: - $ref: '#/components/schemas/AdAccountBaseResponse' - type: object properties: country_code: $ref: '#/components/schemas/AdAccountCountryCode' industry: $ref: '#/components/schemas/AdAccountIndustry' website: $ref: '#/components/schemas/AdAccountWebsite' billing_address: $ref: '#/components/schemas/BillingAddress' legal_entity_name: allOf: - $ref: '#/components/schemas/LegalEntityName' status: $ref: '#/components/schemas/AdAccountStatus' status_reason: type: string description: The reason for the status of the ad account. name: type: string pattern: ^\S.*\S$ example: Nike SB description: Name given to identify your account. ad_account_role: $ref: '#/components/schemas/AdAccountRole' tax_id: $ref: '#/components/schemas/AdAccountTaxId' currency_code: $ref: '#/components/schemas/AdAccountCurrency' ErrorCode: type: object properties: code: description: Identifier for specific error. type: string definition: description: Description of the error code and suggested remediation steps. type: string ErrorResponse: type: object properties: sp_trace_id: type: string format: uuid messages: type: array description: Error messages related to the request. items: type: string error_codes: type: array description: Error identifier and suggested remediation steps. items: $ref: '#/components/schemas/ErrorCode' example: sp_trace_id: 800c5a14-b8fd-4dc0-a4fa-38184111f67a messages: - Custom Error Message Name: type: string minLength: 1 maxLength: 120 pattern: ^(?!\s).+(? CapiAuthTokenResponse: type: object properties: capi_auth_token_id: $ref: '#/components/schemas/CapiAuthTokenId' capi_auth_token: $ref: '#/components/schemas/CapiAuthToken' created_at: $ref: '#/components/schemas/CreatedAt' CapiGetAuthTokenResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/CapiAuthTokenResponse' CapiCreateAuthTokenResponse: type: object properties: data: $ref: '#/components/schemas/CapiAuthTokenResponse' DatasetName: type: string description: The name of the dataset. example: US Advertising IsDatasetArchived: type: boolean description: Whether the dataset has been archived. default: false IsDatasetReceivingEvents: type: boolean description: Whether any integrations in the dataset are currently sending events. default: false schemas-SharedAdAccount: type: object description: An ad account a dataset has been shared to. properties: id: $ref: '#/components/schemas/AdAccountId' name: $ref: '#/components/schemas/AdAccountName' IsDatasetReceivingLeadEvents: type: boolean description: Whether any integrations in the dataset are currently sending lead events. default: false Dataset: type: object properties: id: readOnly: true allOf: - $ref: '#/components/schemas/DatasetId' name: $ref: '#/components/schemas/DatasetName' pixel: $ref: '#/components/schemas/Pixel' capi_integration: $ref: '#/components/schemas/CapiIntegration' ad_set_count: $ref: '#/components/schemas/AdSetCount' is_archived: $ref: '#/components/schemas/IsDatasetArchived' is_receiving_events: $ref: '#/components/schemas/IsDatasetReceivingEvents' shared_ad_accounts: type: array items: $ref: '#/components/schemas/schemas-SharedAdAccount' is_receiving_lead_events: $ref: '#/components/schemas/IsDatasetReceivingLeadEvents' DatasetsResponse: type: object properties: paging: $ref: '#/components/schemas/Paging' datasets: type: array items: $ref: '#/components/schemas/Dataset' CreateDatasetRequest: type: object required: - name - integration_ids properties: name: $ref: '#/components/schemas/DatasetName' integration_ids: type: array items: $ref: '#/components/schemas/IntegrationId' UpdateDatasetRequest: type: object properties: name: $ref: '#/components/schemas/DatasetName' Granularity: type: string description: What granularity of diagnostic data is present. enum: - DAILY - HOURLY DatasourceId: type: string description: A unique identifier for a datasource example: ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a DatasourceType: type: string description: Type of datasource that diagnostic data is using. enum: - PIXEL - CAPI DiagnosticEvent: type: object description: An diagnostic event received from a datasource. properties: name: type: string description: Type of event in datasource. event_count: type: number description: Amount of events of this type fired during timeframe. last_activity_ms: type: number description: Timestamp of most recent event. DiagnosticEvents: type: object description: A list of diagnostic events by timestamp. properties: total: type: number description: Total count of events during timestamp period. timestamp: type: number description: Events that happened during a granularity period (Daily or Hourly). event_counts: type: array items: $ref: '#/components/schemas/DiagnosticEvent' DiagnosticDatasource: type: object properties: datasource_type: $ref: '#/components/schemas/DatasourceType' datasource_id: $ref: '#/components/schemas/DatasourceId' granularity: $ref: '#/components/schemas/Granularity' timeseries: type: array items: $ref: '#/components/schemas/DiagnosticEvents' DiagnosticsResponse: type: object properties: dataset_id: $ref: '#/components/schemas/DatasetId' datasources: type: array items: $ref: '#/components/schemas/DiagnosticDatasource' SearchedParams: type: array default: [] items: type: string TargetBase: type: object properties: id: type: string name: type: string example: id: target-id name: target-name ContentPromotionBase: allOf: - $ref: '#/components/schemas/TargetBase' - type: object properties: images: type: array items: type: object properties: width: type: integer url: type: string height: type: integer example: name: anything goes with emma chamberlain id: 4CfjBMktmGyX0AZYv3O10M images: - width: 6 url: https://i.scdn.co/image/ab6765630000ba8a2e0748b75ab4b3bb0638dd74 height: 2 PodcastShowsResponse: type: object properties: shows: type: array items: $ref: '#/components/schemas/ContentPromotionBase' EntityDimensionType: type: string enum: - AD - AD_SET - CAMPAIGN - AD_ACCOUNT description: | EntityDimensionType describes the top-level entity in the ad hierarchy that a particular report will be based off of. Both Aggregate and Insight Reports require an EntityDimensionType. example: AD_SET ReportFieldType: type: string x-deprecated-enums: type: array items: - E_CPM - E_CPC - INTENT_RATE - PAID_LISTENS - PAID_LISTENS_FREQUENCY - PAID_LISTENS_REACH - SKIPS enum: - CLICKS - COMPLETES - COMPLETION_RATE - CONVERSION_RATE - CTR - E_CPCL - FIRST_QUARTILES - FREQUENCY - IMPRESSIONS - INTENT_RATE - LISTENERS - MIDPOINTS - NEW_LISTENERS - NEW_LISTENER_CONVERSION_RATE - NEW_LISTENER_STREAMS - OFF_SPOTIFY_IMPRESSIONS - PAID_LISTENS - PAID_LISTENS_FREQUENCY - PAID_LISTENS_REACH - REACH - SKIPS - SPEND - STARTS - STREAMS - STREAMS_PER_NEW_LISTENER - STREAMS_PER_USER - THIRD_QUARTILES - VIDEO_VIEWS - VIDEO_EXPANDS - VIDEO_EXPAND_RATE - UNMUTES - PAGE_VIEWS - LEADS - ADD_TO_CART - PURCHASES - REVENUE - AVERAGE_ORDER_VALUE - RETURN_ON_AD_SPEND - CUSTOMER_ACQUISITION_COST - COST_PER_LEAD - START_CHECKOUT - PRODUCTS - SIGN_UPS - CUSTOM_EVENT_1 - CUSTOM_EVENT_2 - CUSTOM_EVENT_3 - CUSTOM_EVENT_4 - CUSTOM_EVENT_5 - STREAMED_IMPRESSIONS description: | Users can define a set of fields that they would like populated in the report. This enum defines the global list of available fields. However, not all fields are applicable to both report types. This is validated at request time. The following fields are not allowed for insight reports: - E_CPCL - FREQUENCY - OFF_SPOTIFY_IMPRESSIONS - PAID_LISTENS_FREQUENCY - SKIPS - SPEND - STARTS - UNMUTES TimeDimensionType: type: string enum: - DAY - HOUR - LIFETIME description: | TimeDimensionType describes the granularity of the data reported. For example, if DAY is selected, a report will be generated that contains daily aggregated metrics between report_start and report_end dates that are provided in the request. Please note that report_start and report_end dates are not permitted when requesting LIFETIME granularity. default: LIFETIME example: LIFETIME AdAccountSourceType: type: string enum: - AD_STUDIO - S4A - STRATEGIC_PROMOTION - MEGAPHONE_CMS - MEGAPHONE_MAPPER - SALESFORCE x-enum-varnames: - AD_STUDIO - S4A - STRATEGIC_PROMOTION - MEGAPHONE_CMS - MEGAPHONE_MAPPER - SALESFORCE description: The internal service that created the ad account. AdAccountSourceId: type: string description: The identifier for the internal service that created the ad account. ReportEntityStatus: description: | Ad, Ad Set, and Campaign statuses that are used in report requests as well as responses. Not every status is valid for each entity type. The valid statuses for each entity are the following: Ad: APPROVED, ARCHIVED, PENDING, PENDING_APPROVAL, PENDING_ADVERTISER_APPROVAL, REJECTED Ad Set: ACTIVE, APPROVED, ARCHIVED, COMPLETED, PENDING_APPROVAL, PENDING_ADVERTISER_APPROVAL, READY, REJECTED Campaign: ACTIVE, ARCHIVED, PAUSED Note: The PENDING_ADVERTISER_APPROVAL status is only available for managed service campaigns. type: string enum: - ACTIVE - APPROVED - ARCHIVED - PENDING_APPROVAL - REJECTED - PENDING_ADVERTISER_APPROVAL - PAUSED - COMPLETED - READY - PENDING ParentEntity: type: object description: Information about the parent entity in the ad hierarchy. properties: id: allOf: - $ref: '#/components/schemas/Uuid' description: ID of the parent entity. example: ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a name: type: string description: Name of the parent entity. example: Parent Entity Name status: allOf: - $ref: '#/components/schemas/ReportEntityStatus' type: string description: Status of the parent entity. example: ACTIVE ReportField: type: object description: A report field type and its value. properties: field_type: description: Type of the field that is being requested, i.e., CLICKS, CTR, IMPRESSIONS, etc. allOf: - $ref: '#/components/schemas/ReportFieldType' example: CLICKS field_value: type: number description: | The value for the specified field. This value can be an integer (CLICKS) or float (CTR). To protect user privacy, we present conversion counts as -5 whenever the actual number of conversions is less than 5 and greater than 0. example: 500 AggregateReportRow: type: object description: | An item that contains the entity information as well as the aggregated time series information for that entity. properties: entity_type: allOf: - $ref: '#/components/schemas/EntityDimensionType' description: Type of the entity requested. This can be CAMPAIGN, AD_SET, or AD. example: AD_SET entity_id: allOf: - $ref: '#/components/schemas/Uuid' example: 7f4c1cc9-9a1d-4b65-b05c-46e5e33b6705 description: ID of the entity. entity_name: type: string example: My Ad Campaign description: Name of the entity. entity_status: allOf: - $ref: '#/components/schemas/ReportEntityStatus' type: string description: Status of the entity. example: ACTIVE parent_entity: $ref: '#/components/schemas/ParentEntity' start_time: type: string format: date-time description: | Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ. example: '2021-01-23T04:56:07Z' end_time: type: string format: date-time description: | Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ. example: '2021-01-26T04:56:07Z' stats: type: array description: | Array of field names and their values that were requested as a part of the report. items: $ref: '#/components/schemas/ReportField' example: - field_type: CLICKS field_value: 100 - field_type: CTR field_value: 0.56 example: entity_type: AD_SET entity_id: 7f4c1cc9-9a1d-4b65-b05c-46e5e33b6705 entity_name: My Ad Set entity_status: ACTIVE parent_entity: id: ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a name: Parent Campaign status: ACTIVE start_time: '2021-01-23T04:56:07Z' end_time: '2021-01-26T04:56:07Z' stats: - field_type: CLICKS field_value: 100 - field_type: CTR field_value: 0.56 AggregateReportResponse: type: object description: | A list of rows of reporting data. If more items exist than are returned, the continuation_token can be used to request the next page. If no more items exist, the continuation_token will be empty. properties: continuation_token: nullable: false type: string example: AMC-fuxpGRIqFcOUEzDEdWQsM5Iy7mkRThKFo94mEys6RF1lzeKyq1sOlWU4RsdjSsgDWR2D7An1nFgLXNBU9hocKnWQ9jRsps6kCLqKd7Q77zNEhHm_Xlb6J_Fci6kK7tXVM3U6H8OajjcTA18eFcr-kv0etZJZBWlMhtP84xj4WiVDZnPWaMo7AL3jRrHH32grJ3eRA2PAoZmhg80= description: | A base64 encoded and encrypted string used for paging. If the value is not null, it should be passed in the next request to get the next page. If null, no more pages are available. report_start: type: string format: date-time description: | Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ. example: '2021-01-23T04:56:07Z' report_end: type: string format: date-time description: | Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ. example: '2021-01-26T04:56:07Z' granularity: type: string description: Requested granularity. HOUR, DAY, or LIFETIME. allOf: - $ref: '#/components/schemas/TimeDimensionType' example: HOUR rows: description: | List of aggregate report rows that contain the entity and the time series information associated with the underlying entity. type: array items: $ref: '#/components/schemas/AggregateReportRow' example: - entity_type: AD_SET entity_id: 9a7b6c5d-4e3f-4b21-8c99-bf1c2a3d4e5f entity_name: Ad Set 1 entity_status: ACTIVE start_time: '2025-08-01T00:00:00Z' end_time: '2025-08-02T00:00:00Z' stats: - field_type: IMPRESSIONS field_value: 1920 - field_type: STREAMED_IMPRESSIONS field_value: 1920 - field_type: CLICKS field_value: 9 - field_type: SPEND field_value: 17.482913 warnings: description: | List of warning messages indicating that the request has minor issues, despite the response being successful. i.e. when the continuation_token is supplied along with other parameters. type: array items: type: string example: - entity_type: AD_SET entity_id: 9a7b6c5d-4e3f-4b21-8c99-bf1c2a3d4e5f entity_name: Ad Set 1 entity_status: ACTIVE start_time: '2025-08-01T00:00:00Z' end_time: '2025-08-02T00:00:00Z' stats: - field_type: IMPRESSIONS field_value: 1920 - field_type: STREAMED_IMPRESSIONS field_value: 1920 - field_type: CLICKS field_value: 9 - field_type: SPEND field_value: 17.482913 - entity_type: AD_SET entity_id: 9a7b6c5d-4e3f-4b21-8c99-bf1c2a3d4e5f entity_name: Ad Set 1 entity_status: ACTIVE start_time: '2025-08-02T00:00:00Z' end_time: '2025-08-03T00:00:00Z' stats: - field_type: IMPRESSIONS field_value: 1811 - field_type: STREAMED_IMPRESSIONS field_value: 1811 - field_type: CLICKS field_value: 14 - field_type: SPEND field_value: 16.994382 - entity_type: AD_SET entity_id: 9a7b6c5d-4e3f-4b21-8c99-bf1c2a3d4e5f entity_name: Ad Set 1 entity_status: ACTIVE start_time: '2025-08-03T00:00:00Z' end_time: '2025-08-04T00:00:00Z' stats: - field_type: IMPRESSIONS field_value: 1888 - field_type: STREAMED_IMPRESSIONS field_value: 1888 - field_type: CLICKS field_value: 15 - field_type: SPEND field_value: 17.112837 - entity_type: AD_SET entity_id: 9a7b6c5d-4e3f-4b21-8c99-bf1c2a3d4e5f entity_name: Ad Set 1 entity_status: ACTIVE start_time: '2025-08-04T00:00:00Z' end_time: '2025-08-05T00:00:00Z' stats: - field_type: IMPRESSIONS field_value: 1855 - field_type: STREAMED_IMPRESSIONS field_value: 1855 - field_type: CLICKS field_value: 11 - field_type: SPEND field_value: 16.785441 InsightDimensionType: type: string enum: - ACT_AND_SET - AGE - AUDIENCE - COUNTRY - FORMAT - GENDER - GENRE - INTERESTS - PLATFORM - TONE description: | InsightDimensionType describes the "second-level" insight that a particular report request is interested in. For example, passing the PLATFORM parameter in a request will generate a LIFETIME report of all requested metrics across IOS, ANDROID, and WEB. example: PLATFORM AudienceInsightReportRow: type: object properties: name: type: string description: The name associated with the ad set. example: My First Ad Set id: allOf: - $ref: '#/components/schemas/Uuid' example: 7f4c1cc9-9a1d-4b65-b05c-46e5e33b6705 description: ID of the ad set. status: type: string allOf: - $ref: '#/components/schemas/ReportEntityStatus' description: Status of the ad set. example: ACTIVE insight_value: description: | Value of the insight associated with this row. For example, if the requested insight is AGE, then a potential value is "18-25"; alternatively, if COUNTRY was requested, a value could be "US". type: string example: IOS stats: description: | Array of Report Fields that were requested for this particular insight value. Note: the report fields in this array are LIFETIME values. type: array items: $ref: '#/components/schemas/ReportField' AudienceInsightResponse: type: object properties: granularity: type: string example: LIFETIME entity: $ref: '#/components/schemas/EntityDimensionType' insight: $ref: '#/components/schemas/InsightDimensionType' rows: type: array items: $ref: '#/components/schemas/AudienceInsightReportRow' example: granularity: LIFETIME entity: AD_SET insight: PLATFORM rows: - id: 7f4c1cc9-9a1d-4b65-b05c-46e5e33b6705 name: Ad Set One status: ACTIVE insight_value: IOS stats: - field_type: CLICKS field_value: 100 - field_type: CTR field_value: 0.56 AsyncReportGranularity: type: string enum: - DAY - LIFETIME description: | Reporting granularity for time breakdowns. Supported values are LIFETIME and DAY. For DAY, each row of the report for the primary entity will contain time series data within the range of report_start and report_end broken down by day. default: LIFETIME example: LIFETIME AsyncReportDimension: type: string enum: - AD_ACCOUNT_NAME - AD_ACCOUNT_CURRENCY - CAMPAIGN_NAME - CAMPAIGN_STATUS - CAMPAIGN_OBJECTIVE - AD_SET_NAME - AD_SET_STATUS - AD_SET_BUDGET - AD_SET_COST_MODEL - AD_NAME AsyncReportMetric: type: string x-deprecated-enums: type: array items: - E_CPC - INTENT_RATE enum: - AD_COMPLETES - AVG_STREAMS_PER_LISTENER - AVG_STREAMS_PER_NEW_LISTENER - CLICKS - COMPLETION_RATE - CPCL - CPM - CTR - FREQUENCY - FREQUENCY_OF_AD_COMPLETES - IMPRESSIONS_OFF_SPOTIFY - IMPRESSIONS_ON_SPOTIFY - INTENT_RATE - LISTENERS - LISTENER_CONVERSION_RATE - NEW_LISTENERS - NEW_LISTENER_CONVERSION_RATE - PLAYED_TO_100 - PLAYED_TO_25 - PLAYED_TO_50 - PLAYED_TO_75 - REACH - REACH_OF_AD_COMPLETES - SPEND - STARTS - STREAMS - UNMUTES - MODELED_ADD_TO_CART - MODELED_LEADS - MODELED_PAGE_VIEWS - MODELED_PURCHASES - UNMODELED_ADD_TO_CART - UNMODELED_LEADS - UNMODELED_PAGE_VIEWS - UNMODELED_PURCHASES - VIDEO_VIEWS - VIDEO_EXPANDS - VIDEO_EXPAND_RATE - SKAD_APP_INSTALLS - KOCHAVA_APP_INSTALLS - APPSFLYER_APP_INSTALLS - PAGE_VIEWS - LEADS - ADD_TO_CART - PURCHASES - REVENUE - AVERAGE_ORDER_VALUE - RETURN_ON_AD_SPEND - CUSTOMER_ACQUISITION_COST - COST_PER_LEAD - START_CHECKOUT - PRODUCTS - SIGN_UPS - CUSTOM_EVENT_1 - CUSTOM_EVENT_2 - CUSTOM_EVENT_3 - CUSTOM_EVENT_4 - CUSTOM_EVENT_5 AsyncReportEntityStatus: type: string enum: - ACTIVE - COMPLETED - STOPPED - PAUSED - PENDING_APPROVAL - REJECTED CreateAsyncReportRequest: type: object required: - name - granularity - dimensions - metrics properties: name: type: string description: | Users can define the report name. It must be between 2 and 120 characters long and can't contain any special characters except for "_" and "-". example: My Report granularity: $ref: '#/components/schemas/AsyncReportGranularity' dimensions: type: array description: | Users can define a set of dimensions that they would like populated as columns in the report. The primary entity of the data displayed in the report will be determined by the lowest level of the selected dimensions. The hierarchy of dimensions is Ad Account -> Campaign -> Ad Set -> Ad. For example, If the user selects AD_ACCOUNT_NAME the primary entity will be the Ad Account. If the user selects AD_ACCOUNT_NAME and CAMPAIGN_NAME, the primary entity will be the Campaign. If the user selects AD_SET_NAME and CAMPAIGN_NAME, the primary entity will be the Ad Set. If the user selects CAMPAIGN_NAME, AD_SET_NAME and AD_NAME, the primary entity will be the Ad. items: $ref: '#/components/schemas/AsyncReportDimension' example: - CAMPAIGN_NAME - AD_SET_NAME metrics: type: array description: | Users can define a set of metrics that they would like populated as columns in the report. items: $ref: '#/components/schemas/AsyncReportMetric' example: - IMPRESSIONS_ON_SPOTIFY - SPEND statuses: type: array description: | Users can define a set of statuses that will be used to filter the primary entity displayed in the report. Not every status is valid for each entity type. The valid statuses for each entity are the following: Ad: APPROVED, ARCHIVED, PENDING, PENDING_APPROVAL, REJECTED Ad Set: ACTIVE, APPROVED, ARCHIVED, COMPLETED, PENDING_APPROVAL, READY, REJECTED Campaign: ACTIVE, APPROVED, ARCHIVED, COMPLETED, PENDING_APPROVAL, READY, REJECTED, PAUSED Note: The status for the Campaign entity type is not its direct status but is derived from its Ad Sets' statuses. items: $ref: '#/components/schemas/AsyncReportEntityStatus' example: - ACTIVE - COMPLETED default: - ACTIVE campaign_ids: type: array description: | A list of Campaign IDs to include in the report. Leaving this field empty means the user wants a report of all campaigns. This filter will be ignored if the primary entity is the Ad Account. items: $ref: '#/components/schemas/Uuid' example: [] default: [] report_start: type: string format: date-time description: | The report time range start time. This field is required if the granularity is DAY. Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset (YYYY-MM-DDTHH:MM:SSZ) and must be expressed in whole hours (0 minutes and 0 seconds). Hours are inclusive, which means that requesting T00:00:00 – T23:00:00, for example, will return data for the full 24 hours (from T23:00:00 through T23:59:59). When specifying the time range for reports, please adhere to the following guidelines based on the selected granularity. - LIFETIME: For lifetime reports, the time component will be truncated to zero. For example, 2021-01-23T22:15:15Z -> 2021-01-23T00:00:00Z. The start and end date (if specified) must also be within 365 days of each other. - DAY: The start and end date must be within 365 days of each other. In addition, UTC midnight timestamps must be used (no hours, minutes, or seconds). example: '2024-01-23T00:00:00Z' report_end: type: string format: date-time description: | The report time range end time. This field is required if the granularity is DAY. Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset (YYYY-MM-DDTHH:MM:SSZ) and must be expressed in whole hours (0 minutes and 0 seconds). Hours are inclusive, which means that requesting T00:00:00 – T23:00:00, for example, will return data for the full 24 hours (from T23:00:00 through T23:59:59). When specifying the time range for reports, please adhere to the following guidelines based on the selected granularity. - LIFETIME: For lifetime reports, the time component will be truncated to zero. For example, 2021-01-23T22:15:15Z -> 2021-01-23T00:00:00Z. The start and end date (if specified) must also be within 365 days of each other. - DAY: The start and end date must be within 365 days of each other. In addition, UTC midnight timestamps must be used (no hours, minutes, or seconds). - LIFETIME and DAY: The end date will be inclusive, meaning that the data for the entire day of the specified end date will be included in the report. For example, if the end date is 2021-01-23T00:00:00Z, the report will include the data for the entire day of 2021-01-23 (UTC). example: '2024-02-23T00:00:00Z' CreateAsyncReportResponse: type: object properties: id: $ref: '#/components/schemas/Uuid' description: | The response will contain the ID of the created report. This ID can be used as a path parameter to retrieve the report status and result via the Get Async Report endpoint. AsyncReportStatus: description: | The status that represents the state of the report. type: string enum: - PROCESSING - READY - EXPIRED - FAILED example: READY AsyncReportResponse: type: object properties: status: $ref: '#/components/schemas/AsyncReportStatus' submitted_at: type: string format: date-time description: | Time is in ISO 8601 format. example: '2021-01-23T04:56:07Z' completed_at: type: string format: date-time description: | Time is in ISO 8601 format. example: '2021-01-23T04:57:07Z' report_url: type: string format: uri description: | URL of the CSV report example: https://storage.googleapis.com/ads-selfserve-reports-export/11f57421-1234-5678-a203-6cd9695987e2/e8da1819-38ab-9876-5432-682fccd08700/Report_12345.csv ArtistTargetsResponse: type: object properties: artists: type: array items: $ref: '#/components/schemas/ContentPromotionBase' GenreTargetsResponse: type: object properties: genres: type: array items: $ref: '#/components/schemas/TargetBase' example: genres: - name: Rock id: rock CountryCode: type: string default: '' description: The country or region of a geo in ISO alpha-2 country code format. x-spotify-include-in-example: true example: US GeoTarget: type: object properties: country_code: type: string description: The country or region of the geo in ISO alpha-2 country code format. example: US id: type: string description: A unique identifier for a geo. example: '94110' type: type: string description: The geo type. example: DMA_REGION name: type: string description: Name of the geo. example: San Francisco parent_geo_name: type: string description: The parent location to this geo if it exists (e.g. city, state, or country). example: California description: An object that represents the geo target entity. GeoTargetsResponse: type: object properties: offset: type: integer page_size: type: integer geos: type: array items: $ref: '#/components/schemas/GeoTarget' InterestWithSubtargets: allOf: - $ref: '#/components/schemas/TargetBase' - type: object properties: subtargets: type: array items: $ref: '#/components/schemas/TargetBase' InterestTargetsResponse: type: object properties: interests_with_subtargets: type: array items: $ref: '#/components/schemas/InterestWithSubtargets' example: interests_with_subtargets: - id: 661a6418-1fa0-4640-a86b-8fb1ef5249f8 name: Academic Interests subtargets: - id: 32147515-b339-4b35-80c7-309ce4bb9024 name: Clinical Science - id: 5bd1a4c8-11db-4245-85f7-b3571aec0a9e name: History - id: b7167be4-4a1f-421d-96b8-6211d723e3ad name: Medicine and Healthcare - id: 5012bb54-9ff3-404e-b892-afffa7e08cdf name: Business and Finance subtargets: - id: 1f926bd0-bc40-49db-8a70-d8fcc068be58 name: Marketing and advertising - id: 91e181b4-a0ad-4ab5-bd66-64457da7d1db name: Sales LanguageTargetsResponse: type: object properties: languages: type: array items: $ref: '#/components/schemas/TargetBase' example: languages: - name: English id: en PlaylistTargetsResponse: type: object properties: playlists: type: array items: $ref: '#/components/schemas/TargetBase' example: playlists: - name: Holidays id: holidays EpisodeTopicTargetsResponse: type: object properties: episode_topics: type: array items: $ref: '#/components/schemas/TargetBase' example: episode_topics: - name: Healthy Living id: healthy-living SensitiveTopicTargetsResponse: type: object properties: sensitive_topics: type: array items: $ref: '#/components/schemas/TargetBase' example: sensitive_topics: - name: Crime and Violence id: crime-and-violence - name: Alcohol id: alcohol parameters: ad_account_id: name: ad_account_id in: path required: true schema: $ref: '#/components/schemas/Uuid' description: A unique identifier for an Ad Account. example: ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a q: name: q in: query required: false schema: type: string description: Query to search by keyword via case-insensitive wildcard matching. x-spotify-include-in-example: true example: query ad_set_id: name: ad_set_id in: path required: true schema: $ref: '#/components/schemas/Uuid' limit: name: limit in: query required: false schema: type: integer minimum: 1 maximum: 50 default: 50 description: Limit or page size for a given response. example: 50 offset: name: offset in: query required: false schema: type: integer default: 0 description: Starting position of the next record to assist in data pagination. example: 0 sort_direction: name: sort_direction in: query required: false schema: $ref: '#/components/schemas/SortDirection' description: Field by which to order the results of the query. example: ASC adset_sort_field: name: sort_field in: query schema: $ref: '#/components/schemas/AdSetSortField' campaign_ids: name: campaign_ids in: query required: false description: A list of Campaign IDs to fetch Ad Sets for only the given subset of Campaigns schema: type: array items: $ref: '#/components/schemas/Uuid' name: name: name description: The string that will be used to filter Ad Set by name. The filter is case-insensitive and will match any Ad Set that contains the given string in its name. in: query schema: type: string statuses: name: statuses description: The set of enums that will be used to filter Ad Set by statuses. The filter will match any Ad Set that has one of the given statuses. in: query schema: type: array items: $ref: '#/components/schemas/AdSetStatus' uniqueItems: true ad_fields: name: fields in: query schema: type: array items: $ref: '#/components/schemas/AdField' uniqueItems: true minItems: 1 default: - AD_ACCOUNT_ID - ADVERTISER_NAME - AD_PREVIEW_URL - AD_SET_ID - ASSET_URI - ASSETS - CAMPAIGN_ID - CALL_TO_ACTION - CATALOG - CREATED_AT - UPDATED_AT - DV_CLIENT_CODE - DELIVERY - ID - METADATAS - NAME - REJECT_REASON - REJECT_REASONS - STATUS - SLOT_POSITIONS - START_TIME - SURVEY - END_TIME - NOTARY_METADATA - TAGLINE - THIRD_PARTY_TRACKING - VERSION description: Subset of ad fields to be returned. example: - NAME - CREATED_AT - STATUS ad_set_ids: name: ad_set_ids in: query required: false description: A list of Ad Set IDs to fetch Ads for only the given subset of Ad Sets schema: type: array items: $ref: '#/components/schemas/Uuid' asset_ids: name: asset_ids in: query required: false description: A list of Asset IDs to fetch Ads for only the given subset of Assets schema: type: array items: $ref: '#/components/schemas/Uuid' parameters-name: name: name description: The string that will be used to filter Ad by name. The filter is case-insensitive and will match any Ad that contains the given string in its name. in: query schema: type: string parameters-statuses: name: statuses description: The set of enums that will be used to filter Ad by statuses. The filter will match any Ad that has one of the given statuses. in: query schema: type: array items: $ref: '#/components/schemas/AdStatus' uniqueItems: true ad_sort_field: name: sort_field in: query schema: $ref: '#/components/schemas/AdSortField' ad_id: name: ad_id in: path schema: $ref: '#/components/schemas/Uuid' required: true parameters-asset_ids: name: asset_ids in: query required: false schema: type: array uniqueItems: true items: $ref: '#/components/schemas/Uuid' asset_types: name: asset_types in: query required: false schema: type: array uniqueItems: true items: $ref: '#/components/schemas/AssetType' asset_subtypes: name: asset_subtypes in: query required: false schema: type: array uniqueItems: true items: $ref: '#/components/schemas/GeneralAudioType' asset_statuses: name: statuses in: query required: false schema: type: array uniqueItems: true items: $ref: '#/components/schemas/Status' aspect_ratios: name: aspect_ratios in: query required: false schema: type: array uniqueItems: true items: $ref: '#/components/schemas/AspectRatio' components-parameters-name: name: name in: query required: false schema: type: string description: Search word provided is applied to the asset name. parameters-sort_direction: name: sort_direction in: query required: false schema: $ref: '#/components/schemas/SortDirection' sort_field: name: sort_field in: query required: false schema: $ref: '#/components/schemas/SortField' asset_id: name: asset_id in: path required: true schema: $ref: '#/components/schemas/Uuid' audience_ids: name: audience_ids in: query schema: type: array items: $ref: '#/components/schemas/Uuid' audience_types: name: audience_types in: query schema: type: array items: $ref: '#/components/schemas/AudienceType' audience_sort_field: name: sort_field in: query schema: $ref: '#/components/schemas/AudienceSortField' audience_id: name: audience_id in: path schema: $ref: '#/components/schemas/Uuid' required: true business_id: name: business_id in: path required: true schema: $ref: '#/components/schemas/Uuid' campaignIds: name: campaign_ids in: query schema: type: array items: $ref: '#/components/schemas/Uuid' description: A list of campaigns to return. required: false campaigns-v3_components-parameters-name: name: name description: The string that will be used to filter campaigns by name. The filter is case-insensitive and will match any campaign that contains the given string in its name. in: query schema: type: string adSetStatuses: name: ad_set_statuses description: The set of enums that will be used to filter campaigns by their ad set statuses. The filter will match any campaign that has at least one ad set with the given status. in: query schema: type: array items: $ref: '#/components/schemas/AdSetStatus' uniqueItems: true campaignStatuses: name: statuses in: query description: Filter by campaign's status required: false schema: type: array items: $ref: '#/components/schemas/CampaignStatus' fields: name: fields in: query schema: type: array items: $ref: '#/components/schemas/CampaignField' uniqueItems: true minItems: 1 default: - ID - NAME - CREATED_AT - UPDATED_AT - STATUS - DELIVERY - PURCHASE_ORDER - OBJECTIVE - MEASUREMENT_METADATA - DELIVERY_GOAL_GROUP - DERIVED_STATUS - RESTRICTED_AD_CATEGORY description: Subset of campaign fields to be returned. example: - NAME - CREATED_AT - STATUS parameters-sort_field: name: sort_field in: query schema: $ref: '#/components/schemas/CampaignSortField' campaign_id: name: campaign_id in: path schema: $ref: '#/components/schemas/Uuid' required: true experiment_id: name: experiment_id in: path schema: $ref: '#/components/schemas/Uuid' required: true survey_question_id: name: survey_question_id in: path required: true schema: $ref: '#/components/schemas/Uuid' description: The unique identifier for the survey question. example: f47ac10b-58cc-4372-a567-0e02b2c3d479 mobile_app_id: name: mobile_app_id in: path required: true schema: $ref: '#/components/schemas/Uuid' description: A unique identifier for a mobile app. example: ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a include_events: name: include_events in: query required: false schema: type: boolean default: false description: | When true, the response will include events that have been set up, such as page view, purchase, and lead events. example: false include_historical_events: name: include_historical_events in: query required: false schema: type: boolean default: false description: | When true, the response will include historical events in the response. Historical events are hourly aggregates of counts of events, intended for debugging use, i.e. verifying that a Javascript hook has been installed correctly and is firing events. There may be up to 20 minutes of delay. If true, historical_events_start_date and historical_events_end_date become required fields. Note: Including historical events can add several seconds to the response time. example: false historical_events_start_date: name: historical_events_start_date in: query required: false schema: type: string description: | When include_historical_events is true, the first date of historical events to include. Date should be in ISO 8601 format: yyyy-MM-dd. example: '2023-07-27' historical_events_end_date: name: historical_events_end_date in: query required: false schema: type: string description: | When include_historical_events is true, the last date of historical events to include. Date should be in ISO 8601 format: yyyy-MM-dd. example: '2023-08-02' pixel_id_path_param: name: pixel_id in: path required: true schema: $ref: '#/components/schemas/PixelId' capi_connection_id: name: capi_connection_id in: path schema: $ref: '#/components/schemas/CapiConnectionId' required: true capi_auth_token_id: name: capi_auth_token_id in: path schema: $ref: '#/components/schemas/CapiAuthTokenId' required: true dataset_id: name: dataset_id in: path schema: $ref: '#/components/schemas/DatasetId' required: true integration_id: name: integration_id in: path schema: $ref: '#/components/schemas/IntegrationId' required: true granularities: name: granularities in: query required: true description: A list of diagnostic granularities to retrieve for a dataset. schema: type: array items: $ref: '#/components/schemas/Granularity' datasource_ids: name: datasource_ids in: query required: false description: A list of datasources you want to filter by. schema: type: array items: $ref: '#/components/schemas/DatasourceId' show_ids: name: ids in: query required: false schema: $ref: '#/components/schemas/SearchedParams' description: A list of unique identifiers for podcast shows. example: - 3zaHNdVeLiqOSXwxdoWcij market: name: market in: query required: true schema: type: string minLength: 2 description: An ISO 3166-1 alpha-2 country code. Only content that is available in that market will be returned. example: US entity_type: name: entity_type in: query required: false x-spotify-include-in-example: true schema: $ref: '#/components/schemas/EntityDimensionType' description: | A reporting dimension for entity-level breakdowns. This field is required if continuation_token is not set. example: AD_SET report_fields: name: fields in: query x-spotify-include-in-example: true required: false schema: type: array default: [] items: $ref: '#/components/schemas/ReportFieldType' description: | A list of fields requested in the report. This field is required if continuation_token is not set. Refer to the Metrics Glossary for definitions: https://developer.spotify.com/documentation/ads-api/guides#metrics-glossary example: - IMPRESSIONS - STREAMED_IMPRESSIONS - CLICKS - SPEND report_start: name: report_start in: query required: false x-spotify-include-in-example: true schema: type: string format: date-time description: | The report time range start time. Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset (YYYY-MM-DDTHH:MM:SSZ) and must be expressed in whole hours (0 minutes and 0 seconds). Hours are inclusive, which means that requesting T00:00:00 – T23:00:00, for example, will return data for the full 24 hours (from T23:00:00 through T23:59:59). When specifying the time range for reports, please adhere to the following guidelines based on the selected granularity. - LIFETIME: For lifetime reports, the time component will be truncated to zero. For example, 2021-01-23T22:15:15Z -> 2021-01-23T00:00:00Z. The start and end date (if specified) must also be within 90 days of each other. - DAY: The start and end date must be within 90 days of each other. In addition, UTC midnight timestamps must be used (no hours, minutes, or seconds). - HOUR: The report range must be within the last 2 weeks. example: '2025-08-01T00:00:00Z' report_end: name: report_end in: query required: false x-spotify-include-in-example: true schema: type: string format: date-time description: | The report time range end time. Time should be in ISO 8601 format using Coordinated Universal Time (UTC) with a zero offset (YYYY-MM-DDTHH:MM:SSZ) and must be expressed in whole hours (0 minutes and 0 seconds). Hours are inclusive, which means that requesting T00:00:00 – T23:00:00, for example, will return data for the full 24 hours (from T23:00:00 through T23:59:59). When specifying the time range for reports, please adhere to the following guidelines based on the selected granularity. - LIFETIME: For lifetime reports, the time component will be truncated to zero. For example, 2021-01-23T22:15:15Z -> 2021-01-23T00:00:00Z. The start and end date (if specified) must also be within 90 days of each other. - DAY: The start and end date must be within 90 days of each other. In addition, UTC midnight timestamps must be used (no hours, minutes, or seconds). - LIFETIME and DAY: The end date will be inclusive, meaning that the data for the entire day of the specified end date will be included in the report. For example, if the end date is 2021-01-23T00:00:00Z, the report will include the data for the entire day of 2021-01-23 (UTC). - HOUR: The report range must be within the last 2 weeks. example: '2025-08-02T00:00:00Z' granularity: name: granularity in: query required: false x-spotify-include-in-example: true schema: type: string default: LIFETIME allOf: - $ref: '#/components/schemas/TimeDimensionType' description: | A reporting granularity for time breakdowns. Supported values are LIFETIME, DAY, HOUR. For DAY and HOUR, each row of the response for a particular entity will contain time series data within the range of report_start and report_end broken down by day or hourly, respectively. example: DAY include_parent_entity: name: include_parent_entity in: query required: false x-spotify-include-in-example: true example: false schema: type: boolean default: false description: | If include_parent_entity=true, the report will also include information about the parent in the ad hierarchy for each returned entity. This parameter defaults to false. Examples: Aggregate report broken down by AD_SET, including parent CAMPAIGN information ?entity_type=AD_SET&include_parent_entity=true Aggregate report broken down by AD, including parent AD_SET information ?entity_type=AD&include_parent_entity=true Restrictions: 1. This parameter is not valid for AD_ACCOUNT and CAMPAIGN entity_type requests, as they are already considered top-level types. 2. This parameter is only valid for aggregate requests and not audience insight requests. 3. Passing this parameter without an entity_type set is not allowed. entity_ids: name: entity_ids in: query required: false x-spotify-include-in-example: true schema: type: array default: [] items: type: string format: uuid description: | A list of one or more campaign, ad set, or ad IDs by which to filter reporting. If this field is set, the entity_ids_type field is required. Aggregate Report: - A maximum of 50 entities can be requested. Insight Report: - Only one ID at a time is currently supported. Restrictions: 1. This parameter is not valid for AD_ACCOUNT entity_type requests, since the ID is derived from the ad_account_id. example: - 9a7b6c5d-4e3f-4b21-8c99-bf1c2a3d4e5f entity_ids_type: name: entity_ids_type in: query required: false x-spotify-include-in-example: true schema: $ref: '#/components/schemas/EntityDimensionType' description: | The entity type of IDs contained in the entity_ids field. If entity_ids is set, this field is required. Furthermore, the only acceptable value for insight reports is AD_SET. When using a granularity that is not LIFETIME, entity id types must match the type of the entity requested Restrictions: 1. This parameter is not valid for AD_ACCOUNT entity_type requests, as the ID is derived from ad_account_id and the type is always considered AD_ACCOUNT. example: AD_SET entity_status_type: name: entity_status_type in: query required: false x-spotify-include-in-example: true schema: $ref: '#/components/schemas/EntityDimensionType' description: | The entity type of statuses contained in the statuses field. If statuses is set, this field is required. Furthermore, the only acceptable value for insight reports is AD_SET. Restrictions: 1. This parameter is not valid for AD_ACCOUNT entity_type requests. example: AD_SET entity_statuses: name: statuses in: query required: false x-spotify-include-in-example: true schema: type: array default: [] items: $ref: '#/components/schemas/ReportEntityStatus' description: | A list of one or more campaign, ad set, or ad statuses by which to filter reporting. If this field is set, the entity_status_type field is required. Restrictions: 1. This parameter is not valid for AD_ACCOUNT entity_type requests. example: - ACTIVE continuation_token: name: continuation_token in: query required: false schema: nullable: true type: string description: | A base64 encoded and encrypted string used for pagination, returned in the response of previous calls to this endpoint. When this parameter is supplied, no other parameters should be used, as they will be ignored by the endpoint, and the response will contain a warning message. example: AMC-fuxpGRIqFcOUEzDEdWQsM5Iy7mkRThKFo94mEys6RF1lzeKyq1sOlWU4RsdjSsgDWR2D7An1nFgLXNBU9hocKnWQ9jRsps6kCLqKd7Q77zNEhHm_Xlb6J_Fci6kK7tXVM3U6H8OajjcTA18eFcr-kv0etZJZBWlMhtP84xj4WiVDZnPWaMo7AL3jRrHH32grJ3eRA2PAoZmhg80= insight_dimension: name: insight_dimension in: query required: false x-spotify-include-in-example: true schema: $ref: '#/components/schemas/InsightDimensionType' description: | A reporting dimension for insight breakdowns. This field is required if continuation_token is not set. example: GENRE report_id: name: report_id in: path required: true schema: $ref: '#/components/schemas/Uuid' description: A unique identifier for a report ID. example: ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a artist_ids: name: ids in: query required: false schema: $ref: '#/components/schemas/SearchedParams' description: A list of unique identifiers for artists. example: - 1XpDYCrUJnvCo9Ez6yeMWh genre_ids: name: ids in: query required: false schema: $ref: '#/components/schemas/SearchedParams' description: A list of unique identifiers for genres. example: - rock - jazz country_code: name: country_code in: query required: false description: The country or region of a geo in ISO alpha-2 country code format. schema: $ref: '#/components/schemas/CountryCode' geo_ids: name: ids in: query required: false schema: $ref: '#/components/schemas/SearchedParams' description: A list of unique identifiers for geos. example: - '5259444' - US:11214 types: name: types in: query required: false schema: $ref: '#/components/schemas/SearchedParams' description: A list of geo types. x-spotify-include-in-example: true example: - CITY - COUNTRY - DMA_REGION - POSTAL_CODE - REGION geo_limit: name: limit in: query required: false schema: type: integer minimum: 1 maximum: 1000 default: 50 description: | Limit or page size for a given response. The maximum limit is 50, except for when bulk uploading zip codes, where the maximum limit is 1000. example: 50 language: name: language in: query required: false schema: type: string description: A two-letter ISO 639-1 language code for querying geo targets. Defaults to "en" if missing. pattern: ^[a-z]{2}$ example: en interest_ids: name: ids in: query required: false schema: $ref: '#/components/schemas/SearchedParams' description: A list of unique identifiers for interests. example: - ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a language_ids: name: ids in: query required: false schema: $ref: '#/components/schemas/SearchedParams' description: A list of unique identifiers for languages. example: - en - cz ad_account_id_query: name: ad_account_id in: query required: false schema: $ref: '#/components/schemas/Uuid' description: Optional ad account ID for per-account feature flag resolution. When omitted, returns safe default behavior. example: ce4ff15e-f04d-48b9-9ddf-fb3c85fbd57a playlist_ids: name: ids in: query required: false schema: $ref: '#/components/schemas/SearchedParams' description: A list of unique identifiers for playlists. example: - cooking - gaming episode_topic_ids: name: ids in: query required: false schema: $ref: '#/components/schemas/SearchedParams' description: A list of unique identifiers for podcast episode topics. example: - healthy-living sensitive_topic_ids: name: ids in: query required: false schema: $ref: '#/components/schemas/SearchedParams' description: A list of unique identifiers for sensitive topics. example: - gambling links: GetAdSetForAd: operationId: getAdSetById parameters: ad_account_id: $parameters.ad_account_id ad_set_id: $response.body#/ad_set_id description: Get an ad set by ID.