Ads API: Hierarchy and terminology — Twitter Developers


Ads API Hierarchy and Terminology

Relevant products



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


Ads Accounts

At the top of the Twitter Ads hierarchy are ads accounts. An ads account can be managed by multiple Twitter 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, a unique alpha-numeric string.

Under each account, we store a number of 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 tweet.

Promotable Users

Each 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. But there can also be other promotable under the Furni 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.

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 Twitter Ads. These span from insertion orders that they’ve signed with Twitter to a credit card that is attached to the account.


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.

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.

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.


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 Twitter Audience Platform, or Promoted Tweets. Here’s an example Tweet that @Furni could promote and use as a creative.

Ready to build your solution?

Review the documentation to get started

  • Read Previous
  • Read Next