Version | Path | Introduction Date | Deprecated Date | End of Life Date |
---|---|---|---|---|
12.0 | /12/ | October 27, 2022 | TBD | TBD |
11.0 | /11/ | March 31, 2022 | TBD | TBD |
10.0 | /10/ | August 31, 2021 | March 31, 2022 | October 27, 2022 |
9.0 | /9/ | March 2, 2021 | August 31, 2021 | March 31, 2022 |
8.0 | /8/ | September 8, 2020 | March 2, 2021 | August 31, 2021 |
7.0 | /7/ | March 3, 2020 | September 1, 2020 | March 2, 2021 |
6.0 | /6/ | August 28, 2019 | March 3, 2020 | September 1, 2020 |
5.0 | /5/ | February 28, 2019 | August 28, 2019 | March 3, 2020 |
4.0 | /4/ | August 28, 2018 | February 28, 2019 | August 28, 2019 |
3.0 | /3/ | February 1, 2018 | August 28, 2018 | February 28, 2019 |
2.0 | /2/ | July 10, 2017 | February 1, 2018 | August 1, 2018 |
1.0 | /1/ | March 31, 2016 | July 7, 2017 | January 10, 2018 |
0.0 | /0/ | February 21, 2013 | N/A | October 31, 2016 |
x-current-api-version
which will be set to the current version of the API in addition to an x-api-warn
header when calling any deprecated API endpoints.
accounts/:account_id/account_media
endpoint have been deprecated.
As with previous versions, there will be a 6 month transition period to migrate to v5. On 2019-08-28, version 4 of the Ads API will no longer be available. We encourage all partners to migrate to the latest version of the API as soon as possible to avoid any service disruptions. Version 3 of the Ads API has reached its end of life and is no longer available.
CAMPAIGN
, FUNDING_INSTRUMENT
, LINE_ITEM
, MEDIA_CREATIVE
, and PROMOTED_TWEET
.
MEDIA_CREATIVE
stats
The Ads API’s analytics endpoints now provide metrics for Media Creative entities. Media Creatives are how in-stream ads or images on the X Audience Platform are promoted. The X Ads UI shows Media Creative metrics under the “In-stream videos” and “Display creatives” tabs. Both synchronous and asynchronous analytics endpoints now support the MEDIA_CREATIVE
entity enum.
Fetch multiple cards
Improving on the v3 release of the endpoint designed to retrieve a single card by its card URI value, it’s now possible to fetch multiple cards using the GET accounts/:account_id/cards/all endpoint. Now, rather than making a request for each card, you can retrieve up to 200 cards in a single request.
Two things to note:
accounts/:account_id/cards/all
. (The previous path is no longer available.) This is so that we’re consistent with the endpoint designed to retrieve a card by ID.draft_only
| with_draft
| |
Network activation duration targeting
The Ads API has resolved a display issue where, after adding Network Activation Duration targeting, the targeting type in the response included an _IN_SEC suffix. Having a reference to seconds was confusing as Network Activation Duration is always represented in months. This fix makes the representation consistent and reduces confusion.
| v4 | v5 |
| :--- | :--- | :--- |
| NETWORK_ACTIVATION_DURATION_IN_SEC
| NETWORK_ACTIVATION_DURATION
| |
Total counts and cursors
In v5, with_total_count and cursor are exclusive. Specifying both in a request will return the EXCLUSIVE_PARAMETERS error code. Prior to v5, with_total_count was ignored when cursorwas specified. This change makes the relationship explicit..
AMPLIFY_VIDEO
assets added to the Media Library are automatically added as Account Media asset with the PREROLL
creative type.INTERSTITIAL
) depends on the image dimensions. (For dimensions, see our Enumerations page.)list_type
parameter will be removed from the request and response on all Tailored Audiences endpoints in version 4.
Settings Endpoints
We now provide the ability for account administrators to set and update user, account, and tax settings. User settings correspond to the user-specific contact preferences for a given ads account. Using the PUT accounts/:account_id endpoint, advertisers can now update their account name and industry type. Finally, the tax settings endpoints allow advertisers in countries where a value added tax (VAT) is charged to update information such as the company name, address, VAT ID, and whether the account is owned by the advertiser or by an agency advertising on behalf of an advertiser.
lookalike_expansion
parameter on the POST accounts/:account_id/line_items and PUT accounts/:accountit/line_items/:line_item_id endpoints.
v3 | v4 |
---|---|
NARROW | DEFINED |
BALANCED | EXPANDED |
country_code
everywhere
As part of a larger effort around consistency on the Ads API, we’re renaming the parameters on the following endpoints from app_country_code
to country_code
.
preview_url
always null
As promised in the v3 announcement, all existing cards now have a card_uri
. As a result, the preview_url
value will always be null
.
As a reminder, associate a card with a Tweet using its card_uri
value. See the following example request.
$ twurl -X POST -H ads-api.x.com “/4/accounts/18ce54d4x5t/tweet?text=Version 4&card_uri=card://958225772740714496”
twurl -H ads-api.x.com "/3/accounts/18ce54d4x5t/videos"
twurl -H ads-api.x.com "/4/accounts/18ce54d4x5t/media_library?media_type=VIDEO"
as_user_id
in Tweet View
The as_user_id
parameter available on the GET accounts/:account_id/tweet/preview/:tweet_id endpoint will no longer be accepted. The preview will always be rendered as the Tweet’s author.
total_count
is now an optional response attribute. It will only be available if with_total_count
is set to true
paused
and draft_only
fields on line_items
and campaigns
request and response objects are replaced by a single entity_status
parameter
status
parameter has been renamed to text
on the POST accounts/:account_id/tweet and GET accounts/:account_id/tweet/preview endpoints
location_type
enums are now plural. COUNTRY
is now COUNTRIES
, REGION
is now REGIONS
, and so on. The one exception is that, in v2, CITY
is now METROS
, to correctly reflect the fact that the location type refers to Designated Marker Areas (DMAs) or “metros”.
display_properties
on the PUT accounts/:account_id/promoted_tweets endpoints. This value will also no longer be returned as part of the response
line_item_id
parameter on the GET accounts/:account_id/promoted_tweets endpoint has been removed
data_type
response attribute is no longer returned
card_uri
request parameter should be used in favor of appending the preview_url
to the Tweet text when associating a card with a Tweetcard_uri
param is not returned in the response (during the card creation step) then use the preview_url
card_uri
parameter.entity_status
parameter value on the POST accounts/:account_id/line_items and POST accounts/:account_id/campaigns endpoints can be set to DRAFT
in order create any new draft campaigns or line items.Draft Campaign | Draft Line Item |
---|---|
funding_instrument_id | campaign_id |
name | objective |
start_time | product_type |
placements |
entity_status
of DRAFT
to PAUSED
or ACTIVE
entity_status
of ACTIVE
.entity_status
of any campaign or line item, use the corresponding PUT endpoint.SCHEDULED
state may be edited/deleted
scheduled_at
date/time.
CUSTOM
objective is no longer supportedcampaign_daily_budget_amount_local_micro
currency
bid
objective
infinite_count
has been renamed infinite_bid_count
to avoid confusion on its purposecount
and infinite_bid_count
, these new data points will now be returned:
impressions
engagements
estimated_daily_spend_local_micro
data_type
for Tailored Audiences has been changed from tailored_audiences
to tailored_audience
in all of our resposnes.metrics
parameter with a new metric_groups
parameter. Developers simply must request which groups of metrics they would like returned for a given request.
null
values. These metrics will not count against your analytics cost limit.promoted_tweet_timeline_impressions
, promoted_tweet_search_impressions
, promoted_tweets_profile_impressions
, promoted_tweets_tpn_impressions
), these will now be exposed when requested in one of the following categories as a single metric, impressions
(this applies to all metrics):ALL_ON_TWITTER
PUBLISHER_NETWORK
impressions
metric to make matching values in our UI simplier.ALL_ON_TWITTER
and PUBLISHER_NETWORK
data, as these cannot be combined.CREDIT_CARD
funding source was available to test with. * Want to test a beta feature? You can now toggle features on/off for an account in the Sandbox environment to accommodate your testing needs.