Ads API hierarchy and terminology

To be successful on the Ads API, it’s important to understand how entities in X Ads relate to each other. This tutorial goes over the basics of the X Ad…

To be successful on the Ads API, it’s important to understand how entities in X Ads relate to each other. This tutorial goes over the basics of the X Ads object hierarchy.

Ad Group (line items)

Ad groups, known as line items on the Ads API, exist under campaigns and are used for targeting and bidding against a set of X users. Advertisers promote posts or media (e.g., videos that are promoted as In-stream ads) by associating them with a line item. Also see Ad Group.

Account Media

A collection of creatives that have been uploaded to an ads account as account media that can include promoted video pre-roll assets, also referred to as in-stream ads, and images that can be promoted on the X Audience Platform.

Ads Accounts

At the top of the X Ads hierarchy are ads accounts. An ads account can be managed by multiple X users. @Furni, our demo furniture store, would be an example of a user who manages an ads account. We identify ads accounts by an account_id, which is a base36 alpha-numeric string.

Under each account, we store a number of entity types that can be reused across campaigns, such as tailored audiences that can be used for targeting, account media, which are videos or images, and cards, which are expanded creatives that you can add to a post.

Amplify Video

When uploading a video asset, the uploading entity can define a category for the video (e.g., Tweet Video, Tweet Gif, Tweet Image and Amplify Video). The amplify video category is required when trying to upload a video that is to be served as an in-stream advertisement. These videos require special processing to ensure that they’re servable and hence the media category of Amplify Video is required.

Analytics

Analytics metrics help partners and advertisers understand the performance of the content they promote on X. This includes information such as impressions, clicks, video views, and spend. In addition, partners and advertisers are able to get detailed metrics for various segments of the audiences they reach.

The Ads API supports two ways of retrieving detailed campaign performance metrics: synchronously and asynchronously.

With synchronous analytics requests, the requested metrics are returned in the response. The synchronous endpoint supports short time ranges and is ideal for querying real-time campaign performance.

With the asynchronous analytics endpoints, the requested metrics are available in a downloadable results file after the associated “job” has finished processing. The asynchronous endpoints support requesting metrics over a much longer time range, allows returning segmented data, and are intended for fetching much more data — ideal for generating reporting or historical backfills.

Campaigns

Each campaign that the advertiser runs must be created under an existing funding instrument. A campaign lets you define things like the name, schedule, and budget of an ad campaign. In sticking with the example of Furni, we might create a campaign called “Furni home decor”.

It’s worth noting that an ads account is limited to a max of 200 active Campaigns; this limit can be elevated by the advertiser’s account manager. A Campaign is deemed active until its end time is reached or its budget is exhausted. A paused campaign is still considered an active campaign for the purposes of campaign limits.

Cards

Cards offer a way to visually extend a Tweet to include an image, video or UI elements. The Ads API supports several card types that can be used in Tweets, which can then be promoted in campaigns.

Creatives

Advertisers can promote Tweets in campaigns that include creatives, such as images, GIFs, and video. These creatives can be associated with X cards that allow attaching rich photos, videos and media experiences to Tweets. Creatives can also be directly attached to Tweets. For example, you can include text and a video (or up to 3 images) and create a promoted Tweet.

Each line item needs to have at least one creative associated with it in order to run. Several options for creatives are available, including Promoted Accounts for gaining new followers, Media Creatives such as an image or video for line items across the TX Audience Platform, or Promoted Posts.

Funding Instruments

Also under the ads account are funding instruments, which are the different sources of funding the advertiser has set up to use with X Ads. These span from insertion orders that they’ve signed with X to a credit card that is attached to the account.

Line Items

Within a campaign, you can have one or more ad groups, also known as line items in the Ads API. Line items can be thought of as different segments of a campaign, each with its own targeting set and its own creative. Campaigns that contain multiple line items are often referred to as “ad group campaigns”.

One of the benefits of multiple line items within a single campaign is that you can create a greater variety of targeting and creative combinations.

Under our “Furni home decor” campaign, we might want to create two line items: one could be “Home buyers in San Francisco”, and the other could be “Home buyers in London”.

