Ads API
About
The Spotify Ads API lets you build, manage, and report on Ad Studio campaigns. This guide can help you get started. Topics include:
- Getting started requirements and instructions
- An Ad Studio overview
- Descriptions of available endpoints
- Help and support information
Next steps
If you're not sure what to do now, try these recommendations:
-
New to the Ads API? See the Quick Start section. It provides instructions about how to set up an account to work with our API.
-
Already using the Ads API? Great! Check the Release Notes section for information on the latest changes, or browse the available methods below.
Support
To report a bug or ask questions about this service, contact the Ads API team at ads-api-support@spotify.com.
Subscribe to Newsletter
Sign up for our monthly Ads API newsletter here if you want to receive updates about new releases, testing opportunities, and more!
API Design
This section covers important design elements that affect how the Ads API works. Take a moment to review this information.
Rate Limiting
Rate limiting caps the number of API calls a user or app can make within a set period of time. The Ads API applies RPS rate limits on a per app basis for each client ID, regardless of the number of simultaneous app users. These limits help Spotify provide API access equitably to all our engineering partners.
Note: If our API returns status code 429, it means that you have sent too many requests. When this happens, check the Retry-After header, where you will see a number displayed. This is the number of seconds that you need to wait before you try your request again.
Rate Limit On | Rate Limit Request | Window (seconds) | Sustained Requests per second (RPS) limit |
---|---|---|---|
Client ID | 1500 | 30s | 50 RPS |
IP | 500 | 10s | 50 RPS |
We have two types of rate limits per partner for production:
- per partner integration 50 rps (calculated in 30 second window)
- per IP 15 rps (calculated in 10 second window)
Versioning
The most recent version of the Ads API is v2.
All endpoints are versioned with a version number in the URI. Version numbers are integers starting with a 1 or 2, and the version number is a prefix of the URI.
In accordance with semantic versioning, versions are bumped when there is a backwards-incompatible change that necessitates it. Major version releases are reserved for major API changes, such as complete revamping of our schemas or a new business model. Other than that, new fields, small schema changes etc fall under a minor change (such as 2.1).
Updates that do not break existing consumers will be deployed to the current version as patch releases.
Patch releases:
- Addition of new optional request body parameters to existing API methods
- Bug fixes that would not warrant a minor, or major release
- Changing the order of properties in existing API responses
- Documentation updates
- Testing improvements (e.g. more validation, coverage, etc.)
- Codebase improvements
- Addition of new endpoints
Minor releases, e.g. /v1.2/
to /v1.3/
:
- Addition of new required request body parameters
- Default value is changed
- Deprecation of existing endpoints
- Deprecation of existing request body parameters
- Deprecation of URL path parameters
- Modification of response object
Major releases, e.g. /v1.2/
to /v2/
:
- Modifying pre-existing request body parameters
- Modifying pre-existing URL path parameters
- Removing pre-existing endpoints
For each of these releases, the API team will communicate with clients and detail the changes in the API Release Notes.
Version Schedules
We strongly recommend that you use the newest available version when upgrading your integration.
API Version | Release Date | Deprecation Date |
---|---|---|
v2 | August 2023 | TBA |
v1.4 | November 2022 | November 6, 2023 |
v1.3 | July 2022 | November 6, 2023 |
v1.2 | December 2021 | August 25, 2022 |
v1.1 | June 2019 | August 25, 2022 |
v1.0 | March 2019 | July 1, 2022 |
Time Format
Times are always recorded in ISO 8601 format as Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ
.
Pagination
Some endpoints support a way of paging the dataset, taking an offset and limit as query parameters.
limit
specifies the number of results to be returned from the call. If not specified, the default value is 50. The max allowed value is also 50.offset
specifies the starting position of the first result.
If you specify a limit
of 5, the API will return 5 results. On the next page you’d put an offset of 6 to retrieve results 6 through 10. We return the total number of results along with the page size in the paging
object.
Release Notes
This section documents changes made to the Spotify Ads API.
August 2023
Announcing Ads API v2!
All of the following updates are included under a new major version (v2) released on August 8, 2023.
What's Changing
General
- The Campaign Management API is now generally available! These endpoints no longer require a manual allowlisting process to access.
- [Breaking Change] The following entities have been deprecated from the API:
advertiser
: All references to advertiser, including advertiser endpoints, have been removedorganization
: All references to organization have been removedad_set_links
: All references to ad_set_links, including Ad Set Link endpoints, have been removed
- [Breaking Change] All resource names now follow snake_case convention (previously in v1, camelCase was used for path resources)
- [Breaking Change] All
update
requests now use the PATCH method to support partial data updates (previously in v1, PUT was used even though the resource is not fully replaced)
Paging
- [Breaking Change]
page_size
has been renamed tolimit
in all instances (previously in v1, bothpage_size
andlimit
were used) - [New]
paging
object is now returned if pagination is specified. Example:
_10 "paging": {_10 "page_size": 50,_10 "total_results": 17,_10 "offset": 0_10 }
Ad Accounts
- Endpoint to query a single ad account by ID called
Get an Ad Account
is now available - Get Ad Accounts endpoint path has been shortened to GET /ad_accounts (was previously GET /currentUser/adAccounts)
- [Breaking Change] The following parameters have been deprecated from the ad account entity:
organization_id
ad_studio_lead
description
- [Breaking Change] The following parameters have been renamed under the ad account entity:
last_modified
is nowupdated_at
iso_country_code
is nowcountry_code
Campaigns
- [New] The following parameters have been added to the campaign entity:
updated_at
: When the campaign was last updated (read only)purchase_order
: Intended for organizational purposes; if specified, it will be displayed on invoices (optional for Create Campaign requests and cannot be updated)objective
: The objective of the campaign, previously referred to asbid_optimization_goal
at the ad set level (required for Create Campaign requests and cannot be updated)
- [Breaking Change] The following parameters have been deprecated from the campaign entity:
description
advertiser_id
landing_page_domain
version
ad_set_ids
- [Breaking Change] The following endpoints have been deprecated:
- Update Campaign Status
- Get Campaigns (users can continue to call Get Campaigns by Ad Account ID and Get Campaigns by ID endpoints to retrieve campaigns)
- [Breaking Change] The following filters under Get Campaigns by Ad Account ID endpoint have been
deprecated:
ids
(ability to query by a single campaign ID still supported under Get Campaign by ID endpoint, but querying by an array of IDs is no longer supported)advertiser_ids
statuses
name
- [Breaking Change] The following parameters have been renamed under the campaign entity:
created_on
is nowcreated_at
Ad Sets
- [New] The following parameters have been added to the ad set entity:
updated_at
: When the campaign was last updated (read only)- [Breaking Change]
category
: A category that most closely matches the content of the ad(s); certain categories may be subject to restrictions (required for Create Ad Set requests and can be updated) podcast_episode_topics
: Podcast episode topics to target (optional for Create Ad Set requests and can be updated)sensitive_topic_exclusions
: Sensitive podcast episode topics to exclude from ad placements (optional for Create Ad Set requests and can be updated)language
: Languages to target; languages are based on the language users use on Spotify (optional for Create Ad Set requests and cannot be updated)interests
: Interests to target; interests are based on listening habits and playlist preferences (optional for Create Ad Set requests and can be updated)exclude_placements
: When targeting a market where podcast ads are supported, placements will automatically default to include both podcast and music; users can set this parameter toPODCAST
in order to limit their ad placement to music only (optional for Create Ad Set requests and can be updated)delivery
: Use to pause/resume ad set delivery; if set toON
, ad set will be served (once ad review is passed and start date occurs) and if set toOFF
, ad set will not be served (optional for Create Ad Set requests and can be updated)
- [Breaking Change] The following parameters have been deprecated from the ad set entity:
advertiser_id
ad_ids
(ability to link an ad to an ad set is still supported at the ad entity level)active_status
ad_set_links
custom_audience_ids
serving_issues
version
- [Breaking Change] The following parameters have had schema changes or been renamed under the
ad set entity:
targeting has been renamed to
targets`budget
object added to the Create Ad Set request in order to match response schema:budget_micro_amount
in the Create Ad Set request is now nested under thebudget
object and renamed tomicro_amount
(previouslybudget_micro_amount
was a root-level parameter)type
parameter has been added to specify aDAILY
orLIFETIME
budget (required for Create Ad Set requests)country_code
has been renamed tocurrency
(read only)
- Names of the following targeting parameters have been simplified:
gender_names
is nowgenders
platform_names
is nowplatforms
- Geo targeting parameters (
country_code
,regions
,dmas
,cities
,postal_codes
) are now nested within a new -geo_targets
object undertargets
- All geo target IDs are now string data type (previously they were integers [int32])
- Metadata (e.g.,
name
) is no longer returned with targeting parameters in Get Ad Set by Ad Account ID response – objects have been flattened into arrays where only the target ID(s) are included now- Metadata is still included in Get Ad Set by Ad Set ID response
artist_promotion
has been renamed topromotion
name
parameter underartist_promotion
has been removedartist_promotion_goal
has been renamed topromotion_goal
- Changes to the following promotion goal enum values:
ARTIST_CONTENT
has been removed (artist targeting is now allowed for any ad set)PODCAST_PROMO
has been added (for promoting a podcast)
artist_promotion_target
object has been removed and replaced withpromotion_target_id
parameter
bid_optimization_goal
has been moved to the campaign entity level and renamedobjective
format
has been moved out of thetargeting
object and is now a root-level parameter, and has been renamed to -asset_format
- [Breaking Change] The following endpoints have been deprecated:
- Update Ad Set Status (ability to update campaign status has been consolidated into Create and Update Ad Set endpoints in v2)
- Get Ad Sets (users can continue to call Get Campaigns by Ad Account ID and Get Campaigns by ID endpoints to retrieve campaigns)
- Get Ad Set Links
- Get Ad Sets by Campaign
- Update Ad Set Link Status
- Get Ad Set Serving Status
- [Breaking Change] The following filters under Get Ad Sets by Ad Account ID endpoint have been
deprecated:
- ids (ability to query by a single ad set ID still supported under Get Ad Set by ID endpoint,
but querying by an array of IDs is no longer supported)
advertiser_ids
campaign_ids
ad_ids
active_statuses
statuses
ad_stauses
name
- ids (ability to query by a single ad set ID still supported under Get Ad Set by ID endpoint,
but querying by an array of IDs is no longer supported)
- [Breaking Change] The following validation logic has been added:
- Minimum budget amount
- Minimum bid amount
Ads
- [New] The following parameters have been added to the ad entity:
- updated_at: When the ad was last updated (read only)
- call to action: The metadata for the behavior of the call-to-action button
text
: The text used for the call-to-action button -- currently defaults toLEARN MORE
but option to configure is coming soon (by end of August 2023)clickthrough_url
: The link to the ads desired landing page.language
: The language in which the call-to-action text is presented -- currently defaults to "ENGLISH" but option to configure is coming soon (by end of August 2023)
delivery
: Use to pause/resume ad delivery; if set toON
, ad will be served (once ad review is passed and start date occurs) and if set toOFF
, ad will not be served (optional for Create Ad requests and can be updated)ad_preview_url
: Link to view a preview of the adad_set_id
: The ID of the ad set to which the ad belongslogo_image_asset
: Part ofassets
object; logo image for the ad (optional for Create Ad requests and can be updated)
- [Breaking Change] The following parameters have been deprecated from the ad entity:
advertiser_id
landing_page_domain
version
- [Breaking Change] The following endpoints have been deprecated:
- Get Ads (users can continue to call Get Ads by Ad Account ID and Get Ads by ID endpoints to retrieve campaigns)
- [Breaking Change] The following parameters have had schema changes or been renamed under the ad entity:
created
has been renamed tocreated_at
brand_name
has been renamed toadvertiser_name
clickthrough_url
is now nested under thecall_to_action
objectassets
object has been simplified to contain the following parameters:asset_id
: ID of an audio or video asset (required on Create Ad requests and can be updated)companion_asset_id
: ID of a companion image asset (required on Create Ad requests and can be updated)logo_asset_id
: Nested underassets
object - ID of a logo image asset (optional on Create Ad requests and can be updated)
third_party_viewability_tracking
has been renamed tothird_party_tracking
and contains the following parameters:measurement_partner
: Name of the third-party measurement partner;DCM
is now supported along withIAS
url
: Third-party tracking URL
- [Breaking Change] The following filters have been deprecated under Get Ads by Ad Account ID endpoint:
ids
(ability to query by a single ad ID still supported under Get Ad by ID endpoint, but querying by an array of IDs is no longer supported)ad_set_ids
statuses
name
Assets
- [Breaking Change] Get Audio Assets, Get Video Assets, and Get Image Assets endpoints have been
deprecated and replaced with a single endpoint called
Get Assets by Asset Type and Ad Account
- [Breaking Change] Get Audio Asset, Get Video Asset, and Get Image Asset endpoints have been
deprecated and replaced with a single endpoint called
Get Asset
- [Breaking Change] Get Fullmix Upload Url, Get Video Upload Url, and Get Image Upload Url endpoints
have been deprecated and replaced with a single
Create Asset
endpoint - [New] The following endpoints have been added to enable asset upload:
- Upload Asset: Upload image, audio, or video assets that are 25 MB or smaller
- Start Upload Chunked Asset: Start a chunked upload session for image, audio, or video assets (required for files that are 25 MB or larger)
- Transfer Chunked Asset: Continues the upload session of a chunked asset by transferring one section of binary media data
- Complete Upload Chunked Asset: Completes the upload session of a chunked asset
- [New] Endpoint to update an asset called
Update Asset
is now available
Targets
- [New] Support for the following new targeting types has been added:
- Postal codes: Postal code IDs can be retrieved via Get Geo Targets endpoint and input as an optional parameter in ‘targeting’ under ad sets entities
- Interests: Interests can be retrieved via new endpoint Get Interest Targets and input as an optional parameter in ‘targeting’ under ad sets entities
- Languages: Languages can be retrieved via new endpoint Get Language Targets and input as an optional parameter in ‘targeting’ under ad sets entities
- Podcast episode topics: Only available for markets where podcast ads are supported – podcast episode topics can be retrieved via new endpoint Get Podcast Episode Targets and input as an optional parameter in ‘targeting’ under ad sets entities
- Podcast sensitive episode topic exclusion: Only available for markets where podcast ads are supported – podcast sensitive episode topics can be retrieved via new endpoint Get Interest Targets and input as an optional parameter in ‘targeting’ under ad sets entities
- [Breaking Change] Consolidation of previous v1 targeting endpoints:
- Get Artist Targets and Search Artist Targets have been consolidated into a single endpoint Get Artist Targets
- Get Genre Targets and Search Genre Targets have been consolidated into a single endpoint
Get Genre Targets
- Querying by ids is no longer supported
- Get Playlist Targets and Search Playlist Targets have been consolidated into a single endpoint
Get Playlist Targets
- Querying by ids is no longer supported
- Get Geo Targets and Search Geo Targets have been consolidated into a single endpoint Get Geo Targets
- New parameter
parent_geo_name
added to geo target entity - Renamed
id
andtype
parameters togeo_id
andgeo_type
under geo target entity
- New parameter
Reporting
- [Breaking Change] Create Report and Create Report by Ad Account have been deprecated and replaced
with the following endpoints:
- Get Aggregate Report by Ad Account Id: Returns aggregated ad campaign metrics based on requested fields and dimensions
- Get Insight Report by Ad Account Id: Returns ad campaign metrics broken out by audience insights (e.g., age, gender, genre) based on requested fields – available only as ad set level breakdown at lifetime granularity and does not support report start/end time filtering
- [Breaking Change] The following
dimensions
values have been deprecated:YEAR
MONTH
CURRENCY
COST_TYPE
ADVERTISER
DMA
REGION
- [Breaking Change] The following
fields
values have been deprecated:FETCHES
RENDER_RATIO
FETCH_REACH
SERVES
ERRORS
COMPLETION_RATE
- [Breaking Change] The following fields have been renamed:
SERVE_REACH
is nowREACH
SERVE_FREQ
is nowFREQUENCY
- [Breaking Change] The following filters have been deprecated:
advertiser_ids
country_isos
region_ids
dma_ids
platforms
ad_set_start_dates
ad_set_end_dates
cost_type_filters
organization_ids
ad_account_ids
(all reports must now include a single ad account ID in the path but filtering by multiple ad account IDs is no longer supported)
- [Breaking Change] Filtering by campaign, ad set, or ad ID(s) has been consolidated into two
generic fields (previously this was supported via separate filters for each entity type):
- entity_ids: A list of one or more campaign, ad set, or ad IDs by which to filter reporting
- entity_ids_type: The entity type of IDs contained in the entity_ids field – if entity_ids is set, this field is required.
- [Breaking Change] Filtering by campaign, ad set, or ad ID status(es) has been consolidated into
two generic fields:
- entity_status_type: The entity type of statuses contained in the statuses field
- statuses: 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
- [New] The following audience insight dimensions have been added and are available under the Get
Insight Report by Ad Account ID endpoint:
AGE
GENDER
GENRE
- [New] The following updates will go into effect on September 1, 2023:
- Data refresh cadence will be increased to hourly (vs every few hours in v1-v1.4) – this will result in a discrepancy between UI and API stats for those who have not yet updated their integration to v2
- Zero-stat campaigns (i.e., campaigns that have not yet been trafficked) will automatically be included in reports
- SPEND field will be capped based on billable impressions; this means that spend tied to delivery over the specified budget will now be filtered out in order to match the UI’s logic
- Support for report start/end filtering on LIFETIME granularity reports (upon initial Aug 8th v2 launch, report start/end filtering will only be available for HOUR or DAY granularity)
Estimates
- Estimate Bid (formerly known as
Get Bid Estimate
)- [Breaking Change] Get Bid Estimate endpoint has been shortened to POST
/estimates/bid
(was previously POST/adAccounts/{ad_account_id}/estimate/bid
) - [Breaking Change]
budget_micro_amount
is no longer required in the request body - [Breaking Change] The following parameters are now required when fetching a bid estimate:
start_date
end_date
asset_format
bid_strategy
currency
- [Breaking Change]
bid_optimization_goal
has been renamed toobjective
- [New] The following optional request body parameters have been added:
- frequency_caps
- Under
targets
object:postal_code_ids
(nested under geo_targets)podcast_episode_topic_ids
sensitive_topic_exclusion_ids
language
interest_ids
exclude_placements
- [Breaking Change] Get Bid Estimate endpoint has been shortened to POST
- Estimate Audience (formerly known as
Get Audience Estimate
)- [Breaking Change] Get Bid Estimate endpoint has been shortened to POST
/estimates/audience
(was previously POST/adAccounts/{ad_account_id}/estimate/audience
) - [Breaking Change] ad_account_id is now a request body parameter (was previously a path parameter)
- [Breaking Change] The following parameters are now required when fetching a bid estimate:
start_date
end_date
asset_format
bid_strategy
budget
(type & micro_amount)
- [Breaking Change]
bid_optimization_goal
has been renamed toobjective
- [New] The following optional request body parameters have been added:
- frequency_caps
- Under
targets
object:postal_code_ids
(nested under geo_targets)podcast_episode_topic_ids
sensitive_topic_exclusion_ids
language
interest_ids
exclude_placements
- [New] The following parameters have been added to the response body:
estimated_frequency_min
estimated_frequency_max
- forecast_type: The time granularity of the forecast -- if a "LIFETIME" budget type is specified, the API will return a single "LIFETIME" forecast type and if a "DAILY" budget type is specified, the API will return "DAILY", "WEEKLY" and "MONTHLY" forecast types
- likely_to_deliver_budget: Indicates the likelihood of spending most of the budget
- [Breaking Change] Get Bid Estimate endpoint has been shortened to POST
Ad Categories [New]
- Get Ad Categories endpoint: Ad categories can be retrieved via this endpoint and input under the
ad_category
parameter in the Create Ad Set request
Podcast Shows [New]
- Get Podcast Shows endpoint: Available for podcast promotion use only (not for targeting) –
podcast shows can be retrieved via this endpoint and input under the
promotion_target_id
parameter in the Create Ad Set request
Documentation Updates
- Now that the Campaign Management API is in GA, mention of manual allowlisting process and closed beta requirements have been removed
- Versioning policy has been simplified and schedule has been updated to reflect November 6, 2023 deprecation date for v1.3-v1.4
- Filtering and Querying section has been removed
- Slicing section has been removed
- Object Hierarchy has been updated to reflect v2 changes
- Build a Campaign Guide has been updated based on new v2 specs
- Metrics Glossary has been updated to only reflect metrics included in v2
November 2022
Announcing Ads API v1.4
All of the following updates are included under a new minor version (v1.4) released on November 29, 2022.
What's New
- Introducing new Click objective with accompanying Call-to-Action (“CTA”) card format
- Spotify Ad Studio advertisers are now able to set up a click optimization goal for their campaigns along with reach and impressions goals introduced this year. Ads with click goal will be accompanied by a Call-to-Action card: a clickable ad experience consisting of an advertiser's companion image, a name and a call-to-action button. After the initial ad is served, the message will resurface across the Spotify app making it easier for listeners to remember and take action.
- New enum value
CLICKS
is available under thebid_optimization_goal
parameter when creating an ad set, updating an ad set, and retrieving bid/audience estimates - CTA cards will be enabled for music ads only (not video) – create ad endpoint now includes:
- New required parameter
brand_name
: Displayed in ad - New optional parameter
tagline
: Displayed in CTA card, max 140 characters - These two parameters are included in the response when retrieving ads
- New required parameter
- Enforcing new validation logic, see Breaking Changes/Deprecations section below for details
Breaking Changes/Deprecations
- New parameter
brand_name
is now required when creating an ad - Removed and replaced
slot_type
withformat
under ad sets/estimates targeting object - Removed
country_codes
(array of string) under ad sets/estimatestargeting
object and replaced withcountry_code
(string) - Validation rules added:
- Ad set start and end dates must be in the future
- Max ad set duration of 365 days
- Minimum length of 2 characters and maximum of 120 characters for campaigns, ad sets and ads entity names
- Only one country may be targeted per ad set
August 2022
All of the following updates are included under the current version of the API v1.3:
- New enum value
ARTIST_CONTENT
is available under theartist_promotion_goal
parameter when creating an ad set or updating an ad set: Users can now specify when they are promoting an artist's merch or concert by selecting this option (NOTE:ARTIST_BOOST
should continue to be used when promoting an artist's music on Spotify).
July 2022 - v1.3
Announcing Ads API v1.3
All of the following updates are included under a new minor version (v1.3) released July 2022.
What's New
- New minor version v1.3 released. Note: v1.1 and v1.2 will be fully deprecated on August 25, 2022. See Versioning section for version schedules.
- Addition of effective cost per mille and completed listen fields,
ECPM
andECPCL
, to reporting endpoints. See Metrics Glossary for detailed definitions. - Ad sets and Estimates requests have been updated to use an auction pricing model, see "Breaking Changes/Deprecations" below for details
frequency_caps
is no longer a required parameter for create ad sets requests; it is now optional. Iffrequency_caps
is not specified, API will default to the maximum allowed values:- 5 per day
- 35 per week
- 50 per month
Breaking Changes/Deprecations
- Addition of
bid_optimization_goal
,bid_strategy
, andbid_micro_amount
to ad sets output responses, as required fields to create ad sets requests, and as optional fields to update ad sets requests- Allowed values for
bid_optimization_goal
are:EVEN_IMPRESSION_DELIVERY
: We’ll aim to deliver as many impressions as possible to your target audience. Not available for active audio (CPCL) ad sets.REACH
: We’ll aim to reach as many unique listeners as possible with your message.AD_COMPLETES
: We’ll aim to deliver as many impressions as possible to your target audience. Available for active audio (CPCL) ad sets only.
- Allowed values for
bid_strategy
are:MAX_BID
: The bid you specify will act as a ceiling/cap.
- Allowed values for
- The following fields under the ad sets objects have been renamed:
optimization
is nowartist_promotion
optimization_goal
is nowartist_promotion_goal
optimization_target
is nowartist_promotion_target
optimization_target_type
is nowartist_promotion_target_type
- The previous
/estimate
endpoints are deprecated and replaced with two new ones (Get Bid Estimate and Get Audience Estimate) that allow users to specify bid details:POST /v1.3/adAccounts/{ad_account_id}/estimate/audience
is replacingPOST /v1.2/estimate
POST /v1.3/adAccounts/{ad_account_id}/estimate/bid
is replacingPOST /v1.2/adAccounts/{ad_account_id}/estimate/cost
Documentation Updates
- Migrated documentation to main portal Spotify for Developers
December 2021 - v1.2
Announcing Ads API v1.2
All of the following updates are included under a new minor version (v1.2) released December 2021.
What's New
- New minor version v1.2 released
- Added new pricing estimate endpoint to estimate your CPM/CLCL/CPCV based on specified targeting parameters
POST /adAccounts/{ad_account_id}/estimate/cost
- Added
custom_audience_ids
under thetargeting
parameter for ad sets- You now have the option to specify custom audiences to target when creating/updating an ad set
- Added
third_party_viewability_tracking
for ads- You now have the ability to set up third-party viewability tracking when creating/updating an ad
- NOTE: This is currently only supported for measurement partner
IAS
Breaking Changes/Deprecations
- “Flights” have been renamed “Ad Sets”
- We have renamed all instances of these entities in v1.2 in order to match the nomenclature used in the Ad Studio UI
- “Creatives” have been renamed “Ads”
- We have renamed all instances of these entities in v1.2 in order to match the nomenclature used in the Ad Studio UI
- Removed parameter “unit_cost_micro_amount” from Create Ad Set and Update Ad Set (fka Flight) endpoints
Documentation Updates
- Added new sections: “Metrics Glossary” and “Release Notes”
- Added additional detail on the expected behavior of the
report_datetime_range
filter under the Reporting API - Updates to “Versioning” section - added version release/sunset schedule
November 2021 - v1.1
- Added support for podcast ad performance data to the Reporting API
- Ads served to podcast listeners on Spotify will automatically be reflected without making any updates to your integration
- To capture the impressions served off Spotify, you will need to update your integration by adding the new metric called
OFF_SPOTIFY_IMPRESSIONS
- There are no breaking changes associated with this launch, however, we recommend that you complete this update as soon as possible in order to accurately reflect podcast ad performance
June 2019 - v1.1
Announcing Ads API v1.1
v1.1 was released June 2019
What's New
- Combined the
/geo
and/geos
endpoints into just/geos
. See docs here /geos
endpoint now allows you to specify a type of geo you are searching for as a filter in a query param.
April 2019 - v1.0
- Renamed the landing_page_url field to be landing_page_domain so it is consistent across the API
- Renamed arrays on GET targets and GET campaigns to be consistent with rest of API
- Refactored statuses on flight endpoint
- Pausing status for flight and flight links
- Previously, you had to pause a flight on the update flight request. Now, there is a separate endpoint to pause / activate / archive a flight. You are no longer able to change the status on the update flight request.
- Added Flight Links endpoints
- Flight links are a connection between flights and creatives that ensure the creative(s) and its contents are compatible with the flight’s targeting
- Added serving status endpoint
- The new serving status endpoint indicates whether your flight is serving or not
March 2019 - v1.0
- Added Campaign Status Endpoint
- The available statuses for campaigns are ACTIVE, PAUSED, and ARCHIVED
- Removed CANCELLED as a status on campaigns
- Campaigns can now only be archived, not cancelled
- Archiving will permanently pause a campaign, you cannot unarchive a campaign
- Archiving a campaign will prevent delivery across all associated flights
- Removed ability to update campaign status on PUT
- Use the campaign status endpoint
- Added support for slicing on all GET LIST requests for creatives, flights, and campaigns
- Slicing is the ability to specify what fields you want returned
- How it works: GET LIST endpoints, there is a query parameter called
fields
where you can specify a comma-separated list of fields you want returned
- Added support for filtering on all the GET LIST requests for creatives, flights, and campaigns
- Filtering is the ability to filter your results based on specific criteria (e.g., Get Flights for a specific Advertiser ID)
- How it works: On the GET LIST endpoints, there are optional query parameters to specify the filter
- Added support for ordering by a specific field on GET LIST requests for creatives, campaigns, and flights
- How it works: There are optional query parameters to specify the ordering field, ascending or descending based on the field