Ads API Version 5

announcements

#1

Ads API Version 5

Today, February 28, 2019, Twitter introduces Ads API v5, with updates that focus on enabling scale and efficiency.

This release includes a new endpoint to determine which entities were active in a given timeframe, stats for Media Creatives (i.e., In-stream videos and images on the Twitter Audience Platform), the ability to fetch multiple cards, by card URI, and more flexibility around retrieving targeting criteria and other entities. In addition, we’ve fixed some bugs and made updates to parameter names and response attributes. Finally, non-media app cards and the POST 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.

As a reminder, the Ads API recently introduced account-level rate limits. This update works on all versions of the Ads API. Developers should adapt code to recognize and leverage account-level rate limits when available.

New

Determining which entities were active

Engineering effort: Variable

The Active Entities endpoint signifies whether analytics metrics for ads entities have changed. Designed to be used in conjunction with the analytics endpoints, Active Entities works by specifying an entity type and a date range—a maximum of 90 days—and returns an array of entity IDs that your platform should request analytics for. IDs other than the ones returned should not be queried in subsequent analytics requests.

This endpoint supports the following entity types: CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, MEDIA_CREATIVE, and PROMOTED_TWEET.

MEDIA_CREATIVE stats

Engineering effort: Minimal

The Ads API’s analytics endpoints now provide metrics for Media Creative entities. Media Creatives are how in-stream ads or images on the Twitter Audience Platform are promoted. The Twitter 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

Engineering effort: Minimal

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:

  1. The URL path is now 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.
  2. The required request parameter is now named card_uris (plural).

Flexibility around retrieving

Engineering effort: Minimal

The GET accounts/:account_id/targeting_criteria endpoint now supports multiple line item IDs. The line_item_ids parameter, which accepts up to 200 IDs, is required. Previously, only a single line item was accepted, which made syncing difficult. With this change, it’s now possible to retrieve more targeting in less time.

The following endpoints now also support multiple line item IDs, though the line_item_ids parameter is optional for these.

Changed

Retrieving draft campaigns and line items

Engineering effort: Minimal

The way that draft campaigns and line items are retrieved has been updated. Now, the with_draft (boolean) parameter, when set to true, returns both draft and non-draft entities. This is consistent with the way deleted entities are retrieved (i.e., using with_deleted). Previously, fetching both draft and non-draft entities required at least two requests. Now, this can be done in a single API call.

v4 v5
draft_only with_draft

Network activation duration targeting

Engineering effort: Minimal

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

Engineering effort: Minimal

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 cursor was specified. This change makes the relationship explicit.

Removed

Three fields are being removed from Ads API responses: preview_url, account_id, and parent_ids. The engineering level of effort for these three is minimal.

  • In v4, it was announced that the preview_url response parameter for cards was always null. The final step in this migration is to remove preview_url from all cards responses.
  • The account_id response attribute is being removed for the following resources given that the ads account ID is already present in the URL as well as in request.params. (It is intentional to exclude funding instruments from this list as parent IDs should be present in response objects, where possible, and account IDs are parent entities to funding instruments.)
    • Account media
    • App event providers
    • App event tags
    • Campaigns
    • Card
    • Line items
    • Promotable users
    • Targeting criteria
  • For GET accounts/:account_id/targeting_criteria requests, we no longer return the parent_ids field as it was always an empty array.

Finally, this version includes two deprecations. The following will not be available in v5, but will continue to work in v4. They will be sunset when v4 is shut off.

Non-media app cards

Engineering effort: Minimal

In v5, non-media app cards are no longer supported. Previously, the ability to create or edit non-media app cards was removed. Now, the remaining endpoints for this resource are being deprecated.

  • Note: This does not affect image and video app download cards.

Account Media creates

Engineering effort: Variable

The POST accounts/:account_id/account_media endpoint is no longer available in v5. Other endpoints for this resource are not affected. The reason for this change is that, when adding media to the Media Library, there are cases when those assets automatically get added as Account Media entities and trying to add an already-existing asset to the Account Media resource results in an error. This happens in the following cases.

  • AMPLIFY_VIDEO assets added to the Media Library are automatically added as Account Media asset with the PREROLL creative type.
  • Images with specific dimensions added to the Media Library are automatically added as Account Media assets. The creative type (e.g., INTERSTITIAL) depends on the image dimensions. (For dimensions, see our Enumerations page.)

As always, we welcome your feedback so that we can continue to improve the developer experience while delivering the features and functionalities that are impactful for your business.

Twitter Ads API team


Stats for media creatives
Understanding rate limits for the campaign stats API
Analytics V1 - Metrics for Promoted Video on Video Views Pre-roll Campaigns
Stats for PRODUCT_TYPE : MEDIA
Twitter VIT APP errors
closed #2

pinned #3