Up to 100 line items are allowed per campaign, and an ads account is limited to 4,000 active line items in total across all campaigns.

Mobile App Promotion (MAP)

Mobile App Promotion, or MAP, is a suite of products that enable advertisers to promote mobile apps via X These include app installs, conversions and re-engagement.

Mobile App Conversion Tracking (MACT)

X mobile app promotion measurement allows advertisers to track the success of advertising campaigns on X that are designed to drive installs or other in-app conversions. An X mobile measurement partner provides the ability for an advertiser to manage what conversions they want to track from the apps they are promoting on X. MACT Overview

Media Library

The Media Library endpoints provide the ability to manage images, GIFs, and videos for X Ads accounts. Media assets in the library can be used in posts and to create cards. They can also be reused in multiple creatives, eliminating the need to upload the same asset multiple times.

Promoted Accounts

Promoted Accounts (followers campaigns) are part of Who to Follow, which suggests accounts that people don’t currently follow and may find interesting. Promoted Accounts help introduce an even wider variety of accounts people may enjoy.

Promoted Accounts allow advertisers to promote their account and grow their audience on X. Follower campaigns are displayed in multiple locations across the X platform — including Home Timelines, Who to Follow, and search results — and this suggestion is labeled as Promoted to distinguish it from other recommended accounts.

Promotable Users

Each X Ads account can have one or more promotable users, which are users that we can promote through the ads account. Furni’s @Furni handle would be an example of a FULL promotable user under Furni’s ads account, which means we can run all types of campaigns for @Furni and their tweets. There can only be one FULL promotable user for an ad account.

Note there can also be other promotable users under an ads account. For example, if we wanted to promote @Jack’s Tweets about Furni products, he would become a retweet-only promotable user on the account which is indicated by RETWEETS_ONLY. Advertisers should contact their X account manager for information about adding reweet users to their ads account.

Promoted Video

Promoted videos are videos within Promoted Tweets that are paid for by advertisers. These appear in the Home timeline, at the top of search results on X, and elsewhere on the platform, and are clearly marked as “Promoted”.

Publisher Network

See X Audience Platform.

Scheduled Tweets

Scheduled Tweets allow an advertiser or user to create a Tweet that can be scheduled to go live at a later date. In addition to being able to create and manage these Tweets, the API allows the ability to associate these Tweets with a line item, to be promoted once the Tweet goes live. This allows advertisers to stage create native Tweets and plan their campaign creatives in advance of any key initiatives. For example, staging a Tweet creative to live immediately upon a new product announcement.

Segmentation

Segmentation allows partners and advertisers to retrieve metrics broken out particular targeting values — such as age, devices, or languages — and is only available through our asynchronous analytics endpoints. To request segmented metrics, use the segmentation_type request parameter. For more details on segmentation options, see Metrics and Segmentation.

Tailored Audience - List

Tailored audiences from lists are one of three types of Tailored Audiences, created by uploading a file containing your own user and customer data. Your lists are matched with users on X so that you can directly target them in your campaigns. Please review these restrictions.

Tailored Audience - Web

Tailored Audience from web, one of three types of Tailored Audiences, is a collection X users who have visited your website. To use Tailored Audiences from web you must have our X pixel installed on your website, or use one of our accepted tag manager partners. Please review these restrictions.

Targeting Criteria

As we mentioned previously, targeting criteria are associated with a line item. We have a variety of different targeting that you can use, from location, keywords, and gender to more granular attributes, such as user behaviors and interests. For the “Home Buyers in San Francisco” line item, we might target the “home buying” behavior along with the “San Francisco” location.

For information on the different types of targeting available, visit the Targeting Overview page on our developer site.

Twitter Object Nest (TON)

The Twitter Object Nest (TON) holds media and various assets upload via the Media Upload endpoints to be used as Creatives.

Creatives

Each line item needs to have at least one creative associated with it in order to run. Several options for creatives are available, including Promoted Accounts for gaining new followers, Media Creatives such as an image or video for line items across the X Audience Platform, or Promoted Posts. Here’s an example post that @Furni could promote and use as a creative.