Advertiser API

Programatically schedule campaigns and manage ads on X through this suite of APIs.

What Can You Promote?

  • Promoted Ads are ordinary ads purchased by advertisers who want to reach a wider group of users or to spark engagement from their existing followers.
  • Promoted Ads are clearly labeled as Promoted when an advertiser is paying for their placement on X. In every other respect, Promoted Ads act just like regular ads and can be reposted, replied to, liked and more. They have typical delivery rules and are created using POST statuses/update.
  • “Promoted-only” Tweets, created via POST accounts/:account_id/tweet, can be used in Promoted Tweets campaigns but will not serve to followers or appear on the public timeline. To retrieve a list of promoted-only tweets for a certain account, use GET accounts/:account_id/scoped_timeline.
  • Promoted Accounts 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 for Timeline, associate a Promoted Tweet with a Promoted Account campaign and will display in user timelines.

Promoted Trends are not available in the Ads API.

Campaigns and Ad Groups (Line Items)

Campaigns define the schedule and budget of an ad. The advertiser specifies a daily and overall budget. The campaign can be bound to a specific start and end time or run continuously until the budget is spent. The budget comes from one of the Funding Instruments of the advertising account. Campaign identifiers (:campaign_id) are the base-36 representation of the base-10 value we present in the X Ads UI.

Advertising accounts are limited to a maximum of 200 active campaigns. This limit can be raised to 4,000 active campaigns manually by the advertiser’s X Account Manager upon request. A campaign is considered active until it reaches its end time or gets deleted. Paused campaigns are considered active until their designated end times.

Line items spend the budget defined by a campaign. Line items pull together the per-engagement bid, the Tweet or account to promote, and the targeting rules.

Analytics

The X Ads API offers a set of analytics endpoints to track and optimize ad performance. Please see Analytics and Analytics Best Practices for more information.

For the billing metric, the data may not be finalized until three days after the event. Before that point, the data should be considered speculative. The final billable number will always be less than the speculative amount. The billable number is corrected for spam and related low-quality traffic. See Timezones for other considerations regarding time.

Creating a Campaign - Step-by-Step

The following example assumes you have installed, configured, and authorized your app and user using twurl. twurl is a command-line tool in the spirit of cURL that gracefully handles X OAuth authentication. twurl is a great tool for quickly testing and debugging Ads API (and REST API) functionality. To see the full headers of the request and response, use -t to trace the call, roughly equivalent to cURL’s -v option.

For this example, we will create a Promoted Ads campaign that will be targeted by keyword.

  1. Retrieve the account id.
twurl -H ads-api.x.com /9/accounts/
{
  "request": {
    "params": {
    }
  },
  "data": [
    {
      "name": "Test account for @AdsAPI",
      "timezone": "America/Los_Angeles",
      "timezone_switch_at": null,
      "id": "xxxxxx",
      "created_at": "2014-03-09T00:41:49Z",
      "salt": "f9f9d5a5f23075c618da5eb1d1a9df57",
      "updated_at": "2015-01-29T00:41:49Z",
      "approval_status": "ACCEPTED",
      "deleted": false
    }
  ],
  "data_type": "account",
  "total_count": 1,
  "next_cursor": null
}
  1. Retrieve the funding instrument id.

Hit the GET accounts/:account_id/funding_instruments API using the account id retrieved in the previous command.

twurl -H ads-api.x.com /9/accounts/xxxxxx/funding_instruments
{
  "data": [
    {
      "cancelled": true,
      "created_at": "2014-03-09T00:41:49Z",
      "credit_limit_local_micro": null,
      "currency": "USD",
      "deleted": false,
      "description": null,
      "end_time": null,
      "funded_amount_local_micro": null,
      "id": "yyyy",
      "type": null,
      "updated_at": "2014-05-29T00:41:49Z"
    }
  ],
  "data_type": "funding_instrument",
  "next_cursor": null,
  "request": {
    "params": {
      "account_id": "xxxxxx"
    }
  },
  "total_count": 1
}
  1. Create a campaign and associate it with the funding instrument.

Specify a start time and a budget for the campaign. For the purpose of this example, we will use a budget of $500 and for the daily limit, $50.

twurl -H ads-api.x.com -d "funding_instrument_id=yyyy&name=My First Campaign&total_budget_amount_local_micro=500000000&daily_budget_amount_local_micro=50000000" /9/accounts/xxxxxx/campaigns
{
  "data": {
    "created_at": "2015-02-09T00:00:00Z",
    "currency": "USD",
    "daily_budget_amount_local_micro": 50000000,
    "deleted": false,
    "end_time": null,
    "funding_instrument_id": "yyyy",
    "id": "92ph",
    "name": "My First Campaign",
    "entity_status": "PAUSED",
    "standard_delivery": true,
    "total_budget_amount_local_micro": 500000000,
    "updated_at": "2015-02-09T00:00:00Z"
  },
  "data_type": "campaign",
  "request": {
    "params": {
      "account_id": "xxxxxx",
      "daily_budget_amount_local_micro": 50000000,
      "funding_instrument_id": "yyyy",
      "name": "My First Campaign",
      "total_budget_amount_local_micro": 500000000
    }
  }
}
  1. Create a line item associated with the campaign.

Now that we have a campaign id, we can create a line item to associate with it. The line item wraps the bid price, targeting, and actual creative portion of the campaign. For this line item, we will be promoting tweets with a bid of $1.50.

twurl -H ads-api.x.com -d "campaign_id=XXXX&bid_amount_local_micro=1500000&product_type=PROMOTED_TWEETS&placements=ALL_ON_TWITTER&objective=ENGAGEMENTS&entity_status=PAUSED" /9/accounts/xxxxxxx/line_items
{
  "data_type": "line_item",
  "data": {
    "bid_type": "MAX",
    "name": "Untitled",
    "placements": [
      "ALL_ON_TWITTER"
    ],
    "bid_amount_local_micro": 1500000,
    "automatically_select_bid": false,
    "advertiser_domain": null,
    "primary_web_event_tag": null,
    "charge_by": "ENGAGEMENT",
    "product_type": "PROMOTED_TWEETS",
    "bid_unit": "ENGAGEMENT",
    "total_budget_amount_local_micro": null,
    "objective": "ENGAGEMENTS",
    "id": "azjx",
    "entity_status": "PAUSED",
    "optimization": "DEFAULT",
    "categories": [],
    "currency": "USD",
    "created_at": "2015-02-09T00:00:00Z",
    "updated_at": "2015-02-09T00:00:00Z",
    "include_sentiment": "POSITIVE_ONLY",
    "campaign_id": "92ph",
    "deleted": false
  },
  "request": {
    "params": {
      "placements": [
        "ALL_ON_TWITTER"
      ],
      "bid_amount_local_micro": 1500000,
      "product_type": "PROMOTED_TWEETS",
      "entity_status": "PAUSED",
      "account_id": "xxxxxxx",
      "campaign_id": "92ph"
    }
  }
}
  1. Create a targeting profile associated with the line item.

With the line item created, we can assign targeting criteria. We want to target the phrase keywords “grumpy cat” in the San Francisco Bay Area location. This is going to require a location id lookup and two targeting_criteria POST requests.

twurl -H ads-api.x.com "/9/targeting_criteria/locations?location_type=CITIES&q=San Francisco"
{
  "data": [
    {
      "name": "San Francisco-Oakland-San Jose CA, US",
      "targeting_type": "LOCATION",
      "targeting_value": "5122804691e5fecc"
    }
  ],
  "data_type": "targeting_criterion",
  "request": {
    "params": {
      "location_type": "CITY",
      "q": "San Francisco"
    }
  }
}
twurl -H ads-api.x.com -X POST -d "line_item_id=yyyy&targeting_type=LOCATION&targeting_value=5122804691e5fecc" /9/accounts/xxxxxx/targeting_criteria
{
  "data": {
    "created_at": "2015-02-09T00:00:15Z",
    "deleted": false,
    "id": "2u3be",
    "line_item_id": "yyyy",
    "name": "San Francisco-Oakland-San Jose CA, US",
    "targeting_type": "LOCATION",
    "targeting_value": "5122804691e5fecc",
    "updated_at": "2013-05-30T21:01:35Z"
  },
  "data_type": "targeting_criterion",
  "request": {
    "params": {
      "account_id": "xxxxxx",
      "line_item_id": "yyyy",
      "targeting_type": "LOCATION",
      "targeting_value": "5122804691e5fecc"
    }
  }
}
twurl -H ads-api.x.com -X POST -d "line_item_id=yyyy&targeting_type=PHRASE_KEYWORD&targeting_value=grumpy cat" /9/accounts/xxxxxx/targeting_criteria
{
  "data": {
    "created_at": "2015-02-09T00:00:20Z",
    "deleted": false,
    "id": "2u3bd",
    "line_item_id": "yyyy",
    "name": "grumpy cat",
    "targeting_type": "PHRASE_KEYWORD",
    "targeting_value": "grumpy cat",
    "updated_at": "2013-05-30T18:05:35Z"
  },
  "data_type": "targeting_criterion",
  "request": {
    "params": {
      "account_id": "xxxxxx",
      "line_item_id": "yyyy",
      "targeting_type": "PHRASE_KEYWORD",
      "targeting_value": "grumpy cat"
    }
  }
}
  1. Finally, un-pause the line item.
twurl -H ads-api.x.com -X PUT "/9/accounts/xxxxxx/line_items/yyyy/?entity_status=ACTIVE"
{
  "data_type": "line_item",
  "data": {
    "bid_type": "MAX",
    "name": "grumpy cat",
    "placements": [],
    "bid_amount_local_micro": 1500000,
    "automatically_select_bid": false,
    "advertiser_domain": null,
    "primary_web_event_tag": null,
    "charge_by": "ENGAGEMENT",
    "product_type": "PROMOTED_TWEETS",
    "bid_unit": "ENGAGEMENT",
    "total_budget_amount_local_micro": null,
    "objective": "ENGAGEMENTS",
    "id": "yyyy",
    "entity_status": "ACTIVE",
    "optimization": "DEFAULT",
    "categories": [],
    "currency": "USD",
    "created_at": "2015-02-09T00:00:20Z",
    "updated_at": "2015-02-09T00:00:20Z",
    "include_sentiment": "POSITIVE_ONLY",
    "campaign_id": "dy1f",
    "deleted": false
  },
  "request": {
    "params": {
      "line_item_id": "yyyy",
      "entity_status": "ACTIVE",
      "account_id": "xxxxxx"
    }
  }
}

That’s it! We now have an active, targeted, and funded Promoted Tweets in Timelines campaign which is running.

Objective Based Campaigns

Objective-based campaigns and pricing allow advertisers to pay for the actions that are aligned with their marketing objectives. To support these, set the appropriate objective on line items.

The parameter used on the line item write endpoints and returned on the read endpoints, is objective. This field has the following possible values as of today:

  • APP_ENGAGEMENTS
  • APP_INSTALLS
  • FOLLOWERS
  • ENGAGEMENTS
  • REACH
  • VIDEO_VIEWS
  • PREROLL_VIEWS
  • WEBSITE_CLICKS

Objectives impact how we optimize campaigns in our auctions and how we bill on those campaigns. We enable pricing based on objective, such as CPAC for APP_ENGAGEMENTS, CPAC or CPI for APP_INSTALLS, CPLC for WEBSITE_CLICKS, CPF for FOLLOWERS, CPE for ENGAGEMENTS, and CPM for REACH.

Mobile app promotion campaigns are required to contain either the APP_ENGAGEMENTS or APP_INSTALLS objective.

Note: Line items with different objectives are not allowed under the same campaign.

Campaign objectiveAPI objectiveMedia in TweetsPricing model
App re-engagementsAPP_ENGAGEMENTSImage or video app download card required.CPAC
App installsAPP_INSTALLSImage or video app download card required.CPAC or CPI (set using charge_by)
ReachREACHNo restrictions.CPM
FollowersFOLLOWERSTweet not required, but recommended. There are no media restrictions on Tweets for Followers campaigns, though we recommend text-only Tweets. More informationCPF
EngagementsENGAGEMENTSNo restrictions.CPE
Video ViewsVIDEO_VIEWSVideo conversation card, video, or GIF required.CPV or cost per 3s/100% view
Pre-roll viewsPREROLL_VIEWSVideo required.CPV or cost per 3s/100% view
Website ClicksWEBSITE_CLICKSWebsite card recommended, but not required. Tweet must have either a website card or a website link (not both).CPLC

Funding Instruments

Funding Instruments are the source of campaign budget. Funding Instruments can not be created via the Ads API, they have to be already established by the advertiser’s account manager at X (for credit lines) or via ads.x.com (for credit cards) to be available.

To get a list of all funding_instruments on an account, see GET accounts/:account_id/funding_instruments and GET accounts/:account_id/funding_instruments/:funding_instrument_id for the details of a specific one.

Funding Instrument Attributes

Descriptive: account_id, funding instrument id, funding instrument typedescription, and io_header(insertion order header ID). Note that a single io_header may be associated with multiple funding instruments.

Funding ability: able_to_fund and reasons_not_able_to_fund.

Time: created_atupdated_atstart_time, and end_time represented by a string, formatted as “%Y-%m-%dT%l:%M:%S%z”.

Boolean status: pauseddeleted, and cancelled (true or false).

Financial: currency (ISO-4217 format), credit_limit_local_microcredit_remaining_local_micro, and funded_amount_local_micro. The value of a currency is represented in micros. For USD, $5.50 is encoded as 5.50*1e6, or 5,500,000. To represent a “whole value”, you need to multiply the local micro by 1e6 (1_000_000) for all currencies.

Attribute Details

credit_limit_local_micro is only valid for CREDIT_CARD or CREDIT_LINE type funding instruments and represents the credit limit for that instrument.

funded_amount_local_micro is only valid for INSERTION_ORDER type funding instruments and represents the allocated budget.

credit_remaining_local_micro is valid for CREDIT_LINE and AGENCY_CREDIT_LINE type funding instruments. It represents the credit_limit_local_micro minus the amount already spent on that funding instrument. It does not represent the difference between funded_amount_local_micro and the amount spent. We draw a distinction between credit limit and funded amount because they represent different underlying funding methods and spending agreements we have with advertisers.

Types of Funding Instruments

Credit Cards

Typically used by self-serve advertisers (without an account manager).

Credit Lines

These are in the form of insertion orders (IOs) and are set by account managers.

Multi-Handle Credit Lines

Advertisers can fund campaigns across multiple handles with this type of credit line. This feature is enabled by their X Account Manager, associating the different @handles to a specific credit line.

For example, @NikeSB and @NikeFuel can both have access to the @Nike credit line. This funding instrument is available just like any other. You retrieve the data by submitting a GET request to the funding_instrument endpoint. Here is a sample response (note the CREDIT_LINE type).

GET https://ads-api.x.com/5/accounts/a0b1c3/funding_instruments

{
"request": {
  "params": {
      "account_id": "a0b1c3"
  }
},
"data": [
  {
      "start_time": "2013-05-30T04:00:00Z",
      "description": "FakeNike - Credit Line",
      "credit_limit_local_micro": 150000000000,
      "end_time": null,
      "cancelled": false,
      "id": "i1234",
      "paused": false,
      "account_id": "a0b1c3",
      "reasons_not_able_to_fund": [],
      "io_header": null,
      "currency": "USD",
      "funded_amount_local_micro": 0,
      "created_at": "2013-05-30T18:16:38Z",
      "type": "CREDIT_LINE",
      "able_to_fund": true,
      "updated_at": "2013-05-30T18:16:38Z",
      "credit_remaining_local_micro": 123661919751,
      "deleted": false,
  }
],
"data_type": "funding_instrument",
"total_count": 1,
"next_cursor": null
}

The only thing particular about this funding instrument is the type and the fact that it is available to all the accounts that were associated to it. Of course, the remaining credit is impacted by all campaigns funded by this instrument, across all accounts sharing it. The details of what accounts are associated to a specific credit line are not available via the API (nor via ads.x.com).

For more information on Funding Instrument enumerations, please click here.

Targeting

Targeting is a core concept of the Ads API. Targeting is set at the line item level and options vary across placements. To set new targeting criteria you need to use POST accounts/:account_id/targeting_criteria and PUT accounts/:account_id/targeting_criteria to update them.

Use GET accounts/:account_id/line_items for a list of all line items and GET  accounts/:account_id/line_items/:line_item_id to retrieve a specific line item.

Targeting options by placement

Promoted Tweets and Promoted Accounts products can be made available on a variety of placements. Promoted Trends (PTr) are not available via the API.

For possible placement combinations, refer to the GET line_items/placements endpoint. Each placement has different options for targeting. Location, Platform and Gender are available for all. The other options are contextual to the type of placement.

  • X Search: Age Targeting, Devices, Events, Gender, Keyword Types (All), Language, Locations, Network Activation, Network Operators, Platform, Platform Version, Tailored Audiences, WiFi Only
  • X Timeline: Age Targeting, Devices, Events, Followers Of, Similar to Followers Of, Gender, Interest, Language, Locations, Network Activation, Network Operators, Non-exact Keyword Types, Partner Audience Types, Platform, Platform Version, Retargeting Types, Tailored Audiences, TV Targeting Types, WiFi Only
  • X Profiles & Tweet Details: Age Targeting, Devices, Events, Followers Of, Similar to Followers Of, Gender, Interest, Language, Locations, Network Activation, Network Operators, Non-exact Keyword Types, Partner Audience Types, Platform, Platform Version, Retargeting Types, Tailored Audiences, TV Targeting Types, WiFi Only

Understanding targeting types

Age Targeting: Target users based on specific age buckets. A list of age bucket enums can be found on the Enumerations page.

Events: Specify an event for targeting. Only one event can be used for targeting (per line item). Use the GET targeting_criteria/events endpoint to find events available for targeting.

Gender: Target males (1) or females (2). Leave null to target all.

Installed App Store Categories: use this targeting type to target users based on the categories of apps they have installed or have indicated interest in. See GET targeting_criteria/app_store_categories.

Interests: Target users by interest. Get the interests list from GET targeting_criteria/interests. You can target up to 100 interests.

Followers Of: Target the followers of any fully promotable users for the current account (note, currently the primary account holder is the only fully-promotable user of that account). GET accounts/:account_id/promotable_users to get a list of promotable users.

Similar to Followers Of: Target people with the same interests as followers of specific users. You can use up to 100 Users.

Locations: Specify up to 2,000 locations to target. Get list from GET targeting_criteria/locations. There are additional requirements for ads that target certain countries. See Country Targeting and Display Requirements for more information.

Keywords: Keyword targeting options are specific by type of placement. You can use up to 1000 keywords for targeting (per line item). See the Keyword Types section for options.

Language Targeting: Target users who understand specific languages.

Mobile Network Operator Targeting: Enables advertisers to target users based on mobile carrier, using the targeting type NETWORK_OPERATOR from GET targeting_criteria/network_operators.

New Mobile Device Targeting: Reach users based on the date that they first accessed X via their device, using the targeting type NETWORK_ACTIVATION_DURATION using operator_type of LT for less than and  GTE for greater than or equal.

Platforms, Platform Versions, Devices, and Wifi-Only: Allows targeting of mobile devices across a variety of vectors. Platforms is a high-level targeting type that can hit broad categories of phone. Example values are iOS and Android. Devices allow you to target users of specific mobile devices, for example the iPhone 5s, Nexus 4, or Samsung Galaxy Note. Platform versions allow you to target users of versions of specific mobile operating systems, down to the point release. Examples include iOS 7.1 and Android 4.4. Wifi-Only allows you to target only those users who are using their devices on a WiFi network; if this is not set, users using the carrier connection as well as WiFi will be targeted.

  • Users can target platforms and devices if there is no overlap. I can target Blackberry as a platform and iPad Air as a device simultaneously.
  • Users can target devices and os versions simultaneously. I can target iPad Air and iOS >= 7.0.
  • Users cannot target platforms that are broader than devices. I cannot target iOS and iPad Air.

[Tailored Audiences]/x-ads-api/audiences: Reach users through an approved ads partner to target groups of customers and connect with them on X.

TV Targeting

TV Show Targeting: reach people that engage with specific TV programs. This targeting criteria can be configured to continuously target while a campaign is active with the TV_SHOW targeting type. Use the GET targeting_criteria/tv_markets and GET targeting_criteria/tv_shows endpoints to determine TV shows available.

Tweet Engager Retargeting

Tweet engager retargeting enables advertisers to target audiences across devices who have previously been exposed to or engaged with their promoted or organic Tweets on X. With this targeting advertisers can follow up with people who saw or engaged with an advertiser’s content on X and are most likely to further engage or convert with subsequent messaging or offers. Users will be eligible for targeting within minutes of exposure or engagement and will remain eligible for up to 90 days afterwards for engagements and 30 days for exposures.

Tweet Engager Targeting Types:

  • ENGAGEMENT_TYPE which accepts either IMPRESSION or ENGAGEMENT as a targeting value. This specifies whether you wish to target exposed users (IMPRESSION) or engaged users (ENGAGEMENT).
  • CAMPAIGN_ENGAGEMENT uses a campaign ID as the targeting value. Users who engaged with or were exposed to this campaign (depending on ENGAGEMENT_TYPE) are the ones who will be targeted.
  • USER_ENGAGEMENT which uses the promoted user ID as the targeting value to target users who were exposed to or engaged with an advertiser’s organic content (depending on ENGAGEMENT_TYPE). This must be the promoted user ID associated with the Ads account.

Note: ENGAGEMENT_TYPE is required in addition to at least one valid CAMPAIGN_ENGAGEMENT or USER_ENGAGEMENT value. Both tweet engager targeting types may be present and multiple campaigns may be targeted on a given line item.

Video Viewer Targeting: Video viewer targeting builds on Tweet engager targeting to enable advertisers to target audiences who have previously watched part or all of a video on X. Advertisers can target organic videos, promoted videos, or both. Promoted videos are not limited to video view objective campaigns or line items.

Video Viewer Targeting Types:

  • VIDEO_VIEW for users who have clicked to play the video or have viewed 3 seconds of autoplay
  • VIDEO_VIEW_PARTIAL for users who have viewed 50% of the video
  • VIDEO_VIEW_COMPLETE for users who have viewed at least 95% of the video

As with Tweet engager targeting, one or both of the following must also be present in targeting criteria for the line item when ENGAGEMENT_TYPE is used:

  • CAMPAIGN_ENGAGEMENT uses a campaign ID as the targeting value. Users who watched a video (based on ENGAGEMENT_TYPE) in this campaign are the ones who will be targeted.
  • USER_ENGAGEMENT which uses the promoted user ID as the targeting value to target users who watched a video (based on ENGAGEMENT_TYPE) in an advertiser’s organic content. This must be the promoted user ID associated with the Ads account.

Keyword Types

See our support document on keyword targeting for a conceptual overview.

  • Broad (default value): match all words, independent of order. Not sensitive to capitalization, plurals or tense. Will automatically be expanded when possible (i.e. “car repair” would also match “automobile fix”). If you want to target without expansion, you need to add a + sign before the keywords, like “+boat +jet”. Using keywords without the + will default to Broad Match.
  • Unordered (deprecated): match all words, independent of order. Not sensitive to capitalization, plurals or tense.
  • Phrase: match the exact keywords string, other keywords can be present.
  • Exact: match exactly the keywords string, not any others.
  • Negative: avoid matching searches that include all of these keywords somewhere in the query, regardless of the order in which they are written, even if other words are present.
  • Negative Phrase: avoid matching searches that include this exact keywords string somewhere in the query, even if other words are present.
  • Negative Exact: avoid matching searches that exactly match these keywords and contain no other words.  

Emoji targeting

Emoji targeting is supported via keyword targeting. To use emoji targeting, simply create keyword targeting for Unicode codepoints representing that emoji such as U+1F602 (xF0x9Fx98x82 in UTF-8) for the ‘face with tears of joy’ emoji (😂). Emoji which we accept can be confirmed with the twemoji list. Targeting an emoji targets all variations.

For a summary of all values with required/optional and specific details for each, see PUT accounts/:account_id/targeting_criteria.

Targeting Criteria Combinations

Updated Campaign Workflow

Create campaigns which target broadly with geo, gender, language, and device/platform criteria. Advertisers can then combine the broad targeting with additional targeting criteria (e.g. interests, keywords, followers, tailored audiences, TV). If no targeting criteria is specified for a line item, the line item will target all users worldwide.

“Primary” TypesOther Types
FollowersLocations
Tailored AudiencesGender
InterestsLanguages
KeywordsDevices and platforms
TVAge

Targeting criteria will be combined for your ad group such that:

  • “Primary” Targeting Types will get ‘d (i.e. put in a logical union).
  • Other Targeting Types will get AND‘d.
  • Same types will get OR‘d.

Some examples

At a glance: [(Followers) ∪ (Tailored Audiences) ∪ (Interests) ∪ (Keywords)] AND (Location) AND (Gender) AND (Languages) AND (Devices and Platforms)

A Geo example:

Let’s say we want an ad group for our campaign to serve targeting:

  • X users in the U.S., England, and Canada (Location)
  • who are Women (Gender)
  • derived from Tailored Audiences list (“Primary”)
  • with Keywords (“Primary”)

The targeting criteria will be:

[US OR GB OR CA] AND [Female] AND [Tailored AudiencesKeyword]

Additional examples

  • Select Gender and Geo but no primary: (Male) AND (US OR GB)
  • Select Gender, Geo, Interest: (Female) AND (CA) AND (Computers OR Technology OR Startups)
  • Select Gender, Geo, Interest, Tailored Audiences, Keywords: (Male) AND (GB) AND (CarsTailored Audiences for CRMautocross)

Budget Pacing

Advertisers now have more control over how fast their daily budgets are spent on your Promoted Tweet and Account campaigns. Enabling standard delivery, which is the default, ensures an even spend rate throughout the day.

By turning off standard delivery, we will serve impressions and generate engagements as quickly as possible until your daily budget is exhausted, which may be quite early on in the day depending on targeting and competition. This is called accelerated delivery.

Getting Started

Standard delivery is the default option for all campaigns, so no action is required unless you wish to turn it off. To spend through your daily budget on a campaign as fast as possible set the standard_delivery parameter to false to set the pace to accelerated delivery (see GET accounts/:account_id/campaigns).

Notes

  • “Day” is respective to X advertiser account timezone (eg. America/Los_Angeles).
  • Early results indicate that standard delivery will improve eCPE/CPF for advertisers, with more consistent coverage throughout the day.

For more additional information about budgets and pacing please see the Bidding and Auctions FAQ.

Target Bidding

Campaign management

Bid Strategy

We have introduced the concept of Bid Strategy to simplify campaign creation workflow and reduce confusion about combinations of multiple parameters.

All previous (marked as legacy) combinations of parameters can be achieved by setting an equivalent goal parameter. Further information can be found in the announcement here.

As example:

Campaign ObjectiveLegacyAds API v10+
App Installsbid_type= AUTO

bid_unit = APP_INSTALLS

charge_by = APP_CLICKS
goal = APP_INSTALLS

bid_strategy = AUTO
Website Clicksbid_type = TARGET (Note: bid_unit was not needed for some campaign objectives)bid_strategy = TARGET

Target Bidding

Using target bidding, you can specify a target cost you want to pay and the X Ads platform will optimize your campaign for performance while staying near or below your target cost.

This feature gives you the flexibility to reach users who are especially likely to take the desired action (such as a link click, a lead or a follow) while maintaining cost control. This is a powerful feature for advertisers who desire more options for campaign setup and optimization (including bidding options).

For line items with compatible campaign objectives, we’ve introduced a new pricing mechanism for bid amount that lets you specify a target cost you want to pay. Our ad platform dynamically bids on your behalf to help you drive more results, while working to keep your average cost within 20% of your specified target. The bid_strategy setting on line items may be set with a value of TARGET to enable target bidding on relevant campaign objectives, such as:

  • WEBSITE_CLICKS
  • WEBSITE_CONVERSIONS 
  • APP_INSTALLS 
  • APP_ENGAGEMENTS
  • REACH

Country Targeting and Display Requirements

Campaign management

Country-specific targeting and display requirements are contained on this page. These requirements must be adhered to by all partners.

Russia

X’s Ads Policies prohibit advertisers from targeting Russia with advertisements that are not in the Russian language. When your users specifically target Russia, you must display the following warning message to your users:

Ads targeting Russia must be in the Russian language.

Partner Managed Funding Instruments

The onboarding flow configures an ads.x.com account for the X account, which can be managed by the partner through the Ads API, and whose advertising spend is billed to the partner.  

Partner Initial Set-up

The process to initially set-up a new PMFI Ads API partner takes up to 3-weeks from exchange of required information. The following must be shared with your technical contacts at X, as well as the X contact managing the integration with the partner in order to get the process started:

  • The partner must share their PGP/GPG public key. A shared secret key needs to be exchanged between the Ads API partner and X. This will be used to verify data during the onboarding flow.
  • The app_id or consumer_secret for the X app that will be used for Ads API access. You can view and edit your existing X apps via the app dashboard if you are logged into your X account on developer.x.com. If you need to create a X app, you will need to have an approved developer account. X allows one app for production+sandbox and one optional app for sandbox-only access. The X app must be created on a corporate, partner-controlled X handle.  

Advertiser Onboarding Flow

The advertiser onboarding flow occurs via a web browser in the following way:

  1. The user starts the onboarding flow on the partner’s website and enters the handle they want to onboard.
  2. The partner redirects the user to a URL on ads.x.com with a signed payload. This payload contains the partner’s API app_id, the X user_id of the X handle which is to be onboarded and a callback URL and other fields documented below.
  3. The user is asked to sign into ads.x.com using the standard x.com login page.
  4. Once the user is logged in, the onboarding process is initiated. This step includes ad review, account validation and other checks.
  5. When all onboarding tasks are completed, the user is redirected to the callback URL that was provided by the Ads API partner, with a payload that indicates success or failure. This includes the 3-legged authorization process.  

Onboarding redirect payload

URL for redirect:

https://ads.x.com/link\_managed\_account

The redirect URL will be called with the following parameters:

NameTypeDescription
callback_urlURL encoded stringuser will be redirected to this url after the account link process completes, regardless of outcome. See the partner redirect url section for protocol details
client_app_idintegerX API client app id, used to identify the managing partner
promotable_user_idintegerX user_id of the @handle whose promotions are to be managed by the managing partner. Used to make sure it is the same as the user who logs into ads.x.com to complete the linking process
fi_descriptionURL encoded String (max 255 characters)funding instrument name. This will be displayed in the description field in the API when the funding instrument is retrieved. If a funding_instrument description is given, the existing funding_instrument will be paused, and a new managed partner funding instrument will be set up. (if one exists with the same name, nothing will happen)
timezoneString, in Area/Location formatThis will be the timezone used to determine the day to which daily budgets apply, and in which charges will be aggregated
currencyISO 4217 Currency CodeCurrency that will be used to enter bids, and in which charges will be billed
countryISO 3166-1 alpha 2 Country CodeBilling Country for the account
signatureURL encoded, base64 encoded binary code, as explained belowsignature that combines a shared secret and the other parameters to verify authenticity of the call, as well as validity of the parameters.

Callback URL payload

The base redirect URL is provided using the callback_url parameter on the account link request (see above). The parameters added by ads.x.com are:

NameTypeDescription
statusstringOK an account was created, or an existing, eligible account was found.

ACCOUNT_INELIGIBLE if partner specific constraints are not met USER_MISMATCH the X account used to sign into ads.x.com was different from the promotable_user_id on the account link request INCOMPLETE_SERVING_BILLING_INFO timezone, currency or country were not specified INVALID_COUNTRY an invalid country value was given INVALID_CURRENCY an invalid currency value was given INVALID_TIMEZONE an invalid timezone value was given
account_idURL encoded stringX ads account id of the linked account
funding_instrument_idURL encoded stringID of the active partner managed funding instrument
signatureURL encoded, base64 encoded binary code, as explained belowBase64 encoded HMAC-SHA1 signature that combines a shared secret and the other parameters to verify authenticity of the call, as well as validity of the parameters. To make sure the callback url is only valid for the X user_id that the account link process was intended for, the X user_id is to be appended to the shared secret (using &) when signing the request.

To make sure the callback URL is only valid for the X user_id that the account link process was intended for, the X user_id is to be appended to the shared secret (using &) when signing the request.  

Signing the request and callback URLs

In order to ensure that the requests to /link_managed_account and the callback url are valid, the requests need to be signed at the source and verified by the recipient before the recipient takes action on them. Signing the request with a secret that is shared between X and the managing partner ensures that each party only accepts requests sent by the authorized counterpart.

The signature generation algorithm is similar to the one used in OAuth.

Create a signature base string as follows:

  • Convert the HTTP Method to uppercase and set the base string equal to this value.
  • Append the ‘&’ character to the base string.
  • Percent encode the URL (without parameters) and append it to the base string.
  • Append the ‘&’ character to the base string.
  • Append the percent encoded query string, which is built as follows:
  • Percent encode every key and value that will be signed.
  • Sort the list of parameters alphabetically by key.
  • For each key/value pair (and with primary_promotable_user_id for the partner redirect url):
  • Append the percent encoded key to the query string.
  • Append the ‘=’ character to the base string.
  • Append the percent encoded value to the query string.
  • Separate the percent encoded key=value pairs with the ‘&’ character.
  • Use the HMAC-SHA1 algorithm, using the previously exchanged shared secret, as the key, and the base string as the value to generate the signature.
  • Base64 encode the output of Step 2, drop the trailing newline character percent encode the signature generated in Step 3 and add it to the url in a signature parameter  

Signing examples

Signing a link account request

Url to sign, assuming a GET request:

https://ads.x.com/link\_managed\_account?callback\_url=https%3A%2F%2Fmanagingpartner.com%2Flink\_account\_callback&client\_app\_id=12345&fi\_description=some%20name&promotable\_user\_id=1

This url has the following parameters:

callback_url = https://managingpartner.com/link\_account_callback client_app_id = 12345 fi_description = some name promotable_user_id = 1

The base string consisting of http method and url without parameters, steps a - d, looks like:

GET https://ads.x.com/link\_managed\_account

The query string, produced by the substeps of e, looks like:

callback_url=https://managingpartner.com/link\_account\_callback&client\_app\_id=12345&fi\_description=some name&promotable_user_id=1

Note that the key-value pairs are sorted by key name.

The percent encoded query string looks like:

callback_url%3Dhttps%253A%252F%252Fmanagingpartner.com%252Flink_account_callback%26client_app_id%3D12345%26fi_description%3Dsome%2520name%26promotable_user_id%3D1

The complete base string, combining steps a - d and e:

GET https://ads.x.com/link\_managed\_account&callback\_url%3Dhttps%253A%252F%252Fmanagingpartner.com%252Flink\_account\_callback%26client\_app\_id%3D12345%26fi\_description%3Dsome%2520name%26promotable\_user\_id%3D1

Using the hmac-sha1 algorithm we will sign this with the word “secret” as the key. The result is Base64 encoded, and presented without the final “\n” (steps 2 and 3): KBxQMMSpKRrtg9aw3qxK4fTXvUc=

This signature is then added (percent encoded) to the end of the original url in the signature parameter (step 4):

https://ads.x.com/link\_managed\_account?callback\_url=https%3A%2F%2Fmanagingpartner.com%2Flink\_account\_callback&client\_app\_id=12345&fi\_description=some%20name&promotable\_user\_id=1&signature=KBxQMMSpKRrtg9aw3qxK4fTXvUc%3D

Signing a partner redirect url (account link request callback) The URL to sign, assuming a GET request:

https://managingpartner.com/link\_account\_callback?status=OK&account\_id=ABC&funding\_instrument_id=DEF

This url has the following parameters:

account_id = ABC, funding_instrument_id = DEF and status = OK

The base string consisting of http method and url without parameters, steps a - d, looks like:

GET https%3A%2F%2Fmanagingpartner.com%2Flink_account_callback&“

The query string, produced by the substeps of e, looks like:

account_id=ABC&funding_instrument_id=DEF&status=OK

The percent encoded query string looks like:

account_id%3DABC%26funding_instrument_id%3DDEF%26status%3DOK

The complete base string, combining steps a - d and e:

GET https%3A%2F%2Fmanagingpartner.com%2Flink_account_callback&account_id%3DABC%26funding_instrument_id%3DDEF%26status%3DOK

Using the hmac-sha1 algorithm we will sign this with the word “secret” and the X user id for which the original link request was made, 1 (promotable_user_id = 1 from above) as the key, “secret&1”.

The result is Base64 encoded, and presented without the final “\n” (steps 2 and 3): jDSHDkHJIFXpPLVxtA3a9d4bPjM=

This signature is then added (percent encoded) to the end of the original url in the signature parameter (step 4):

https://managingpartner.com/link\_account\_callback?&status=OK&account\_id=ABC&funding\_instrument_id=DEF&signature=jDSHDkHJIFXpPLVxtA3a9d4bPjM%3D

Shared Key use / renewal

The signing algorithm should have the ability to repeat itself with multiple keys. This will allow multiple shared keys to be used, and enables cycling shared keys on a periodic basis.  

partner_managed_funding_instrument creation

If the fi_description parameter is given, and no existing partner_managed_funding_instrument with the same name exists in the account, a new partner_managed_funding_instrument will be created, and all existing partner_managed_funding_instruments will be paused.

If a partner_managed_funding_instrument with the same name exists, no new one will be created.  

Repeated on-boarding flow calls / token refresh

The on-boarding flow can be repeated in case the API access token was lost. The on-boarding flow implementation will require the user is logged in. If the user matches the promotable_user_id, and the associated ads account is found, and everything looks good, the user will be redirected back to the callback url, and the partner can initiate the OAuth flow to obtain an access token.  

Non-redirectable error flow

If the account link url is invoked with invalid parameters, the user will be shown a page similar to the one shown in the OAuth flow when invalid or expired parameters are given.  

Ongoing updates to the PMFI

Once the advertiser has been onboarded, the funding instrument can be managed using the PUT accounts/:account_id/funding_instruments/:funding_instrument_id endpoint by only the partner who manages it.

Placements

There are several places where X ads can be displayed. This is set at the line item using the placements parameter. The possible values are:

  • ALL_ON_TWITTER
  • PUBLISHER_NETWORK
  • TWITTER_PROFILE
  • TWITTER_SEARCH
  • TWITTER_TIMELINE

The line item’s product_type and objective determine which placements are allowed. The GET line_items/placements endpoint can be used to retrieve the valid placement options for each product type.

Additionally, the following table lists the valid placement and objective combinations.

ObjectiveALL_ON_TWITTERTWITTER_PROFILETWITTER_SEARCHTWITTER_TIMELINE
APP_ENGAGEMENTS
APP_INSTALLS
REACH
FOLLOWERS
ENGAGEMENTS
VIDEO_VIEWS
PREROLL_VIEWS
WEBSITE_CLICKS

Note: It is not possible to specify only TWITTER_PROFILE placement.

Note: TWITTER_SEARCH requires keyword targeting.

Note: The REACH objective must include TWITTER_TIMELINE placement. It can have either ALL_ON_TWITTER, any combination of placements that include TWITTER_TIMELINE, or TWITTER_TIMELINE on its own.

Ad groups FAQ

This document is meant to be a collection of commonly asked questions about Ad Groups in X’s Ads API.

What is an Ad Group?

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

How do we create an Ad Group?

Ad Groups are created by calling POST accounts/:account_id/line_items multiple times for the same campaign ID, and keeping (possibly completely different) targeting and Tweets associated with those line items. There is a limit of 100 line items per campaign and a limit of 200 active campaigns for a single ads account. Across all campaigns, there is a limit of and 8,000 active line items per ads account.

Why should we add support for Ad Groups?

Ad Groups are intended to make it easier for advertisers to organize, optimize and manage their campaigns.

The advantage of Ad Groups is to compare and control different strategies across bid, budget, creative, and targeting. Upon associating multiple Promoted Tweets to a single line item, the auction would select the best Tweet from that group and then select the best Tweet for that campaign from all of the line items. If you have multiple Ad Groups with single Tweets, it would effectively select the Tweet that would likely perform better from that Ad Group.

Using Ad Groups enables an advertiser to split up targeting and bidding into a much greater number of possible combinations, and in general allows splitting up targeting into logical groups.

Ads API tools in particular could be built around fine tuned optimization rules with Ad Groups that would be more difficult to do via manual edits due to the larger scale of line item and creative combinations.

How does the line item budget relate to campaign budget in an Ad Groups campaign?

The total_budget_amount_local_micro for a line item cannot exceed the total budget for its parent campaign. Similarly, the line item’s bid_amount_local_micro value should not exceed daily_budget_amount_local_micro or total_budget_amount_local_micro of the parent campaign. Setting these values incorrectly may put the overall campaign into a paused and unservable state.

Note that the total campaign budget can be less than the sum of the budgets of its child line items, and distribution of budget between line items is partially up to the Ads API tool to effectively optimize and change as daily performance of targeting (line item) could differ significantly day to day due to X’s realtime nature.

Do Ad Groups perform better than single line items?

The performance of a campaign depends upon many factors and effectively a Tweet is the final deciding factor of performance. A Line Item will be treated as a factor of whether or not a Tweet is even in the running to be served to a user.

Line items that target the same sets of users are considered to have overlap of users. It is considered a best practice to reduce this overlap of targeting between line items so that the highest performing sets of users can be clearly identified.

Guides

Video Views Preroll Objective

The following guide outlines the steps required to set up a PREROLL_VIEWS campaign on the Ads API. Broadly speaking these campaigns are split into two types, Curated Categories and Content Categories (referred to as Standard Categories on the Ads UI).  

Endpoints Required

Steps

Upload the video

Uploading the video involves 2 steps:

Upload the video media

First, using the Chunked media upload endpoint, you will upload the video to X for processing. You must pass the media_category=amplify_video on the initial INIT using this endpoint. You’ll upload the video in chunks. Once the STATUS returns a state of succeeded you may continue with the next steps. More on the uploading of media using the chunked endpoint can be found in our Promoted Video Overview.

Add the video to the ads account

Once the state returned using the STATUS command is succeeded, you’ll use the media_key returned from that endpoint to add the video to the advertiser’s media library, using the POST accounts/:account_id/media_library endpoint.

POST https://ads-api.x.com/8/55w3kv/media\_library?media\_key=3_931236738554519552

{
 "request": {
   "params": {
     "account_id": "55w3kv",
     "media\_key": "3\_931236738554519552"
   }
 },
 "data": {
   "tweeted": false,
   "name": null,
   "file_name": null,
   "media\_url": "https://video.twimg.com/amplify\_video/1059840836186165250/vid/568x320/Gr2l1fB1X7xotKwC.mp4?tag=8",
   "media\_category": "AMPLIFY\_VIDEO",
   "media\_key": "3\_931236738554519552",
   "created_at": "2017-11-16T19:05:14Z",
   "media\_status": "TRANSCODE\_COMPLETED",
   "media_id": 931236738554519552,
   "media_type": "VIDEO",
   "updated_at": "2017-11-16T19:05:23Z",
   "deleted": false
 }
}

Setup the campaign

Campaign Creation

Create the campaign and line item/ad group. Line items should be created with an objective of VIDEO_VIEWS_PREROLL, and a product_type of MEDIA. The categories parameter must also be set to the appropriate advertiser business categories.

POST https://ads-api.x.com/8/accounts/55w3kv/campaigns?name=test-curated-categories-api&funding\_instrument\_id=103hp9&start\_time=2021-02-10&entity\_status=PAUSED&daily\_budget\_amount\_local\_micro=55000000

{
  "request": {
    "params": {
      "name": "test-curated-categories-api",
      "start_time": "2021-02-10T00:00:00Z",
      "daily\_budget\_amount\_local\_micro": 55000000,
      "funding\_instrument\_id": "103hp9",
      "entity_status": "PAUSED",
      "account_id": "55w3kv"
    }
  },
  "data": {
    "name": "test-curated-categories-api",
    "start_time": "2021-02-10T00:00:00Z",
    "reasons\_not\_servable": \[
      "EXPIRED",
      "PAUSED\_BY\_ADVERTISER",
      "FUNDING_PROBLEM"
    \],
    "servable": false,
    "purchase\_order\_number": null,
    "effective_status": "PAUSED",
    "daily\_budget\_amount\_local\_micro": 55000000,
    "end_time": null,
    "funding\_instrument\_id": "103hp9",
    "duration\_in\_days": null,
    "standard_delivery": true,
    "total\_budget\_amount\_local\_micro": null,
    "id": "f2rp3",
    "entity_status": "PAUSED",
    "frequency_cap": null,
    "currency": "USD",
    "created_at": "2021-02-08T23:55:38Z",
    "updated_at": "2021-02-08T23:55:38Z",
    "deleted": false
  }
}

Line Item Creation

Line items must have the categories parameter set to the appropriate set of IAB categories, retrieved via the GET content_categories endpoint. These content categories each correspond to one or more IAB categories.

In order to use these values, partners must select an appropriate content category and use the entire set of iab_categories returned in the response, to set the categories parameter on the line items endpoint. Any partial application of the iab_categories will result in the entire group being set on the line item. For example,

GET https://ads-api.x.com/8/advertiser\_business\_categories

{
  "request": {
    "params": {}
  },
  "next_cursor": null,
  "data": \[
    {
      "id": "1jl",
      "name": "Consumer Packaged Goods",
      "iab_categories": \[
        "IAB9-26",
        "IAB9-18",
        "IAB9-29",
        "IAB9-1",
        "IAB9-8",
        "IAB9-22",
        "IAB6",
        "IAB9-5",
        "IAB9-12",
        "IAB9-11",
        "IAB9-23",
        "IAB9-14",
        "IAB4",
        "IAB9-25",
        "IAB9-17",
        "IAB23",
        "IAB9-24",
        "IAB9-13",
        "IAB16",
        "IAB9-4",
        "IAB9-9",
        "IAB9-20",
        "IAB22",
        "IAB9-28",
        "IAB9-27",
        "IAB9-16",
        "IAB9-31",
        "IAB9-3",
        "IAB9-19",
        "IAB10",
        "IAB9-2",
        "IAB9-6",
        "IAB9-21",
        "IAB9-10",
        "IAB9-15"
      \]
    },
    {
      "id": "1jm",
      "name": "Health & Pharma",
      "iab_categories": \[
        "IAB7"
      \]
    },
    {
      "id": "1jn",
      "name": "Alcohol",
      "iab_categories": \[
        "IAB8-5",
        "IAB8-18"
      \]
    },
    {
      "id": "1jo",
      "name": "Dining",
      "iab_categories": \[
        "IAB8-10",
        "IAB8-8",
        "IAB8-7",
        "IAB8-15",
        "IAB8-3",
        "IAB8-4",
        "IAB8-1",
        "IAB8-16",
        "IAB8-12",
        "IAB8-13",
        "IAB8-17",
        "IAB8-11",
        "IAB8-6",
        "IAB8-9",
        "IAB8-2",
        "IAB8-14"
      \]
    },
    {
      "id": "1jp",
      "name": "Financial Services",
      "iab_categories": \[
        "IAB3",
        "IAB13",
        "IAB21"
      \]
    },
    {
      "id": "1jq",
      "name": "Retail",
      "iab_categories": \[
        "IAB18"
      \]
    },
    {
      "id": "1jr",
      "name": "Travel",
      "iab_categories": \[
        "IAB20"
      \]
    },
    {
      "id": "1js",
      "name": "Gaming",
      "iab_categories": \[
        "IAB9-30"
      \]
    },
    {
      "id": "1jt",
      "name": "Technology",
      "iab_categories": \[
        "IAB19-22",
        "IAB19-13",
        "IAB19-4",
        "IAB19-33",
        "IAB19-26",
        "IAB19-3",
        "IAB19-16",
        "IAB19-9",
        "IAB19-32",
        "IAB19-25",
        "IAB19-30",
        "IAB19-36",
        "IAB19-21",
        "IAB5",
        "IAB19-12",
        "IAB19-28",
        "IAB19-17",
        "IAB19-8",
        "IAB19-7",
        "IAB19-24",
        "IAB15",
        "IAB19-11",
        "IAB19-31",
        "IAB19-20",
        "IAB19-15",
        "IAB19-1",
        "IAB19-35",
        "IAB19-29",
        "IAB19-34",
        "IAB19-23",
        "IAB19-2",
        "IAB19-5",
        "IAB19-14",
        "IAB19-27",
        "IAB19-10",
        "IAB19-19"
      \]
    },
    {
      "id": "1ju",
      "name": "Telecommunication",
      "iab_categories": \[
        "IAB19-6",
        "IAB19-18"
      \]
    },
    {
      "id": "1jv",
      "name": "Auto",
      "iab_categories": \[
        "IAB2"
      \]
    },
    {
      "id": "1jw",
      "name": "Media & Entertainment",
      "iab_categories": \[
        "IAB14-8",
        "IAB14-4",
        "IAB1-5",
        "IAB14-7",
        "IAB1-7",
        "IAB17",
        "IAB14-3",
        "IAB1-1",
        "IAB12",
        "IAB1-6",
        "IAB25-1",
        "IAB1-2",
        "IAB14-2",
        "IAB14-6",
        "IAB1-3",
        "IAB1-4",
        "IAB14-5"
      \]
    },
    {
      "id": "1jx",
      "name": "Politics",
      "iab_categories": \[
        "IAB11-4"
      \]
    },
    {
      "id": "1jy",
      "name": "Gambling",
      "iab_categories": \[
        "IAB9-7"
      \]
    },
    {
      "id": "1jz",
      "name": "Dating",
      "iab_categories": \[
        "IAB14-1"
      \]
    },
    {
      "id": "1k0",
      "name": "Non-Profit",
      "iab_categories": \[
        "IAB11-1",
        "IAB11-2",
        "IAB11-3",
        "IAB11-5"
      \]
    }
  \]
}

Now, in order to set the categories parameter to “Science & Education”, the entire set of iab_categories i.e., "IAB5", "IAB15" must be set for the line item, like so:

POST https://ads-api.x.com/8/accounts/55w3kv/line\_items?campaign\_id=f2rp3&bid\_amount\_local\_micro=5500000&name=curated-category-line-item&product\_type=MEDIA&placements=ALL\_ON\_TWITTER&objective=PREROLL_VIEWS&categories=IAB3,IAB13,IAB21

{
  "request": {
    "params": {
      "name": "curated-category-line-item",
      "placements": \[
        "ALL\_ON\_TWITTER"
      \],
      "bid\_amount\_local_micro": 5500000,
      "product_type": "MEDIA",
      "objective": "PREROLL_VIEWS",
      "account_id": "55w3kv",
      "categories": \[
        "IAB3",
        "IAB13",
        "IAB21"
      \],
      "campaign_id": "f2rp3"
    }
  },
  "data": {
    "bid_type": "MAX",
    "advertiser\_user\_id": 312226591,
    "name": "curated-category-line-item",
    "placements": \[
      "ALL\_ON\_TWITTER"
    \],
    "start_time": null,
    "bid\_amount\_local_micro": 5500000,
    "automatically\_select\_bid": false,
    "advertiser_domain": null,
    "target\_cpa\_local_micro": null,
    "raw_categories": \[
      "x",
      "5l",
      "9z"
    \],
    "primary\_web\_event_tag": null,
    "charge\_by": "VIEW\_3S_100PCT",
    "product\_type": "PROMOTED\_TWEETS",
    "end_time": null,
    "duration\_in\_days": null,
    "bid\_unit": "VIEW\_3S_100PCT",
    "total\_budget\_amount\_local\_micro": null,
    "objective": "PREROLL_VIEWS",
    "id": "iqwka",
    "entity_status": "ACTIVE",
    "automatic\_tweet\_promotion": null,
    "optimization": "DEFAULT",
    "frequency_cap": null,
    "android\_app\_store_identifier": null,
    "categories": \[
      "IAB3",
      "IAB13",
      "IAB21"
    \],
    "currency": "USD",
    "created_at": "2021-02-09T00:00:46Z",
    "tracking_tags": \[\],
    "ios\_app\_store_identifier": null,
    "amplify_config": {
      "auto_promote": true,
      "is_open": true
    },
    "updated_at": "2021-02-09T00:00:46Z",
    "campaign_id": "f2rp3",
    "creative_source": "MANUAL",
    "deleted": false
  }
}

Publisher Selection

An advertiser may choose to target either a Content Category or a Curated Category, with additional details described below. 

Note:  Line items may target either Curated or Content  Categories but not both. 

Curated Categories

Curated Categories allow advertisers to target a preset group of publishers and can be retrieved using the  GET curated_categories endpoint. These categories are country specific, and therefore require that the line item target the appropriate country based on the country_code of the category.

In order to use one of these categories, the following steps are required in the specific order listed:

  1. The line item needs to target the appropriate country based on the country_code of the Curated Category
  2. The POST line_item_curated_categories endpoint must be used to associate the line item with a specific curated_category_id. 

Note: Associating a line item with a curated category will also limit the number of publishers that can be denylisted to 5. The full list of user_id used to denylist specific publishers can be retrieved from the GET publishers endpoint. Additionally, a given line item may target no more than one Curated Category at a time.

The following example illustrates how to associate a curated category id: b0xt which is only available in the US, with the line item created in the previous step.

First, the line item’s targeting criteria is set to the the value 96683cc9126741d

GET https://ads-api.x.com/8/targeting\_criteria/locations?country\_code=US&location_type=COUNTRIES

{
  "data": \[
    {
      "name": "United States",
      "country_code": "US",
      "location_type": "COUNTRIES",
      "targeting_value": "96683cc9126741d1",
      "targeting_type": "LOCATION"
    }
  \],
  "request": {
    "params": {
      "location_type": "COUNTRIES",
      "country_code": "US"
    }
  },
  "next_cursor": null
}

POST https://ads-api.x.com/8/batch/accounts/55w3kv/targeting_criteria
\[
  {
    "operation_type": "Create",
    "params": {
      "line\_item\_id": "iqwka",
      "targeting_type": "LOCATION",
      "targeting_value": "96683cc9126741d1",
      "operator_type": "EQ"
    }
  }
\]

{
  "data": \[
    {
      "line\_item\_id": "iqwka",
      "name": "United States",
      "raw_negated": false,
      "raw\_targeting\_value": "2",
      "id": "rv9hmc",
      "raw\_targeting\_type": "GEO",
      "raw\_operator\_type": "EQUAL_TO",
      "location_type": "COUNTRIES",
      "operator_type": "EQ",
      "created_at": "2021-02-09T00:06:28Z",
      "targeting_value": "96683cc9126741d1",
      "updated_at": "2021-02-09T00:06:28Z",
      "deleted": false,
      "targeting_type": "LOCATION"
    }
  \],
  "request": \[
    {
      "params": {
        "line\_item\_id": "iqwka",
        "account_id": "55w3kv",
        "operator_type": "EQ",
        "targeting_value": "96683cc9126741d1",
        "targeting_type": "LOCATION"
      },
      "operation_type": "Create"
    }
  \]
}

POST https://ads-api.x.com/8/accounts/55w3kv/line\_item\_curated\_categories?line\_item\_id=iqwka&curated\_category_id=9ddrgesiap6o

{
  "request": {
    "params": {
      "curated\_category\_id": "9ddrgesiap6o",
      "line\_item\_id": "iqwka",
      "account_id": "55w3kv"
    }
  },
  "data": {
    "line\_item\_id": "iqwka",
    "curated\_category\_id": "9ddrgesiap6o",
    "id": "xq",
    "created_at": "2021-03-30T17:26:42Z",
    "updated_at": "2021-03-30T17:26:42Z",
    "deleted": false
  }
}

Content Categories

Content categories, also referred to as Standard Categories can be retrieved from the GET curated_categories endpoint. These categories can then be targeted by the line item using the batch targeting criteria endpoints. The following example illustrates how to select a particular content category, id: sr which maps to “News & Current Events” and apply it to the line item.

Note: The entire set of iab_categories in the GET curated_categories response must be targeted via the targeting criteria endpoint. Failing to do so will result in a validation error. 

GET https://ads-api.x.com/8/content_categories
{
      "name": "News & Current Events",
      "id": "sr",
      "iab_categories": \[
        "IAB12",
        "IAB14"
      \],
      "publishers\_in\_last\_thirty\_days": 124,
      "videos\_monetized\_in\_last\_thirty_days": 5429
    }
}

POST https://ads-api.x.com/8/batch/accounts/55w3kv/targeting_criteria
\[
  {
    "operation_type": "Create",
    "params": {
      "line\_item\_id": "iqwls",
      "targeting\_type": "IAB\_CATEGORY",
      "targeting_value": "IAB12",
      "operator_type": "EQ"
    }
  },
  {
    "operation_type": "Create",
    "params": {
      "line\_item\_id": "iqwls",
      "targeting\_type": "IAB\_CATEGORY",
      "targeting_value": "IAB14",
      "operator_type": "EQ"
    }
  }
\]

{
  "data": \[
    {
      "line\_item\_id": "iqwls",
      "name": "News",
      "raw_negated": false,
      "raw\_targeting\_value": "5h",
      "id": "saib9p",
      "raw\_targeting\_type": "IAB_CATEGORY",
      "raw\_operator\_type": "EQUAL_TO",
      "operator_type": "EQ",
      "created_at": "2021-03-30T17:35:50Z",
      "targeting_value": "IAB12",
      "updated_at": "2021-03-30T17:35:50Z",
      "deleted": false,
      "targeting\_type": "IAB\_CATEGORY"
    },
    {
      "line\_item\_id": "iqwls",
      "name": "Society",
      "raw_negated": false,
      "raw\_targeting\_value": "5y",
      "id": "saib9q",
      "raw\_targeting\_type": "IAB_CATEGORY",
      "raw\_operator\_type": "EQUAL_TO",
      "operator_type": "EQ",
      "created_at": "2021-03-30T17:35:50Z",
      "targeting_value": "IAB14",
      "updated_at": "2021-03-30T17:35:50Z",
      "deleted": false,
      "targeting\_type": "IAB\_CATEGORY"
    }
  \],
  "request": \[
    {
      "params": {
        "line\_item\_id": "iqwls",
        "account_id": "55w3kv",
        "operator_type": "EQ",
        "targeting_value": "IAB12",
        "targeting\_type": "IAB\_CATEGORY"
      },
      "operation_type": "Create"
    },
    {
      "params": {
        "line\_item\_id": "iqwls",
        "account_id": "55w3kv",
        "operator_type": "EQ",
        "targeting_value": "IAB14",
        "targeting\_type": "IAB\_CATEGORY"
      },
      "operation_type": "Create"
    }
  \]
}
Associate the account media (video) with the line item

Use the POST accounts/:account_id/media_creatives endpoint to associate the video with an ad group.

POST https://ads-api.x.com/8/accounts/55w3kv/media_creatives
line\_item\_id=4bii5&account\_media\_id=knb

{
 "data":{
   "account\_media\_id":"74g",
   "approval_status":"ACCEPTED",
   "created_at":"2016-02-11T22:23:23Z",
   "deleted":false,
   "id":"qeq",
   "landing_url":null,
   "line\_item\_id":"4bii5",
   "serving_status":"ACTIVE",
   "updated_at":"2016-02-11T22:23:23Z"
 },
 "request":{
   "params":{
     "line\_item\_id":"4bii5",
     "account\_media\_id":"knb"
   }
 }
}

Set the CTA and destination URL

It is important to note that unlike most other campaigns on X, the VIDEO_VIEWS_PREROLL objective does not utilize Promoted Tweets or Cards. Instead, the video creative is associated with your ad group (line item) and the CTA information is associated with a preroll_call_to_action entity. The POST accounts/:account_id/preroll_call_to_action endpoint allows you to control the button CTA and the destination URL.

POST https://ads-api.x.com/8/accounts/55w3kv/preroll\_call\_to_action
line\_item\_id=4bii5&call\_to\_action=VISIT\_SITE&call\_to\_action\_url=https%3A%2F%2Fx.com%2FAdsAPI

{
 "data":{
   "id":"aaa111",
   "line\_item\_id":"4bii5",
   "call\_to\_action":"WATCH_NOW",
   "call\_to\_action_url":"https://x.com/AdsAPI",
   "created_at":"2016-02-11T22:23:23Z",
   "updated_at":"2016-02-11T22:23:23Z",
   "deleted":false
 },
 "request":{
   "params":{
     "line\_item\_id":"4bii5",
     "call\_to\_action":"VISIT_SITE",
     "call\_to\_action_url":"https://x.com/AdsAPI"
   }
 }
}

Set targeting criteria

The targetting criterion utilized for pre-roll video ads is only avaialble using our batch targeting criteria endpoint POST batch/accounts/:account_id/targeting_criteria.

Use CONTENT_PUBLISHER_USER as negated targeting to exclude the ad from being paired with a set of users. Provide the X user_id  or publisher_user_id for the handles to exclude.

The GET publishers endpoint can be used to retrieve the list of user_id to exclude for Content Categories. The publisher_user_id returned in the GET curated_categories response can be used to retrieve a similar exclusion list for Curated Categories.

Note: A maximum of 5 publisher_user_id can be excluded for Curated Categories and 50 user_id for Content Categories.

POST https://ads-api.x.com/8/batch/accounts/55w3kv/targeting_criteria
\[
  {
    "operation_type": "Create",
    "params": {
      "line\_item\_id": "iqwls",
      "targeting\_type": "CONTENT\_PUBLISHER_ID",
      "targeting_value": "1917731",
      "operator_type": "NE"
    }
  }
\]

{
  "data": \[
    {
      "line\_item\_id": "iqwka",
      "name": "realsaltlake",
      "raw_negated": true,
      "raw\_targeting\_value": "aajwo",
      "id": "sajk32",
      "raw\_targeting\_type": "CONTENT_PUBLISHER",
      "raw\_operator\_type": "EQUAL_TO",
      "operator_type": "NE",
      "created_at": "2021-03-30T18:02:32Z",
      "targeting_value": 17288520,
      "updated_at": "2021-03-30T18:02:32Z",
      "deleted": false,
      "targeting\_type": "CONTENT\_PUBLISHER_USER"
    }
  \],
  "request": \[
    {
      "params": {
        "line\_item\_id": "iqwka",
        "account_id": "55w3kv",
        "operator_type": "NE",
        "targeting_value": "17288520",
        "targeting\_type": "CONTENT\_PUBLISHER_USER"
      },
      "operation_type": "Create"
    }
  \]
}

Launch campaign

When you’re ready to launch your campaign, simply un-pause using PUT accounts/:account_id/campaigns/:id.

PUT https://ads-api.x.com/8/accounts/55w3kv/campaigns/f2rp3? entity_status=ACTIVE

{
  "request": {
    "params": {
      "campaign_id": "f2rp3",
      "account_id": "55w3kv"
    }
  },
  "data": {
    "name": "test-curated-categories-api",
    "start_time": "2021-02-10T00:00:00Z",
    "reasons\_not\_servable": \[
    \],
    "servable": false,
    "purchase\_order\_number": null,
    "effective_status": "ACTIVE",
    "daily\_budget\_amount\_local\_micro": 55000000,
    "end_time": null,
    "funding\_instrument\_id": "103hp9",
    "duration\_in\_days": null,
    "standard_delivery": true,
    "total\_budget\_amount\_local\_micro": null,
    "id": "f2rp3",
    "entity_status": "ACTIVE",
    "frequency_cap": null,
    "currency": "USD",
    "created_at": "2021-02-08T23:55:38Z",
    "updated_at": "2021-02-08T23:55:38Z",
    "deleted": false
  }
}

Analytics

Analytics for VIDEO_VIEWS_PREROLL campaigns are available using our stats endpoints.

Keyword Targeting in Timelines

Keyword targeting is fundamental to our Promoted Tweets products, giving campaigns better reach. Keyword targeting in timeline enables platforms to target X users based on keywords in their recent Tweets. For example, if an advertiser is targeting the unordered keyword combination “plan + trip”, and a user Tweets, “I’m starting to plan my trip to Cabo, any suggestions?” while the campaign is running, that user may soon afterward see the advertiser’s Promoted Tweet.

How does it work?

TL;DR: from an API standpoint, this change is quite simple: you can now target keywords on Promoted Tweets in Timeline. Just set the targeting_type to unordered_keywords or phrase_keywords for line items.

Quick Start Guide

API Reference

Accounts

GET accounts

Retrieve details for some or all advertising-enabled accounts the authenticating user has access to.

Resource URL

https://ads-api.x.com/12/accounts

Parameters

NameDescription
account_ids
optional
Scope the response to just the desired account IDs by specifying a comma-separated list of identifiers.

Type: string

Example: 18ce54d4x5t
count
optional
Specifies the number of records to try and retrieve per distinct request.

Type: int

Default: 200
Min, Max: 1, 1000
cursor
optional
Specifies a cursor to get the next page of results. See Pagination for more information.

Type: string

Example: 8x7v00oow
q
optional
An optional query to scope resource by name.

Note: This performs case-insensitive prefix matching.

Type: string

Min, Max length: 1, 255
sort_by
optional
Sorts by supported attribute in ascending or descending order. See Sorting for more information.

Type: string

Example: created_at-asc
with_deleted
optional
Include deleted results in your request.

Type: boolean

Default: false
Possible values: true, false
with_total_count
optional
Include the total_count response attribute.

Note: This parameter and cursor are exclusive.

Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes.

Type: boolean

Default: false
Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts?account_ids=18ce54d4x5t

Example Response

       {
         "request": {
           "params": {
             "account_ids": [
               "18ce54d4x5t"
             ]
           }
         },
         "next_cursor": null,
         "data": [
           {
             "name": "API McTestface",
             "business_name": null,
             "timezone": "America/Los_Angeles",
             "timezone_switch_at": "2016-07-21T07:00:00Z",
             "id": "18ce54d4x5t",
             "created_at": "2016-07-21T22:42:09Z",
             "updated_at": "2017-07-06T16:51:04Z",
             "business_id": null,
             "approval_status": "ACCEPTED",
             "deleted": false
           }
         ]
       }

GET accounts/:account_id

Retrieve a specific account that the authenticating user has access to.

Resource URL

https://ads-api.x.com/12/accounts/:account_id

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts.

The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
with_deleted
optional
Include deleted results in your request.

Type: boolean

Default: false
Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t

Example Response

       {
         "request": {
           "params": {
             "account_id": "18ce54d4x5t"
           }
         },
         "data": {
           "name": "API McTestface",
           "business_name": null,
           "timezone": "America/Los_Angeles",
           "timezone_switch_at": "2016-07-21T07:00:00Z",
           "id": "18ce54d4x5t",
           "created_at": "2016-07-21T22:42:09Z",
           "updated_at": "2017-07-06T16:51:04Z",
           "industry_type": "TRAVEL",
           "business_id": null,
           "approval_status": "ACCEPTED",
           "deleted": false
         }
       }

POST accounts

Note: SANDBOX ONLY

Create an ads account in the sandbox environment.

Resource URL

https://ads-api-sandbox.x.com/12/accounts

Parameters

None

Example Request

POST https://ads-api-sandbox.x.com/12/accounts

Example Response

       {
         "request": {
           "params": {}
         },
         "next_cursor": null,
         "data": [
           {
             "name": "Sandbox account",
             "business_name": null,
             "timezone": "America/Los_Angeles",
             "timezone_switch_at": null,
             "id": "gq12fh",
             "created_at": "2016-07-18T23:02:20Z",
             "updated_at": "2016-07-18T23:02:20Z",
             "business_id": null,
             "approval_status": "ACCEPTED",
             "deleted": false
           }
         ]
       }

PUT accounts/:account_id

Updates the account name and/or industry type.

Resource URL

https://ads-api.x.com/12/accounts/:account_id

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts.
The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
name
optional
The name of account.

Type: string

Example: API McTestface
industry_type
optional
Industry that the account is associated with.

Type: string

Possible values: AGENCY, BUSINESS_TO_BUSINESS, ONLINE_SERVICES, EDUCATION, FINANCIAL, HEALTH, GOVERNMENT, MEDIA, MOBILE, RESTAURANT, RETAIL, TECHNOLOGY, TRAVEL, OTHER

Example Request

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t?name='API McTestface 2'&industry_type=TECHNOLOGY

Example Response

       {
         "request": {
           "params": {
             "account_id": "18ce54d4x5t"
             "name"": "API McTestface 2",
             "industry_type": "TECHNOLOGY"
           }
         },
         "data": {
           "name": "API McTestface 2",
           "business_name": null,
           "timezone": "America/Los_Angeles",
           "timezone_switch_at": "2016-07-21T07:00:00Z",
           "id": "18ce54d4x5t",
           "created_at": "2016-07-21T22:42:09Z",
           "updated_at": "2017-07-06T16:51:04Z",
           "industry_type": "TECHNOLOGY",
           "business_id": null,
           "approval_status": "ACCEPTED",
           "deleted": false
         }
       }

DELETE accounts/:account_id

Note: SANDBOX ONLY

Delete an ads account in the sandbox environment.

Resource URL

https://ads-api-sandbox.x.com/12/accounts/:account_id

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts.

The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t

Example Request

DELETE https://ads-api-sandbox.x.com/12/accounts/gq12fh

Example Response

       {
         "data": {
           "name": "Sandbox account",
           "timezone": "America/Los_Angeles",
           "timezone_switch_at": null,
           "id": "gq12fh",
           "created_at": "2016-07-18T23:02:20Z",
           "updated_at": "2017-08-23T18:21:10Z",
           "approval_status": "ACCEPTED",
           "deleted": true
         },
         "request": {
           "params": {
             "account_id": "gq12fh"
           }
         }
       }

Account Apps

Run in Postman ❯

GET account_apps

Retrieve details for all mobile apps that are associated with the specified ad account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/account_apps

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
count
optional
Specifies the number of records to try and retrieve per distinct request.

Type: int

Default: 200
Min, Max: 1, 1000
cursor
optional
Specifies a cursor to get the next page of results. See Pagination for more information.

Type: string

Example: 8x7v00oow
sort_by
optional
Sorts by supported attribute in ascending or descending order. See Sorting for more information.

Type: string

Example: created_at-asc
with_deleted
optional
Include deleted results in your request.

Type: boolean

Default: false
Possible values: true, false
with_total_count
optional
Include the total_count response attribute.

Note: This parameter and cursor are exclusive.

Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes.

Type: boolean

Default: false
Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_apps

Example Response

       {
         "request": {
           "params": {
             "account_ids": [
               "18ce54d4x5t"
             ]
           }
         },
         "next_cursor": null,
         "data": [
          {
            "app_store_identifier": "com.twitter.android",
            "conversion_tracking_enabled": false,
            "deep_link_pattern": "twitter://",
            "id": "4x",
            "created_at": "2019-06-20T22:36:16Z",
            "updated_at": "2021-10-19T20:05:29Z",
            "os_type": "Android",
            "deleted": false
          }
         ]
       }

Account History

GET accounts/:account_id/account_history

Retrieve a summary of changes made to the entity_id specified in the request.

Note: This endpoint is currently in beta and requires allowlisting.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/account_history

Parameters

NameDescription
account_id
required
The identifier for the leveraged account.

Type: string

Example: 18ce54d4x5t
count
optional
Specifies the number of records to try and retrieve per distinct request.

Type: int

Default: 200
Min, Max: 1, 1000
cursor
optional
Specifies a cursor to get the next page of results. See Pagination for more information.

Type: string

Example: 8x7v00oow
entity_type
required
The entity type to retrieve data for.

Type: enum

Example: PROMOTED_TWEET
Possible values: CAMPAIGN, LINE_ITEM, PROMOTED_TWEET, TARGETING_CRITERIA, PROMOTED_ACCOUNT
entity_id
required
The specific entitiy to retrieve data for.

Type: string

Example: 8u94t
start_time
required
Scopes the retrieved data to the specified start time, expressed in ISO 8601.

Note: Must be expressed in whole hours (0 minutes and 0 seconds).

Type: string

Example: 2017-05-19T07:00:00Z
end_time
required
Scopes the retrieved data to the specified end time, expressed in ISO 8601.

Note: Must be expressed in whole hours (0 minutes and 0 seconds).

Type: string

Example: 2017-05-26T07:00:00Z
user_id
optional
Scopes the response to a specific user.

Type: long

Example: 3271358660

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_history?entity_type=CAMPAIGN&entity_id=fc3h5&count=1

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "entity": "CAMPAIGN",
          "entity_id": "fc3h5",
          "count": 1
        }
      },
      "next_cursor": "1r2407sb4lc",
      "data": [
        {
          "change_by": {
            "user_id": "982978172",
            "platform": "API_OTHER"
          },
          "changes": {},
          "change_time": "2021-04-02T20:55:42Z",
          "entity_id": "fc3h5",
          "entity": "CAMPAIGN",
          "entity_data": {
            "name": "test_campaign",
            "start_time": "2021-04-02T18:59:11Z",
            "purchase_order_number": null,
            "daily_budget_amount_local_micro": 100000000,
            "end_time": null,
            "duration_in_days": null,
            "standard_delivery": true,
            "total_budget_amount_local_micro": 100000000,
            "entity_status": "ACTIVE",
            "frequency_cap": null,
            "created_at": "2021-04-02T20:55:42Z",
            "updated_at": "2021-04-02T20:55:42Z",
            "deleted": false
          },
          "change_type": "CREATE"
        }
      ]
    }

Advertiser Business Categories

GET advertiser_business_categories

Request the valid advertiser business categories for Ad Groups (line_items) to describe an advertiser’s brand to publishers.

Note: These categories apply only to line_items with the PREROLL_VIEWS objective and are separate from the content_categories used for targeting criteria.

Each advertiser_business_categories represents a collection of IAB Categories. When creating an Ad Group with the PREROLL_VIEWS objective, one or two advertiser_business_categories must be set for the Ad Group. This can be done by setting the value of the categories request parameter on the line item endpoint to the set of corresponding iab_categories available through this endpoint.

Additional details can be found in the Video Views Preroll Objective Guide

Resource URL

https://ads-api.x.com/12/advertiser_business_categories

Parameters

No request parameters

Example Request

GET https://ads-api.x.com/12/advertiser_business_categories

Example Response

    {
      "request": {
        "params": {}
      },
      "next_cursor": null,
      "data": [
        {
          "id": "1jl",
          "name": "Consumer Packaged Goods",
          "iab_categories": [
            "IAB9-26",
            "IAB9-18",
            "IAB9-29",
            "IAB9-1",
            "IAB9-8",
            "IAB9-22",
            "IAB6",
            "IAB9-5",
            "IAB9-12",
            "IAB9-11",
            "IAB9-23",
            "IAB9-14",
            "IAB4",
            "IAB9-25",
            "IAB9-17",
            "IAB23",
            "IAB9-24",
            "IAB9-13",
            "IAB16",
            "IAB9-4",
            "IAB9-9",
            "IAB9-20",
            "IAB22",
            "IAB9-28",
            "IAB9-27",
            "IAB9-16",
            "IAB9-31",
            "IAB9-3",
            "IAB9-19",
            "IAB10",
            "IAB9-2",
            "IAB9-6",
            "IAB9-21",
            "IAB9-10",
            "IAB9-15"
          ]
        },
        {
          "id": "1jm",
          "name": "Health & Pharma",
          "iab_categories": [
            "IAB7"
          ]
        },
        {
          "id": "1jn",
          "name": "Alcohol",
          "iab_categories": [
            "IAB8-5",
            "IAB8-18"
          ]
        },
        {
          "id": "1jo",
          "name": "Dining",
          "iab_categories": [
            "IAB8-10",
            "IAB8-8",
            "IAB8-7",
            "IAB8-15",
            "IAB8-3",
            "IAB8-4",
            "IAB8-1",
            "IAB8-16",
            "IAB8-12",
            "IAB8-13",
            "IAB8-17",
            "IAB8-11",
            "IAB8-6",
            "IAB8-9",
            "IAB8-2",
            "IAB8-14"
          ]
        },
        {
          "id": "1jp",
          "name": "Financial Services",
          "iab_categories": [
            "IAB3",
            "IAB13",
            "IAB21"
          ]
        },
        {
          "id": "1jq",
          "name": "Retail",
          "iab_categories": [
            "IAB18"
          ]
        },
        {
          "id": "1jr",
          "name": "Travel",
          "iab_categories": [
            "IAB20"
          ]
        },
        {
          "id": "1js",
          "name": "Gaming",
          "iab_categories": [
            "IAB9-30"
          ]
        },
        {
          "id": "1jt",
          "name": "Technology",
          "iab_categories": [
            "IAB19-22",
            "IAB19-13",
            "IAB19-4",
            "IAB19-33",
            "IAB19-26",
            "IAB19-3",
            "IAB19-16",
            "IAB19-9",
            "IAB19-32",
            "IAB19-25",
            "IAB19-30",
            "IAB19-36",
            "IAB19-21",
            "IAB5",
            "IAB19-12",
            "IAB19-28",
            "IAB19-17",
            "IAB19-8",
            "IAB19-7",
            "IAB19-24",
            "IAB15",
            "IAB19-11",
            "IAB19-31",
            "IAB19-20",
            "IAB19-15",
            "IAB19-1",
            "IAB19-35",
            "IAB19-29",
            "IAB19-34",
            "IAB19-23",
            "IAB19-2",
            "IAB19-5",
            "IAB19-14",
            "IAB19-27",
            "IAB19-10",
            "IAB19-19"
          ]
        },
        {
          "id": "1ju",
          "name": "Telecommunication",
          "iab_categories": [
            "IAB19-6",
            "IAB19-18"
          ]
        },
        {
          "id": "1jv",
          "name": "Auto",
          "iab_categories": [
            "IAB2"
          ]
        },
        {
          "id": "1jw",
          "name": "Media & Entertainment",
          "iab_categories": [
            "IAB14-8",
            "IAB14-4",
            "IAB1-5",
            "IAB14-7",
            "IAB1-7",
            "IAB17",
            "IAB14-3",
            "IAB1-1",
            "IAB12",
            "IAB1-6",
            "IAB25-1",
            "IAB1-2",
            "IAB14-2",
            "IAB14-6",
            "IAB1-3",
            "IAB1-4",
            "IAB14-5"
          ]
        },
        {
          "id": "1jx",
          "name": "Politics",
          "iab_categories": [
            "IAB11-4"
          ]
        },
        {
          "id": "1jy",
          "name": "Gambling",
          "iab_categories": [
            "IAB9-7"
          ]
        },
        {
          "id": "1jz",
          "name": "Dating",
          "iab_categories": [
            "IAB14-1"
          ]
        },
        {
          "id": "1k0",
          "name": "Non-Profit",
          "iab_categories": [
            "IAB11-1",
            "IAB11-2",
            "IAB11-3",
            "IAB11-5"
          ]
        }
      ]
    }

Audience Estimate

POST accounts/:account_id/audience_estimate

Determine the approximate audience size of your campaigns.

This endpoint accepts an array of JSON objects containing the parameters for the targeting criteria objects. A list of required and optional targeting criteria parameters are available on the POST accounts/:account_id/targeting_criteria endpoint. Requests must be HTTP POST with a JSON content body with a Content-Type: application/json header.

Note: It is required that you specify at least one primary targeting criterion; you can see a list of all primary targeting criteria in our campaigns targeting page.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/audience_estimate

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
targeting_criteria
required
A JSON object containing all the parameters for the targeting criteria objects. A list of required and optional targeting criteria parameters are available on the POST accounts/:account_id/targeting_criteria endpoint.
operator_type
optional
Specify the relationship that the targeting criterion should have. For example, to set negated targeting, use operator_type=NE.

Type: enum

Possible values: EQ, NE

Default: EQ

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/audience_estimate

    {
        "targeting_criteria": [
            {
                "targeting_type": "BROAD_KEYWORD",
                "targeting_value": "nba",
                "operator_type": "EQ"
            },
            {
                "targeting_type": "BROAD_KEYWORD",
                "targeting_value": "tech",
                "operator_type": "NE"
            },
            {
                "targeting_type": "LOCATION",
                "targeting_value": "96683cc9126741d1",
                "operator_type": "EQ"
            },
            {
                "targeting_type": "SIMILAR_TO_FOLLOWERS_OF_USER",
                "targeting_value": "14230524"
            },
            {
                "targeting_type": "SIMILAR_TO_FOLLOWERS_OF_USER",
                "targeting_value": "90420314"
            }
        ]
    }

Example Response

    {
      "request": {
        "params": {
          "targeting_criteria": null,
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "audience_size": {
          "min": 38236294,
          "max": 42261167
        }
      }
    }

Authenticated User Access

GET accounts/:account_id/authenticated_user_access

Retrieve the permissions of the currently authenticated user (access_token) as they relate to the specified ads account. These permissions match those exposed on ads.x.com.

Possible values include:

  • ACCOUNT_ADMIN: Full access to modify campaigns and view stats, including the ability to add or remove users and change settings
  • AD_MANAGER: Full access to modify campaigns and view stats, but cannot add or remove users or change settings
  • CREATIVE_MANAGER: Access to modify creatives and view previews, but no access to create or modify campaigns
  • CAMPAIGN_ANALYST: Access to view campaigns and view stats, but no access to create or modify campaigns
  • ANALYST (“Organic Analyst” on ads.x.com): Access to view organic analytics and audience insights, but no access to create, modify, or view campaigns
  • PARTNER_AUDIENCE_MANAGER: API-only access to view and modify data partner audiences, but no access to campaigns, creatives, or other audience types.

In addition, the TWEET_COMPOSER permission indicates that the authenticated user can create nullcasted (or “Promoted-only”) Tweets on behalf of the advertiser. This is only available for users with ACCOUNT_ADMIN, AD_MANAGER, or CREATIVE_MANAGER access.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/authenticated_user_access

Parameters

None

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/authenticated_user_access

Example Response

    {
      "data": {
        "user_id": "2417045708",
        "permissions": [
          "ACCOUNT_ADMIN",
          "TWEET_COMPOSER"
        ]
      },
      "request": {
        "params": {
          "account_id": "18ce54d4x5t"
        }
      }
    }

Bidding Rules

GET bidding_rules

Retrieve the bidding rules for some or all currencies. The response will indicate the minimum and maximum CPE (cost-per-engagement) bids.

While these bidding rules change rarely, it is suggested that your systems refresh from these endpoints at least monthly.

Resource URL

https://ads-api.x.com/12/bidding_rules

Parameters

NameDescription
currency
optional
The type of a currency to filter results by, identified using ISO-4217. This is a three-letter string “USD” or “EUR”. Omit this parameter to retrieve all bidding rules. associated with the authenticating user.

Type: string

Example: USD

Example Request

GET https://ads-api.x.com/12/bidding_rules?currency=USD

Example Response

    {
      "request": {
        "params": {
          "currency": "USD"
        }
      },
      "data_type": "bidding_rule",
      "data": [
        {
          "currency": "USD",
          "minimum_cpe_bid_local_micro": 10000,
          "maximum_cpe_bid_local_micro": 1000000000,
          "minimum_denomination": 10000
        }
      ],
      "total_count": 1
    }

Campaigns

GET accounts/:account_id/campaigns

Retrieve details for some or all campaigns associated with the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/campaigns

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
campaign_ids
optional
Scope the response to just the desired campaigns by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: 8wku2
count
optional
Specifies the number of records to try and retrieve per distinct request.

Type: int

Default: 200
Min, Max: 1, 1000
cursor
optional
Specifies a cursor to get the next page of results. See Pagination for more information.

Type: string

Example: 8x7v00oow
funding_instrument_ids
optional
Scope the response to just the campaigns under specific funding instruments by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: lygyi
q
optional
An optional query to scope resource by name.

Type: string

Min, Max length: 1, 255
sort_by
optional
Sorts by supported attribute in ascending or descending order. See Sorting for more information.

Type: string

Example: created_at-asc
with_deleted
optional
Include deleted results in your request.

Type: boolean

Default: false
Possible values: true, false
with_draft
optional
Include draft campaigns results in your request.

Type: boolean

Default: false
Possible values: true, false
with_total_count
optional
Include the total_count response attribute.

Note: This parameter and cursor are exclusive.

Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes.

Type: boolean

Default: false
Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns?campaign_ids=8wku2

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "campaign_ids": [
            "8wku2"
          ]
        }
      },
      "next_cursor": null,
      "data": [
        {
          "name": "test",
          "budget_optimization": "CAMPAIGN",
          "reasons_not_servable": [
            "PAUSED_BY_ADVERTISER",
            "INCOMPLETE"
          ],
          "servable": false,
          "purchase_order_number": null,
          "effective_status": "UNKNOWN",
          "daily_budget_amount_local_micro": 10000000,
          "funding_instrument_id": "lygyi",
          "duration_in_days": null,
          "standard_delivery": false,
          "total_budget_amount_local_micro": null,
          "id": "8wku2",
          "entity_status": "PAUSED",
          "frequency_cap": null,
          "currency": "USD",
          "created_at": "2022-06-03T21:38:07Z",
          "updated_at": "2022-06-03T21:38:07Z",
          "deleted": false
        }
      ]
    }

GET accounts/:account_id/campaigns/:campaign_id

Retrieve a specific campaign associated with the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/campaigns/:campaign_id

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
campaign_id
required
A reference to the campaign you are operating with in the request.

Type: string

Example: 8wku2
with_deleted
optional
Include deleted results in your request.

Type: boolean

Default: false
Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns/8wku2

Example Response

    {
      "request": {
        "params": {
          "campaign_id": "8wku2",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "name": "test",
        "budget_optimization": "CAMPAIGN",
        "reasons_not_servable": [
          "PAUSED_BY_ADVERTISER",
          "INCOMPLETE"
        ],
        "servable": false,
        "purchase_order_number": null,
        "effective_status": "UNKNOWN",
        "daily_budget_amount_local_micro": 10000000,
        "funding_instrument_id": "lygyi",
        "duration_in_days": null,
        "standard_delivery": false,
        "total_budget_amount_local_micro": null,
        "id": "8wku2",
        "entity_status": "PAUSED",
        "frequency_cap": null,
        "currency": "USD",
        "created_at": "2022-06-03T21:38:07Z",
        "updated_at": "2022-06-03T21:38:07Z",
        "deleted": false
      }
    }

POST accounts/:account_id/campaigns

Create a new campaign associated with the current account.

Note: There is a default limit of 200 active campaigns per account. However, there is no limit to the number of inactive campaigns. This limit can be raised to 8,000 active campaigns. To enable the higher limit, the advertiser must make the request to their X Account Manager.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/campaigns

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
funding_instrument_id
required
The identifier for the funding instrument to create the campaign under.

Type: string

Example: lygyi
name
required
The name for the campaign. Maximum length: 255 characters.

Type: string

Example: demo
budget_optimization
optional
Select the type of budget optimization to be applied

Type: enum

Default: CAMPAIGN
Possible values: CAMPAIGN, LINE_ITEM
daily_budget_amount_local_micro
sometimes required
The daily budget amount to be allocated to the campaign. The currency associated with the specified funding instrument will be used. For USD, $5.50 is represented as 5500000.

Note: This should be less than or equal to the total_budget_amount_local_micro and is required for most Funding Insturment types.

Type: long

Example: 5500000
entity_status
optional
The campaign status.

Type: enum

Default: ACTIVE
Possible values: ACTIVE, DRAFT, PAUSED
purchase_order_number
optional
The booking reference number. Use this field to help with invoice reconciliation. Maximum length: 50 characters.

Type: string

Example: D00805843
standard_delivery
optional
Enable standard or accelerated delivery. See Budget Pacing for more information on standard versus accelerated delivery. Only available when budget_optimization is set to CAMPAIGN.

Type: boolean

Default: true
Possible values: true, false
total_budget_amount_local_micro
optional
The total budget amount to be allocated to the campaign. The currency associated with the specified funding instrument will be used. For USD, $37.50 is represented as 37500000.

Type: long

Example: 37500000

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns?funding_instrument_id=lygyi&name=demo&daily_budget_amount_local_micro=140000000&entity_status=PAUSED&budget_optimization=CAMPIAGN&standard_delivery=false

Example Response

    {
      "request": {
        "params": {
          "name": "demo",
          "budget_optimization": "CAMPAIGN",
          "daily_budget_amount_local_micro": 140000000,
          "funding_instrument_id": "lygyi",
          "standard_delivery": false,
          "entity_status": "PAUSED",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "name": "demo",
        "budget_optimization": "CAMPAIGN",
        "reasons_not_servable": [
          "PAUSED_BY_ADVERTISER",
          "INCOMPLETE"
        ],
        "servable": false,
        "purchase_order_number": null,
        "effective_status": "UNKNOWN",
        "daily_budget_amount_local_micro": 140000000,
        "funding_instrument_id": "lygyi",
        "duration_in_days": null,
        "standard_delivery": false,
        "total_budget_amount_local_micro": null,
        "id": "hwtbm",
        "entity_status": "PAUSED",
        "frequency_cap": null,
        "currency": "USD",
        "created_at": "2022-06-03T21:38:07Z",
        "updated_at": "2022-06-03T21:38:07Z",
        "deleted": false
      }
    }

POST batch/accounts/:account_id/campaigns

Allows the batch creation of new campaigns with a single request.

Batch Requests

  • The current maximum batch size is 40.
  • All parameters are sent in the request body and a Content-Type of application/json is required.
  • Batch requests fail or succeed together as a group and all API responses for both error and success preserve the item order of the initial request.

Batch Responses

Batch API responses return an ordered collection of items. Otherwise, they are identical in structure to their corresponding single-item endpoints.

Batch Errors

  • Request-level errors (eg. max batch size exceeded) are shown in the response under the errors object.
  • Item-level errors (eg. missing required campaign parameter) are shown in the response under the operation_errors object.

Resource URL

https://ads-api.x.com/12/batch/accounts/:account_id/campaigns

Parameters

NameDescription
operation_type
required
The per item operation type being performed.

Type: enum

Possible values: Create, Delete, Update
params
required
A JSON object containing all the parameters for the campaign objects. For a list of required and optional campaign parameters, see here.

Example Request

POST 'Content-Type: application/json' https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/campaigns

    [
      {
        "operation_type":"Create",
        "params":{
          "name":"batch campaigns",
          "funding_instrument_id":"lygyi",
          "daily_budget_amount_local_micro":140000000,
          "entity_status":"PAUSED",
          "budget_optimization":"CAMPAIGN"
        }
      }
    ]

Example Response

    {
      "data": [
        {
          "name": "batch campaigns",
          "budget_optimization": "CAMPAIGN",
          "reasons_not_servable": [
            "PAUSED_BY_ADVERTISER",
            "INCOMPLETE"
          ],
          "servable": false,
          "purchase_order_number": null,
          "effective_status": "UNKNOWN",
          "daily_budget_amount_local_micro": 140000000,
          "funding_instrument_id": "lygyi",
          "duration_in_days": null,
          "standard_delivery": false,
          "total_budget_amount_local_micro": null,
          "id": "8yn7m",
          "entity_status": "PAUSED",
          "frequency_cap": null,
          "currency": "USD",
          "created_at": "2022-06-03T21:38:07Z",
          "updated_at": "2022-06-03T21:38:07Z",
          "deleted": false
        }
      ],
      "request": [
        {
          "params": {
            "name": "batch campaigns",
            "funding_instrument_id": "lygyi",
            "daily_budget_amount_local_micro": 140000000,
            "entity_status": "PAUSED",
            "budget_optimization":"CAMPAIGN",
            "account_id": "18ce54d4x5t"
          },
          "operation_type": "Create"
        }
      ]
    }

PUT accounts/:account_id/campaigns/:campaign_id

Update the specified campaign associated with the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/campaigns/:campaign_id

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
campaign_id
required
A reference to the campaign you are operating with in the request.

Type: string

Example: 8wku2
budget_optimization
optional
Select the type of budget optimization to be applied

Type: enum

Default: CAMPAIGN
Possible values: CAMPAIGN, LINE_ITEM
daily_budget_amount_local_micro
optional
The daily budget amount to be allocated to the campaign. The currency associated with the specified funding instrument will be used. For USD, $5.50 is represented as 5500000. When not provided the campaign will spend evenly based upon total budget and for duration of campaign flight time.

Note: This should be less than or equal to the total_budget_amount_local_micro.

Type: long

Example: 5500000
entity_status
optional
The campaign status.

Type: enum

Possible values: ACTIVE, PAUSED
name
optional
The name for the campaign. Maximum length: 255 characters.

Type: string

Example: demo
purchase_order_number
optional
The booking reference number. Use this field to help with invoice reconciliation. Maximum length: 50 characters.

Type: string

Example: D00805843
standard_delivery
optional
Enable standard or accelerated delivery. See Budget Pacing for more information on standard versus accelerated delivery. Only available when budget_optimization is set to CAMPAIGN.

Type: boolean

Default: true
Possible values: true, false
total_budget_amount_local_micro
optional
The total budget amount to be allocated to the campaign. The currency associated with the specified funding instrument will be used. For USD, $37.50 is represented as 37500000.

Type: long

Example: 140000000

Example Request

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns/8wku2?total_budget_amount_local_micro=140000000

Example Response

    {
      "request": {
        "params": {
          "campaign_id": "8wku2",
          "daily_budget_amount_local_micro": 140000000,
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "name": "test",
        "budget_optimization": "CAMPAIGN",
        "reasons_not_servable": [
          "PAUSED_BY_ADVERTISER",
          "INCOMPLETE"
        ],
        "servable": false,
        "purchase_order_number": null,
        "effective_status": "UNKNOWN",
        "daily_budget_amount_local_micro": 140000000,
        "funding_instrument_id": "lygyi",
        "duration_in_days": null,
        "standard_delivery": false,
        "total_budget_amount_local_micro": null,
        "id": "8wku2",
        "entity_status": "PAUSED",
        "frequency_cap": null,
        "currency": "USD",
        "created_at": "2022-06-03T21:38:07Z",
        "updated_at": "2022-06-03T21:53:54Z",
        "deleted": false
      }
    }

DELETE accounts/:account_id/campaigns/:campaign_id

Delete the specified campaign belonging to the current account.

Note: Deleting a campaign is not reversible and subsequent attempts to delete the resource will return HTTP 404.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/campaigns/:campaign_id

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
campaign_id
required
A reference to the campaign you are operating with in the request.

Type: string

Exampple: 8yn7m

Example Request

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns/8yn7m

Example Response

    {
      "request": {
        "params": {
          "campaign_id": "8yn7m",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "name": "test",
        "budget_optimization": "CAMPAIGN",
        "reasons_not_servable": [],
        "servable": null,
        "purchase_order_number": null,
        "effective_status": "RUNNING",
        "daily_budget_amount_local_micro": 140000000,
        "funding_instrument_id": "lygyi",
        "duration_in_days": null,
        "standard_delivery": false,
        "total_budget_amount_local_micro": null,
        "id": "8yn7m",
        "entity_status": "PAUSED",
        "frequency_cap": null,
        "currency": "USD",
        "created_at": "2022-06-03T21:38:07Z",
        "updated_at": "2022-06-03T21:56:35Z",
        "deleted": true
      }
    }

Content Categories

GET content_categories

Request the valid content categories to be set as targeting_criteria for a line item.

Each content_category maps to one or more IAB Categories. This can be done by setting the targeting_type to IAB_CATEGORY on the batch targeting_critera endpoint to include the set of corresponding iab_categories returned by the content_categories request. Failure to do so will result in a validation error.

Publisher details for each of these content categories can be retrieved using the GET publishers endpoint.

Additional details can be found in the Video Views Pre-roll Objective Guide.

Resource URL

https://ads-api.x.com/12/content_categories

Parameters

No request parameters

Example Request

GET https://ads-api.x.com/12/content_categories

Example Response

    {
      "request": {
        "params": {}
      },
      "next_cursor": null,
      "data": [
        {
          "name": "Automotive (Cars, Trucks, Racing)",
          "id": "ru",
          "iab_categories": [
            "IAB2"
          ],
          "publishers_in_last_thirty_days": 12,
          "videos_monetized_in_last_thirty_days": 316
        },
        {
          "name": "Comedy",
          "id": "sk",
          "iab_categories": [
            "IAB1-4"
          ],
          "publishers_in_last_thirty_days": 19,
          "videos_monetized_in_last_thirty_days": 174
        },
        {
          "name": "Digital Creators",
          "id": "sl",
          "iab_categories": [
            "IAB25-1"
          ],
          "publishers_in_last_thirty_days": 110,
          "videos_monetized_in_last_thirty_days": 1257
        },
        {
          "name": "Entertainment & Pop Culture",
          "id": "sm",
          "iab_categories": [
            "IAB1-1",
            "IAB1-2",
            "IAB1-3",
            "IAB1-5"
          ],
          "publishers_in_last_thirty_days": 120,
          "videos_monetized_in_last_thirty_days": 3482
        },
        {
          "name": "Financial & Business News",
          "id": "sn",
          "iab_categories": [
            "IAB3",
            "IAB13",
            "IAB21"
          ],
          "publishers_in_last_thirty_days": 29,
          "videos_monetized_in_last_thirty_days": 1461
        },
        {
          "name": "Food & Drink",
          "id": "so",
          "iab_categories": [
            "IAB8-8",
            "IAB8-12",
            "IAB8-17",
            "IAB8-2",
            "IAB8-3",
            "IAB8-7",
            "IAB8-11",
            "IAB8-4",
            "IAB8-14",
            "IAB8-10",
            "IAB8-15",
            "IAB8-13",
            "IAB8-9",
            "IAB8-16",
            "IAB8-6",
            "IAB8-1"
          ],
          "publishers_in_last_thirty_days": 24,
          "videos_monetized_in_last_thirty_days": 516
        },
        {
          "name": "Lifestyle (Fashion, Travel, Wellness)",
          "id": "sp",
          "iab_categories": [
            "IAB16",
            "IAB9-21",
            "IAB9-4",
            "IAB9-25",
            "IAB9-8",
            "IAB4",
            "IAB9-3",
            "IAB9-15",
            "IAB7",
            "IAB6",
            "IAB9-11",
            "IAB9-16",
            "IAB9-7",
            "IAB9-20",
            "IAB9-24",
            "IAB9-17",
            "IAB9-12",
            "IAB9-31",
            "IAB9-27",
            "IAB10",
            "IAB9-10",
            "IAB9-23",
            "IAB9-6",
            "IAB9-18",
            "IAB9-13",
            "IAB9-1",
            "IAB9-28",
            "IAB20",
            "IAB9-5",
            "IAB9-26",
            "IAB22",
            "IAB23",
            "IAB9-9",
            "IAB9-22",
            "IAB18",
            "IAB9-2",
            "IAB9-19",
            "IAB9-14",
            "IAB9-29"
          ],
          "publishers_in_last_thirty_days": 67,
          "videos_monetized_in_last_thirty_days": 2412
        },
        {
          "name": "Music",
          "id": "sq",
          "iab_categories": [
            "IAB1-6"
          ],
          "publishers_in_last_thirty_days": 31,
          "videos_monetized_in_last_thirty_days": 518
        },
        {
          "name": "News & Current Events",
          "id": "sr",
          "iab_categories": [
            "IAB12",
            "IAB14"
          ],
          "publishers_in_last_thirty_days": 125,
          "videos_monetized_in_last_thirty_days": 5507
        },
        {
          "name": "Politics",
          "id": "s4",
          "iab_categories": [
            "IAB11"
          ],
          "publishers_in_last_thirty_days": 19,
          "videos_monetized_in_last_thirty_days": 1402
        },
        {
          "name": "Science & Education",
          "id": "ss",
          "iab_categories": [
            "IAB5",
            "IAB15"
          ],
          "publishers_in_last_thirty_days": 7,
          "videos_monetized_in_last_thirty_days": 132
        },
        {
          "name": "Sports",
          "id": "se",
          "iab_categories": [
            "IAB17"
          ],
          "publishers_in_last_thirty_days": 403,
          "videos_monetized_in_last_thirty_days": 18281
        },
        {
          "name": "Technology",
          "id": "sg",
          "iab_categories": [
            "IAB19"
          ],
          "publishers_in_last_thirty_days": 13,
          "videos_monetized_in_last_thirty_days": 1089
        },
        {
          "name": "Television",
          "id": "sh",
          "iab_categories": [
            "IAB1-7"
          ],
          "publishers_in_last_thirty_days": 58,
          "videos_monetized_in_last_thirty_days": 1307
        },
        {
          "name": "Esports & Video Games",
          "id": "s0",
          "iab_categories": [
            "IAB9-30"
          ],
          "publishers_in_last_thirty_days": 109,
          "videos_monetized_in_last_thirty_days": 1844
        }
      ],
      "total_count": 15
    }

Curated Categories

GET accounts/:account_id/curated_categories

Retrieve a list of available Curated Categories for the given country_codes

Each curated_category is only available in specific countries specified by the country_codes in the response.

Additional details can be found in the Video Views Pre-roll Objective Guide.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/curated_categories

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
country_codes
required
Scope the response to just the desired countries by specifying a comma-separated list of two letter ISO country codes. Up to 200 IDs may be provided.

Type: string

Example: US
cursor
optional
Specifies a cursor to get the next page of results. See Pagination for more information.

Type: string

Example: 8x7v00oow

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/curated_categories?country_codes=US

Example Response

    {
      "request": {
        "params": {
          "country_codes": [
            "US"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "name": "Basketball",
          "description": "Run next to the best of everyday basketball content including college teams, professional teams, and the top sports media handles sharing on and off-season basketball video.",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "20265254",
            "378174762",
            "900368808",
            "18939563",
            "18371803",
            "18360370",
            "770658432928079872",
            "11026952",
            "37085464",
            "16212685",
            "57422635",
            "281669945",
            "7117962",
            "23065057",
            "41688179",
            "29779226",
            "900280416",
            "364460082",
            "902030382",
            "19409270",
            "19077044",
            "18139461",
            "14992591",
            "66753565",
            "667563",
            "16727749",
            "40941404",
            "18481113",
            "791598918",
            "16201775",
            "15900167",
            "45891626",
            "191894553",
            "2181233851",
            "34352904",
            "171483987",
            "454122399",
            "57415242",
            "19263978",
            "902089998",
            "423540866",
            "2715223320",
            "22185437",
            "17292143",
            "55590247",
            "66757066",
            "22642626",
            "41604618",
            "87275465",
            "22643259",
            "32414973",
            "73406718",
            "20346956",
            "413422891",
            "45412765",
            "19537303",
            "459511725",
            "30954864",
            "21308488",
            "18552281",
            "19924520",
            "24903350",
            "851142163",
            "26270913",
            "20444254",
            "26074296",
            "6395222",
            "15537451",
            "28672101",
            "38053254",
            "24925573",
            "19564719",
            "18164425",
            "22815383",
            "20196159"
          ],
          "id": "929wbl6ymlfk",
          "created_at": "2019-11-08T21:12:47Z",
          "updated_at": "2021-03-09T20:36:44Z",
          "videos_monetized_in_last_thirty_days": 2446
        },
        {
          "name": "Gaming Personalities",
          "description": "Run next to the best of everyday gaming content exclusively from a list of some of online gaming’s biggest and most loved digital creators.",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "90779436",
            "268270621",
            "567167802",
            "246596682",
            "474919140",
            "284422688",
            "185909682",
            "4767225325",
            "2559865245",
            "186888760",
            "161418822",
            "141021153",
            "352881953",
            "1117931702",
            "146556805",
            "357294577",
            "234526497",
            "266687361",
            "214201922",
            "9451052",
            "2163885564",
            "2231422037",
            "116952434",
            "399909209",
            "15993650",
            "974356091193741312",
            "210839744",
            "2313002094",
            "159916388",
            "3258981481",
            "231992478",
            "182236262",
            "386884916",
            "22705686",
            "4140881832",
            "995979576",
            "2244953047",
            "311775629",
            "98821255",
            "2733210014",
            "2741078150"
          ],
          "id": "94ngssfrr01x",
          "created_at": "2019-12-02T20:45:12Z",
          "updated_at": "2021-03-09T20:18:13Z",
          "videos_monetized_in_last_thirty_days": 448
        },
        {
          "name": "Baseball",
          "description": "Run next to the best of everyday baseball content including college teams, professional teams, and the top sports media handles sharing major baseball coverage.",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "22016177",
            "22798877",
            "52803520",
            "20710218",
            "423532170",
            "28603812",
            "41144996",
            "22819823",
            "39389304",
            "252273678",
            "123307490",
            "2319354187",
            "41488578",
            "37947138",
            "302066953",
            "159143990",
            "35006336",
            "53178109",
            "40918816",
            "39682297",
            "39397148",
            "39419180",
            "53197137",
            "52863923",
            "21407926",
            "31164229",
            "19607400",
            "39392910",
            "241544156",
            "43024351",
            "37837907",
            "165764237",
            "69117905",
            "87673496",
            "23043294",
            "52824038",
            "52861612",
            "33137450",
            "30008146",
            "39367703",
            "21436663",
            "188575356",
            "40931019",
            "41468683",
            "40927173",
            "172742915"
          ],
          "id": "9lav5usxfmdc",
          "created_at": "2020-05-18T20:20:27Z",
          "updated_at": "2021-03-09T20:37:46Z",
          "videos_monetized_in_last_thirty_days": 190
        },
        {
          "name": "Esports Teams",
          "description": "Run next to the programming from the world’s best esports teams, covering both in-event coverage and other year-round complimentary programming.",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "759527448757215232",
            "61933836",
            "477213534",
            "907193396049182720",
            "895382891408089089",
            "862708050116976640",
            "115038550",
            "3182089458",
            "4131266472",
            "1145702070961496065",
            "2262070855",
            "920664872786059264",
            "1035653581683220481",
            "14229141",
            "1101275970995027968",
            "20734751",
            "1452520626",
            "720303639277928448",
            "2853641871",
            "912696400571486208",
            "874362688939413504",
            "286505380",
            "892808605170245632",
            "875087838613733376",
            "238431491",
            "867053221940011014",
            "964529942",
            "1172506293174710272",
            "535756639",
            "2255226817",
            "1100825469853696000",
            "1122713320086220803",
            "1124064709295128581",
            "899858978418642944",
            "864977592532688896",
            "864476897106898944",
            "862770685445361665",
            "257268592"
          ],
          "id": "9ys3jz3ktreo",
          "created_at": "2020-10-01T20:02:35Z",
          "updated_at": "2021-03-09T20:36:20Z",
          "videos_monetized_in_last_thirty_days": 169
        },
        {
          "name": "Football ",
          "description": "Run next to the best of everyday football content including college teams, professional teams, and the top sports media handles sharing on and off-season football video.",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "21790466",
            "53103297",
            "23642374",
            "817416193854283776",
            "43403778",
            "24179879",
            "26813914",
            "36375662",
            "33587536",
            "180884045",
            "16332223",
            "27902825",
            "180503626",
            "44468807",
            "18336787",
            "818431566",
            "22146282",
            "31126587",
            "40358743",
            "35865630",
            "16347506",
            "72665816",
            "33583496",
            "389038362",
            "36155311",
            "227342532",
            "2151130166",
            "26791995",
            "44666348",
            "24109979",
            "31504542",
            "713143",
            "423536031",
            "25545388",
            "59471027",
            "706923475",
            "19383279",
            "8824902",
            "1655877529",
            "18734310",
            "240734425",
            "17076218",
            "47964412",
            "2802184770",
            "19426729",
            "56443153",
            "23508439",
            "25084916",
            "764347046",
            "19853312",
            "348590880"
          ],
          "id": "8tujg1lvi8sn",
          "created_at": "2019-08-15T20:48:51Z",
          "updated_at": "2021-03-09T20:34:13Z",
          "videos_monetized_in_last_thirty_days": 254
        },
        {
          "name": "Men’s Culture + Lifestyle",
          "description": "Run next to content from a set of handles curated based on their follower profiles to help you reach a majority male audience, including some of the top handles sharing technology, news, and lifestyle content.",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "17764377",
            "61933836",
            "28370738",
            "3224616765",
            "22819823",
            "18927441",
            "734826612684783616",
            "14372486",
            "7157132",
            "15764136",
            "590316679",
            "7302282",
            "895014043932540928",
            "7517222",
            "3489420013",
            "14063426",
            "72665816",
            "214201922",
            "14980903",
            "22199141",
            "21272440",
            "25319414",
            "119593082",
            "4760694445",
            "765905855195803648",
            "238431491",
            "22178780",
            "241544156",
            "25093616",
            "16877611",
            "22146985",
            "368703433",
            "14342661",
            "415605847",
            "2181233851",
            "890891",
            "15764001",
            "614754689",
            "18479513",
            "23508439",
            "348590880"
          ],
          "id": "8tujj1ep7t34",
          "created_at": "2019-08-15T20:49:47Z",
          "updated_at": "2021-03-09T20:39:00Z",
          "videos_monetized_in_last_thirty_days": 1330
        },
        {
          "name": "Women’s Culture + Lifestyle",
          "description": "Run next to content from a set of handles curated based on their follower profiles to help you reach a majority female audience, including some of the top handles sharing pop culture, news, and lifestyle content.",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "23482952",
            "20177423",
            "19074134",
            "15566901",
            "32469566",
            "19784831",
            "16145224",
            "16932962",
            "14934818",
            "29730065",
            "24190981",
            "30278532",
            "15846407",
            "24994219",
            "23993734",
            "40965341",
            "16312576",
            "75094638",
            "549673665",
            "18806753",
            "75306892",
            "1482663290",
            "31181674",
            "971407531972186112",
            "4020532937",
            "25087685",
            "22515362",
            "80943051",
            "19247844",
            "15279429",
            "16824090",
            "20710809",
            "979831113655996416",
            "32432308",
            "19472585",
            "25589776",
            "739963476370673665",
            "20188834",
            "926269727663673349"
          ],
          "id": "8tujl1p3yn0g",
          "created_at": "2019-08-15T20:50:24Z",
          "updated_at": "2021-03-09T20:17:53Z",
          "videos_monetized_in_last_thirty_days": 1365
        },
        {
          "name": "Light-Hearted",
          "description": "Run next to a list of handles curated for the volume of positive, feel-good content and conversation they’ve consistently generated on X.",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "20177423",
            "22449367",
            "9695312",
            "19074134",
            "4805771380",
            "32469566",
            "1212860112047460352",
            "16402507",
            "16932962",
            "14934818",
            "17446621",
            "29730065",
            "15846407",
            "1604444052",
            "180066380",
            "16312576",
            "549673665",
            "18806753",
            "16211434",
            "545336345",
            "971407531972186112",
            "4020532937",
            "833612154",
            "22515362",
            "20710809",
            "32432308",
            "774311630",
            "3073349892",
            "926269727663673349"
          ],
          "id": "9fg8gmz96qdg",
          "created_at": "2020-03-20T19:37:44Z",
          "updated_at": "2021-03-09T19:57:40Z",
          "videos_monetized_in_last_thirty_days": 1395
        },
        {
          "name": "Soccer",
          "description": "Run next to the best of everyday soccer content including college teams, professional teams, and the top sports media handles sharing major soccer coverage.",
          "country_codes": [
            "US"
          ],
          "publisher_user_ids": [
            "21677316",
            "20636347",
            "4704552148",
            "14573900",
            "22556296",
            "1415791555",
            "107146095",
            "17288520",
            "213474069",
            "17493398",
            "44990136",
            "452155423",
            "17744542",
            "16303450",
            "2841146601",
            "2413176055",
            "29739264",
            "38580532",
            "953476292913106945",
            "27092557",
            "86356439",
            "34613288",
            "3170659367",
            "119593082",
            "73412535",
            "627586654",
            "15891449",
            "23011345",
            "96951800",
            "15997022",
            "16960789",
            "21919642",
            "102965285",
            "17224076",
            "36432200",
            "1410055968"
          ],
          "id": "9ddrgesiap6o",
          "created_at": "2020-02-28T22:43:26Z",
          "updated_at": "2021-01-26T17:54:55Z",
          "videos_monetized_in_last_thirty_days": 421
        }
      ],
      "total_count": 9
    }

GET accounts/:account_id/curated_categories/:curated_category_id

Retrieve details for a specific curated_category_id

Each curated_category is only available in specific countries specified by the country_codes in the response.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/curated_categories/:curated_category_id

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
curated_category_id
required
A reference to the Curated Category you are operating with in the request.

Type: string

Example: 9ddrgesiap6o

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/curated_categories/9ddrgesiap6o

Example Response

    {
      "request": {
        "params": {
          "id": "9ddrgesiap6o",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "name": "Soccer",
        "description": "Run next to the best of everyday soccer content including college teams, professional teams, and the top sports media handles sharing major soccer coverage.",
        "country_codes": [],
        "publisher_user_ids": [
          "21677316",
          "20636347",
          "4704552148",
          "14573900",
          "22556296",
          "1415791555",
          "107146095",
          "17288520",
          "213474069",
          "17493398",
          "44990136",
          "452155423",
          "17744542",
          "16303450",
          "2841146601",
          "2413176055",
          "29739264",
          "38580532",
          "953476292913106945",
          "27092557",
          "86356439",
          "34613288",
          "3170659367",
          "119593082",
          "73412535",
          "627586654",
          "15891449",
          "23011345",
          "96951800",
          "15997022",
          "16960789",
          "21919642",
          "102965285",
          "17224076",
          "36432200",
          "1410055968"
        ],
        "id": "9ddrgesiap6o",
        "created_at": "2020-02-28T22:43:26Z",
        "updated_at": "2021-01-26T17:54:55Z",
        "videos_monetized_in_last_thirty_days": 421
      }
    }

Features

GET accounts/:account_id/features

Retrieve the collection of granted features accessible by this ads account. Features are indicated by a descriptive feature key and are only exposed on this endpoint if they are introduced in beta or an otherwise limited release and are available in the Ads API. Features that do not meet this criteria will not be exposed on this endpoint.

Note: This endpoint serves to aid Ads API ecosystem development by improving visibility into client access to beta releases. API developers can not request access to features on behalf of an advertiser. These requests can only be made by the advertiser to their X account manager.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/features

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
feature_keys
optional
An optional parameter that enables querying for a specific feature key. Requests may include multiple comma-separated keys.

Note: Only the features that are accessible by this account will be included in the response.

Type: enum

Possible values: REACH_AND_FREQUENCY_ANALYTICS, REACH_FREQUENCY_CAP, WEBSITE_CLICKS_CPM_BILLING

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/features

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t"
        }
      },
      "data": [
        "CITY_TARGETING",
        "CONVERSATION_CARD",
        "PROMOTED_MEDIA_POLLS",
        "REACH_AND_FREQUENCY_ANALYTICS",
        "REACH_FREQUENCY_CAP",
        "UNIVERSAL_LOOKALIKE"
      ]
    }

POST accounts/:account_id/features

SANDBOX ONLY

Add a feature to a sandbox account.

The up to date list of account features may be retrieved via the GET accounts/:account_id/features endpoint.

Resource URL

https://ads-api-sandbox.x.com/12/accounts/:account_id/features

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: gq180y
feature_keys
required
A comma-separated list of account features to add to the account.

Type: enum

Possible values: AGE_TARGETING, ALLOW_SKIPPABLE_VIDEOS_FOR_PREROLL_VIEWS_OBJECTIVE, AWARENESS_OBJECTIVE, BRAND_TPN, CHARGE_FOR_GOOD_CLICK, CONVERSATION_CARD, CONVERSATION_CARD_FOUR_OPTIONS, CONVERSATION_CARD_UNLOCK, CPI_CHARGING, DIRECT_MESSAGE_CARD, DR_TAP, ENGAGER_RETARGETING, EVENT_TARGETING, INSTALLED_APP_CATEGORY_TARGETING, MOBILE_CONVERSION_TRANSACTION_VALUE, OPTIMIZED_ACTION_BIDDING, REACH_AND_FREQUENCY_ANALYTICS, REACH_FREQUENCY_CAP, VALIDATED_AGE_TARGETING, VIDEO_VIEWS_MIDROLL_OBJECTIVE, PREROLL_VIEWS_OBJECTIVE, VIDEO_APP_DOWNLOAD_CARD

Example Request

POST https://ads-api-sandbox.x.com/12/accounts/gq180y/features?feature_keys=VALIDATED_AGE_TARGETING

Example Response

    {
      "request": {
        "params": {
          "account_id": "gq180y",
          "feature_keys": [
            "VALIDATED_AGE_TARGETING"
          ]
        }
      },
      "data": [
        "ALLOW_SKIPPABLE_VIDEOS_FOR_PREROLL_VIEWS_OBJECTIVE",
        "AWARENESS_OBJECTIVE",
        "CPI_CHARGING",
        "EVENT_TARGETING",
        "INSTALLED_APP_CATEGORY_TARGETING",
        "MOBILE_CONVERSION_TRANSACTION_VALUE",
        "OPTIMIZED_ACTION_BIDDING",
        "VALIDATED_AGE_TARGETING",
        "VIDEO_APP_DOWNLOAD_CARD"
      ]
    }

DELETE accounts/:account_id/features

SANDBOX ONLY

Remove a feature from a sandbox account.

The up to date list of account features may be retrieved via the GET accounts/:account_id/features endpoint.

Resource URL

https://ads-api-sandbox.x.com/12/accounts/:account_id/features

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: gq180y
feature_keys
required
A comma-separated list of account features to remove from the account.

Type: enum

Possible values: AGE_TARGETING, ALLOW_SKIPPABLE_VIDEOS_FOR_PREROLL_VIEWS_OBJECTIVE, AWARENESS_OBJECTIVE, BRAND_TPN, CHARGE_FOR_GOOD_CLICK, CONVERSATION_CARD, CONVERSATION_CARD_FOUR_OPTIONS, CONVERSATION_CARD_UNLOCK, CPI_CHARGING, DIRECT_MESSAGE_CARD, DR_TAP, ENGAGER_RETARGETING, EVENT_TARGETING, INSTALLED_APP_CATEGORY_TARGETING, MOBILE_CONVERSION_TRANSACTION_VALUE, OPTIMIZED_ACTION_BIDDING, REACH_AND_FREQUENCY_ANALYTICS, REACH_FREQUENCY_CAP, VALIDATED_AGE_TARGETING, VIDEO_VIEWS_MIDROLL_OBJECTIVE, PREROLL_VIEWS_OBJECTIVE, VIDEO_APP_DOWNLOAD_CARD

Example Request

DELETE https://ads-api-sandbox.x.com/12/accounts/gq180y/features?feature_keys=PREROLL_VIEWS_OBJECTIVE

Example Response

    {
      "request": {
        "params": {
          "account_id": "gq180y",
          "feature_keys": [
            "PREROLL_VIEWS_OBJECTIVE"
          ]
        }
      },
      "data": [
        "CPI_CHARGING",
        "EVENT_TARGETING",
        "INSTALLED_APP_CATEGORY_TARGETING",
        "MOBILE_CONVERSION_TRANSACTION_VALUE",
        "OPTIMIZED_ACTION_BIDDING",
        "VIDEO_APP_DOWNLOAD_CARD"
      ]
    }

Funding Instruments

GET accounts/:account_id/funding_instruments

Retrieve details for some or all funding instruments associated with the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/funding_instruments

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
count
optional
Specifies the number of records to try and retrieve per distinct request.

Type: int

Default: 200
Min, Max: 1, 1000
cursor
optional
Specifies a cursor to get the next page of results. See Pagination for more information.

Type: string

Example: 8x7v00oow
funding_instrument_ids
optional
Scope the response to just the desired funding instruments by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: lygyi
sort_by
optional
Sorts by supported attribute in ascending or descending order. See Sorting for more information.

Type: string

Example: created_at-asc
with_deleted
optional
Include deleted results in your request.

Type: boolean

Default: false
Possible values: true, false
with_total_count
optional
Include the total_count response attribute.

Note: This parameter and cursor are exclusive.

Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes.

Type: boolean

Default: false
Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/funding_instruments

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "start_time": "2016-07-22T04:24:04Z",
          "description": "Visa ending in 0650",
          "credit_limit_local_micro": 200000000,
          "end_time": null,
          "id": "lygyi",
          "entity_status": "ACTIVE",
          "account_id": "18ce54d4x5t",
          "reasons_not_able_to_fund": [],
          "io_header": null,
          "currency": "USD",
          "funded_amount_local_micro": 645940000,
          "created_at": "2016-07-22T04:24:04Z",
          "type": "CREDIT_CARD",
          "able_to_fund": true,
          "updated_at": "2017-04-05T00:25:13Z",
          "credit_remaining_local_micro": null,
          "deleted": false
        }
      ]
    }

GET accounts/:account_id/funding_instruments/:funding_instrument_id

Retrieve a specific funding instrument associated with the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/funding_instruments/:id

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
funding_instrument_id
required
A reference to the funding instrument you are operating with in the request.

Type: string

Example: lygyi
with_deleted
optional
Include deleted results in your request.

Type: boolean

Default: false
Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/funding_instruments/lygyi

Example Response

    {
      "request": {
        "params": {
          "funding_instrument_id": "lygyi",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "start_time": "2016-07-22T04:24:04Z",
        "description": "Visa ending in 0650",
        "credit_limit_local_micro": 200000000,
        "end_time": null,
        "id": "lygyi",
        "entity_status": "ACTIVE",
        "account_id": "18ce54d4x5t",
        "reasons_not_able_to_fund": [],
        "io_header": null,
        "currency": "USD",
        "funded_amount_local_micro": 645940000,
        "created_at": "2016-07-22T04:24:04Z",
        "type": "CREDIT_CARD",
        "able_to_fund": true,
        "updated_at": "2017-04-05T00:25:13Z",
        "credit_remaining_local_micro": null,
        "deleted": false
      }
    }

POST accounts/:account_id/funding_instruments

SANDBOX ONLY

Create a funding instrument in the sandbox environment.

There is no risk of incurring costs while using a sandbox funding instrument.

Resource URL

https://ads-api-sandbox.x.com/12/accounts/:account_id/funding_instruments

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: gq1844
currency
required
The currency, expressed in ISO-4217.

Type: string

Example: USD
start_time
required
The date for the funding instrument to become active and usable, expressed in ISO 8601.

Type: string

Example: 2017-05-19T07:00:00Z
type
required
The type of funding instrument to create.

Type: enum

Possible values: AGENCY_CREDIT_LINE, CREDIT_CARD, CREDIT_LINE, INSERTION_ORDER, PARTNER_MANAGED
end_time
sometimes required
The date for the funding instrument to become inactive, expressed in ISO 8601.

Type: string

Example: 2017-05-26T07:00:00Z
credit_limit_local_micro
optional
The total credit available against this funding instrument.

Note: Only applicable to some funding instrument types.

Type: long

Example: 37500000
funded_amount_local_micro
optional
The total budget amount allocated to this funding instrument.

Note: Only applicable to some funding instrument types.

Type: long

Example: 37500000

Example Request

POST https://ads-api-sandbox.x.com/12/accounts/gq1844/funding_instruments?currency=USD&start_time=2017-07-10T00:00:00Z&type=INSERTION_ORDER&end_time=2018-01-10T00:00:00Z&funded_amount_local_micro=140000000000

Example Response

    {
      "data": {
        "start_time": "2017-07-10T00:00:00Z",
        "description": "(no payment method has been set up yet)",
        "credit_limit_local_micro": null,
        "end_time": "2018-01-10T00:00:00Z",
        "id": "hxtet",
        "entity_status": "ACTIVE",
        "account_id": "gq1844",
        "reasons_not_able_to_fund": [],
        "io_header": null,
        "currency": "USD",
        "funded_amount_local_micro": 140000000000,
        "created_at": "2017-09-09T05:23:28Z",
        "type": "INSERTION_ORDER",
        "able_to_fund": true,
        "updated_at": "2017-09-09T05:23:28Z",
        "credit_remaining_local_micro": null,
        "deleted": false
      },
      "request": {
        "params": {
          "start_time": "2017-07-10T00:00:00Z",
          "end_time": "2018-01-10T00:00:00Z",
          "account_id": "gq1844",
          "currency": "USD",
          "funded_amount_local_micro": 140000000000,
          "type": "INSERTION_ORDER"
        }
      }
    }

DELETE accounts/:account_id/funding_instruments/:funding_instrument_id

SANDBOX ONLY

Delete a funding instrument in the sandbox environment.

Resource URL

https://ads-api-sandbox.x.com/12/accounts/:account_id/funding_instruments/:funding_instrument_id

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: gq1844
funding_instrument_id
required
A reference to the funding instrument you are operating with in the request.

Type: string

Exampple: hxt82

Example Request

DELETE https://ads-api-sandbox.x.com/12/accounts/gq1844/funding_instruments/hxt82

Example Response

    {
      "data": {
        "start_time": "2017-08-30T19:23:47Z",
        "description": "(no payment method has been set up yet)",
        "credit_limit_local_micro": 500000000,
        "end_time": null,
        "id": "hxt82",
        "entity_status": "ACTIVE",
        "account_id": "gq1844",
        "reasons_not_able_to_fund": [
          "DELETED"
        ],
        "io_header": null,
        "currency": "USD",
        "funded_amount_local_micro": null,
        "created_at": "2017-08-30T19:23:47Z",
        "type": "CREDIT_CARD",
        "able_to_fund": false,
        "updated_at": "2017-09-09T02:08:30Z",
        "credit_remaining_local_micro": null,
        "deleted": true
      },
      "request": {
        "params": {
          "funding_instrument_id": "hxt82",
          "account_id": "gq1844"
        }
      }
    }

IAB Categories

GET iab_categories

Request the valid app categories for ad groups (line_items).

Resource URL

https://ads-api.x.com/12/iab_categories

Parameters

NameDescription
count
optional
Specifies the number of records to try and retrieve per distinct request.

Type: int

Default: 200
Min, Max: 1, 1000
cursor
optional
Specifies a cursor to get the next page of categories. See Pagination for more information.

Type: string

Example: gc-ddf4a
with_total_count
optional
Include the total_count response attribute.

Note: This parameter and cursor are exclusive.

Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes.

Type: boolean

Default: false
Possible values: true, false

Example Request

GET https://ads-api.x.com/12/iab_categories?count=2

Example Response

    {
      "data": [
        {
          "id": "IAB1",
          "parent_id": null,
          "name": "Arts & Entertainment"
        },
        {
          "id": "IAB1-1",
          "parent_id": "IAB1",
          "name": "Books & Literature"
        }
      ],
      "next_cursor": "uxa8",
      "request": {
        "params": {
          "count": 2
        }
      }
    }

Line Items

GET accounts/:account_id/line_items

Retrieve details for some or all line items associated with the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/line_items

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
campaign_ids
optional
Scope the response to just the line items under specific campaigns by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: 8gdx6
count
optional
Specifies the number of records to try and retrieve per distinct request.

Type: int

Default: 200
Min, Max: 1, 1000
cursor
optional
Specifies a cursor to get the next page of results. See Pagination for more information.

Type: string

Example: 8x7v00oow
funding_instrument_ids
optional
Scope the response to just the line items under specific funding instruments by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: lygyi
line_item_ids
optional
Scope the response to just the desired line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: 8v7jo
q
optional
An optional query to scope resource by name.

Type: string

Min, Max length: 1, 255
sort_by
optional
Sorts by supported attribute in ascending or descending order. See Sorting for more information.

Type: string

Example: created_at-asc
with_deleted
optional
Include deleted results in your request.

Type: boolean

Default: false
Possible values: true, false
with_draft
optional
Include draft campaigns results in your request.

Type: boolean

Default: false
Possible values: true, false
with_total_count
optional
Include the total_count response attribute.

Note: This parameter and cursor are exclusive.

Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes.

Type: boolean

Default: false
Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items?line_item_ids=itttx

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "line_item_ids": [
            "itttx"
          ]
        }
      },
      "next_cursor": null,
      "data": [
        {
          "advertiser_user_id": "756201191646691328",
          "name": "li-18",
          "placements": [
            "ALL_ON_TWITTER"
          ],
          "start_time": "2021-02-16T00:00:00Z",
          "bid_amount_local_micro": 320000,
          "advertiser_domain": null,
          "target_cpa_local_micro": null,
          "primary_web_event_tag": null,
          "goal": "ENGAGEMENT",
          "daily_budget_amount_local_micro": null,
          "product_type": "PROMOTED_TWEETS",
          "end_time": null,
          "funding_instrument_id": "lygyi",
          "bid_strategy": "MAX",
          "duration_in_days": null,
          "standard_delivery": null,
          "total_budget_amount_local_micro": null,
          "objective": "ENGAGEMENTS",
          "id": "itttx",
          "entity_status": "PAUSED",
          "automatic_tweet_promotion": null,
          "frequency_cap": null,
          "android_app_store_identifier": null,
          "categories": [],
          "currency": "USD",
          "pay_by": "ENGAGEMENT",
          "created_at": "2021-02-23T23:37:54Z",
          "ios_app_store_identifier": null,
          "updated_at": "2022-06-01T02:01:18Z",
          "campaign_id": "f4z6x",
          "creative_source": "MANUAL",
          "deleted": false
        }
      ]
    }

GET accounts/:account_id/line_items/:line_item_id

Retrieve a specific line item associated with the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/line_items/:line_item_id

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
line_item_id
required
A reference to the line item you are operating with in the request.

Type: string

Example: 8v7jo
with_deleted
optional
Include deleted results in your request.

Type: boolean

Default: false
Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items/itttx

Example Response

    {
      "request": {
        "params": {
          "line_item_id": "itttx",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "advertiser_user_id": "756201191646691328",
        "name": "li-18",
        "placements": [
          "ALL_ON_TWITTER"
        ],
        "start_time": "2021-02-16T00:00:00Z",
        "bid_amount_local_micro": 320000,
        "advertiser_domain": null,
        "target_cpa_local_micro": null,
        "primary_web_event_tag": null,
        "goal": "ENGAGEMENT",
        "daily_budget_amount_local_micro": null,
        "product_type": "PROMOTED_TWEETS",
        "end_time": null,
        "funding_instrument_id": "lygyi",
        "bid_strategy": "MAX",
        "duration_in_days": null,
        "standard_delivery": null,
        "total_budget_amount_local_micro": null,
        "objective": "ENGAGEMENTS",
        "id": "itttx",
        "entity_status": "PAUSED",
        "automatic_tweet_promotion": null,
        "frequency_cap": null,
        "android_app_store_identifier": null,
        "categories": [],
        "currency": "USD",
        "pay_by": "ENGAGEMENT",
        "created_at": "2021-02-23T23:37:54Z",
        "ios_app_store_identifier": null,
        "updated_at": "2022-06-01T02:01:18Z",
        "campaign_id": "f4z6x",
        "creative_source": "MANUAL",
        "deleted": false
      }
    }

POST accounts/:account_id/line_items

Create a line item associated with the specified campaign belonging to the current account.

All line items within a campaign must be of the same product_type and objective.

When using the PROMOTED_ACCOUNT product type, associating a Tweet with the line_item will add timeline placements on mobile in addition to the standard PROMOTED_ACCOUNT placement.

Setting either android_app_store_identifier or ios_app_store_identifier will automatically add the targeting criteria for the line item matching the mobile app being promoted; for example, passing in ios_app_store_identifier would add PLATFORM targeting criteria for iOS.

Note: There is a limit of 100 line items per campaign and 256 active line items across all campaigns.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/line_items

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
campaign_id
required
The identifier for the campaign to create the line item under.

Type: string

Example: 8slvg
end_time
required
The time, expressed in ISO 8601, that the line item will stop serving.

Type: string

Example: 2017-10-05T00:00:00Z
objective
required
The campaign objective for this line item.

Type: enum

Possible values: APP_ENGAGEMENTS, APP_INSTALLS, REACH, FOLLOWERS, ENGAGEMENTS, VIDEO_VIEWS, PREROLL_VIEWS, WEBSITE_CLICKS
placements
required
The placement location(s) for this line item to display in. Specify a comma-separated list of placement values.

Type: enum

Possible values: ALL_ON_TWITTER, PUBLISHER_NETWORK, TAP_BANNER, TAP_FULL, TAP_FULL_LANDSCAPE, TAP_NATIVE, TAP_MRECT,TWITTER_PROFILE, TWITTER_REPLIES, TWITTER_SEARCH, TWITTER_TIMELINE
product_type
required
The type of promoted product that this line item will contain.

Type: enum

Possible values: MEDIA, PROMOTED_ACCOUNT, PROMOTED_TWEETS
start_time
required
The time, expressed in ISO 8601, that the line item will begin serving.

Type: string

Example: 2017-07-05T00:00:00Z
advertiser_domain
sometimes required
The website domain for this advertiser, without the protocol specification.

Note: Required when the line item’s placement is set to PUBLISHER_NETWORK.

Type: string

Example: x.com
android_app_store_identifier
sometimes required
The Google App Store identifier for promoted applications.

Note: APP_INSTALLS and APP_ENGAGEMENTS objectives require setting at least one app store identifier — either android_app_store_identifier or ios_app_store_identifier.

Type: string

Example: com.twitter.android
bid_amount_local_micro
sometimes required
The bid amount to be associated with this line item. The currency associated with the specified funding instrument will be used. For USD, $5.50 is represented as 5500000.

Note: Required if bid_strategy is set to either MAX or TARGET

Note: Only values greater than zero are accepted.

Type: long

Example: 5500000
categories
sometimes required
The relevant IAB categories for this advertiser. See GET iab_categories.

Note: Required when the line item’s placement is set to PUBLISHER_NETWORK.

Type: string

Example: IAB3-1
ios_app_store_identifier
sometimes required
The numeric portion of the Apple App Store identifier for promoted applications.

Note: APP_INSTALLS and APP_ENGAGEMENTS objectives require setting at least one app store identifier — either android_app_store_identifier or ios_app_store_identifier.

Type: string

Example: 333903271
primary_web_event_tag
sometimes required
The identifier of the primary web event tag. Allows more accurate tracking of engagements for the campaign pertaining to this line item.

Note: Required when the line item’s goal is set to WEBSITE_CONVERSIONS.

Type: string

Example: nvo4z
advertiser_user_id
optional
The X user identifier for the handle promoting a PREROLL_VIEWS ad. Only certain client applications may use this parameter.

Type: string

Example: 312226591
audience_expansion
optional
Used to expand the reach of campaigns by targeting users similar to those already targeted.

Note: By default, no expansion will be applied.

Type: enum

Possible values: BROAD, DEFINED, EXPANDED
bid_strategy
optional
The bidding mechanism.

AUTO automatically optimizes bidding based on daily budget and campaign flight dates.

MAX sets the maximum allowable bid and is not available when the objective is set to REACH or FOLLOWERS.

TARGET attempts to make daily bid averages within 20% of the specified bid_amount_local_micro and is available when the objective is set to REACH, FOLLOWERS, OR WEBSITE_CLICKS.

Note: If set to AUTO, bid_amount_local_micro will be ignored.

Note: Default based on objective.

Type: enum

Possible values: AUTO, MAX, TARGET
duration_in_days
optional
The time period within which the frequency_cap is achieved.

Type: int

Possible values: 1, 7, 30
entity_status
optional
The line item status.

Type: enum

Default: ACTIVE
Possible values: ACTIVE, DRAFT, PAUSED
frequency_cap
optional
The maximum number of times an ad could be delivered to a user.

Note: Only supported for REACH, ENGAGEMENTS, VIDEO_VIEWS, and PREROLL_VIEWS objectives.

Type: int

Example: 5
goal
optional
The optimization setting to use with this line item.

The APP_PURCHASES option is available for APP_INSTALL. The APP_CLICKS and APP_INSTALLS options are available for both APP_INSTALL and APP_ENGAGEMENTS objectives and may require using a supported MACT partner.

The SITE_VISITS option is only available with the WEBSITE_CLICKS objective.

Note: Default based on objective.

Type: enum

Possible values: APP_CLICKS, APP_INSTALLS, APP_PURCHASES,ENGAGEMENT, FOLLOWERS, LINK_CLICKS, MAX_REACH, PREROLL, PREROLL_STARTS, REACH_WITH_ENGAGEMENT, SITE_VISITS, VIDEO_VIEW, VIEW_3S_100PCT, VIEW_6S, VIEW_15S, WEBSITE_CONVERSIONS
name
optional
The name for the line item.

Type: string

Example: demo

Min, Max length: 1, 255
pay_by
optional
The unit to charge this line item by. This setting can only be modified for line items using the APP_INSTALLS objective.

Note: The default pay_by is automatically set based upon the campaign objective and line item’s bid unit.

The APP_INSTALLS goal supports both APP_CLICK and IMPRESSION values. IMPRESSION is the default value.

The LINK_CLICKS goal supports both LINK_CLICK and IMPRESSION values. IMPRESSION is the default value but is not supported when setting TARGET for bid_strategy.

The SITE_VISITS goal supports IMPRESSION values.

Type: enum

Possible values: APP_CLICK, IMPRESSION, LINK_CLICK
standard_delivery
optional
Enable standard or accelerated delivery. See Budget Pacing for more information on standard versus accelerated delivery. Only available when budget_optimization is set to LINE_ITEM for the parent campaign

Type: boolean

Default: true
Possible values: true, false
total_budget_amount_local_micro
optional
The total budget amount to be allocated to the line item. The currency associated with the specified funding instrument will be used. For USD, $37.50 is represented as 37500000.

Type: long

Example: 37500000
daily_budget_amount_local_micro
sometimes required
The daily budget amount to be allocated to the campaign. The currency associated with the specified funding instrument will be used. For USD, $5.50 is represented as 5500000. When not provided the campaign will spend evenly based upon total budget and for duration of campaign flight time. Only available when budget_optimization is set to LINE_ITEM for the parent campaign

Note: This should be less than or equal to the total_budget_amount_local_micro.

Type: long

Example: 5500000

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items?campaign_id=hwtq0&objective=ENGAGEMENTS&product_type=PROMOTED_TWEETS&placements=ALL_ON_TWITTER&bid_amount_local_micro=3210000&entity_status=PAUSED&daily_budget_amount_local_micro=1000000&start_time=2022-06-15

Example Response

    {
      "request": {
        "params": {
          "placements": [
            "ALL_ON_TWITTER"
          ],
          "start_time": "2022-06-15T00:00:00Z",
          "bid_amount_local_micro": 3210000,
          "daily_budget_amount_local_micro": 1000000,
          "product_type": "PROMOTED_TWEETS",
          "objective": "ENGAGEMENTS",
          "entity_status": "PAUSED",
          "account_id": "18ce54d4x5t",
          "campaign_id": "hwtq0"
        }
      },
      "data": {
        "advertiser_user_id": "756201191646691328",
        "name": null,
        "placements": [
          "ALL_ON_TWITTER"
        ],
        "start_time": "2022-06-15T00:00:00Z",
        "bid_amount_local_micro": 3210000,
        "advertiser_domain": null,
        "target_cpa_local_micro": null,
        "primary_web_event_tag": null,
        "goal": "ENGAGEMENT",
        "daily_budget_amount_local_micro": 1000000,
        "product_type": "PROMOTED_TWEETS",
        "end_time": null,
        "bid_strategy": "MAX",
        "duration_in_days": null,
        "standard_delivery": true,
        "total_budget_amount_local_micro": null,
        "objective": "ENGAGEMENTS",
        "id": "ml5vs",
        "entity_status": "PAUSED",
        "automatic_tweet_promotion": null,
        "frequency_cap": null,
        "android_app_store_identifier": null,
        "categories": [],
        "currency": "USD",
        "pay_by": "ENGAGEMENT",
        "created_at": "2022-06-03T23:47:20Z",
        "ios_app_store_identifier": null,
        "updated_at": "2022-06-03T23:47:20Z",
        "campaign_id": "hwtq0",
        "creative_source": "MANUAL",
        "deleted": false
      }
    }

POST batch/accounts/:account_id/line_items

Allows the batch creation of new line items with a single request.

Batch Requests

  • The current maximum batch size is 40.
  • All parameters are sent in the request body and a Content-Type of application/json is required.
  • Batch requests fail or succeed together as a group and all API responses for both error and success preserve the item order of the initial request.

Batch Responses

Batch API responses return an ordered collection of items. Otherwise, they are identical in structure to their corresponding single-item endpoints.

Batch Errors

  • Request-level errors (eg. max batch size exceeded) are shown in the response under the errors object.
  • Item-level errors (eg. missing required line item parameter) are shown in the response under the operation_errors object.

Resource URL

https://ads-api.x.com/12/batch/accounts/:account_id/line_items

Parameters

NameDescription
operation_type
required
The per item operation type being performed.

Type: enum

Possible values: Create, Delete, Update
params
required
A JSON object containing all the parameters for the line item objects. For a list of required and optional line item parameters, see here.

Example Request

POST 'Content-Type: application/json' https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/line_items

    [
      {
        "operation_type":"Create",
        "params":{
          "campaign_id":"8yn7m",
          "objective":"ENGAGEMENTS",
          "product_type":"PROMOTED_TWEETS",
          "placements":"ALL_ON_TWITTER",
          "bid_amount_local_micro":3210000,
          "entity_status":"PAUSED"
        }
      }
    ]

Example Response

    {
      "data": [
        {
          "advertiser_user_id": "756201191646691328",
          "name": null,
          "placements": [
            "ALL_ON_TWITTER"
          ],
          "start_time": null,
          "bid_amount_local_micro": 3210000,
          "advertiser_domain": null,
          "target_cpa_local_micro": null,
          "primary_web_event_tag": null,
          "goal": "ENGAGEMENT",
          "daily_budget_amount_local_micro": null,
          "product_type": "PROMOTED_TWEETS",
          "end_time": null,
          "funding_instrument_id": "lygyi",
          "bid_strategy": "MAX",
          "duration_in_days": null,
          "standard_delivery": null,
          "total_budget_amount_local_micro": null,
          "objective": "ENGAGEMENTS",
          "id": "9cqi0",
          "entity_status": "PAUSED",
          "automatic_tweet_promotion": null,
          "frequency_cap": null,
          "android_app_store_identifier": null,
          "categories": [],
          "currency": "USD",
          "pay_by": "ENGAGEMENT",
          "created_at": "2017-07-07T17:42:20Z",
          "ios_app_store_identifier": null,
          "updated_at": "2017-07-07T17:42:20Z",
          "campaign_id": "8yn7m",
          "creative_source": "MANUAL",
          "deleted": false
        }
      ],
      "request": [
        {
          "params": {
            "placements": [
              "ALL_ON_TWITTER"
            ],
            "bid_amount_local_micro": 3210000,
            "product_type": "PROMOTED_TWEETS",
            "objective": "ENGAGEMENTS",
            "entity_status": "PAUSED",
            "account_id": "18ce54d4x5t",
            "campaign_id": "8yn7m"
          },
          "operation_type": "Create"
        }
      ]
    }

PUT accounts/:account_id/line_items/:line_item_id

Update the specified line item associated with the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/line_items/:line_item_id

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
line_item_id
required
A reference to the line item you are operating with in the request.

Type: string

Example: 8v7jo
advertiser_domain
optional
The website domain for this advertiser, without the protocol specification.

Note: Required when the line item’s placement is set to PUBLISHER_NETWORK.

Type: string

Example: x.com
advertiser_user_id
optional
The Twitter user identifier for the handle promoting a PREROLL_VIEWS ad. Only certain client applications may use this parameter.

Type: string

Example: 312226591
android_app_store_identifier
optional
The Google App Store identifier for the promoted application.

Note: APP_INSTALLS and APP_ENGAGEMENTS objectives require setting at least one app store identifier — either android_app_store_identifier or ios_app_store_identifier.

Type: string

Example: com.twitter.android
audience_expansion
optional
Used to expand the reach of campaigns by targeting users similar to those already targeted.

Type: enum

Possible values: BROAD, DEFINED, EXPANDED
bid_amount_local_micro
optional
The bid amount to be associated with this line item. The currency associated with the specified funding instrument will be used. For USD, $5.50 is represented as 5500000.

Note: Required if bid_strategy is set to either MAX or TARGET

Note: Only values greater than zero are accepted.

Type: long

Example: 140000
bid_strategy
optional
The bidding mechanism.

AUTO automatically optimizes bidding based on daily budget and campaign flight dates.

MAX sets the maximum allowable bid and is not available when the objective is set to REACH or FOLLOWERS.

TARGET attempts to make daily bid averages within 20% of the specified bid_amount_local_micro and is available when the objective is set to REACH or WEBSITE_CLICKS.

Note: If set to AUTO, bid_amount_local_micro will be ignored.

Note: Default based on objective.

Type: enum

Possible values: AUTO, MAX, TARGET
categories
optional
The relevant IAB categories for this advertiser. See GET iab_categories.

Note: Required when the line item’s placement is set to PUBLISHER_NETWORK.

Type: string

Example: IAB3-1
duration_in_days
optional
The time period within which the frequency_cap is achieved.

Type: int

Possible values: 1, 7, 30
entity_status
optional
The line item status.

Type: enum

Possible values: ACTIVE, PAUSED
end_time
optional
The time, expressed in ISO 8601, that the line item will stop serving.

Type: string

Example: 2017-10-05T00:00:00Z
frequency_cap
optional
The maximum number of times an ad could be delivered to a user.

Note: Only supported for REACH, ENGAGEMENTS, VIDEO_VIEWS, and PREROLL_VIEWS objectives.

Type: int

Example: 5
goal
optional
The optimization setting to use with this line item. The APP_PURCHASES option is available for APP_INSTALL. The APP_CLICKS and APP_INSTALLS options are available for APP_INSTALL and APP_ENGAGEMENTS and may require using a supported MACT partner.

Note: Default based on objective.

Type: enum

Possible values: APP_CLICKS, APP_INSTALLS, APP_PURCHASES, ENGAGEMENT, FOLLOWERS, LINK_CLICKS, MAX_REACH, PREROLL, PREROLL_STARTS, REACH_WITH_ENGAGEMENT, VIDEO_VIEW, VIEW_3S_100PCT, VIEW_6S, VIEW_15S, WEBSITE_CONVERSIONS
ios_app_store_identifier
optional
The numeric portion of the Apple App Store identifier for promoted applications.

Note: APP_INSTALLS and APP_ENGAGEMENTS objectives require setting at least one app store identifier — either android_app_store_identifier or ios_app_store_identifier.

Type: string

Example: 333903271
name
optional
The name for the line item.

Type: string

Example: demo
pay_by
optional
The unit to charge this line item by. This setting can only be modified for line items using the APP_INSTALLS objective.

Note: The default pay_by is automatically set based upon the campaign objective and line item’s bid unit.

The APP_INSTALLS goal supports both APP_CLICK and IMPRESSION values. IMPRESSION is the default value.

The LINK_CLICKS goal supports both LINK_CLICK and IMPRESSION values. IMPRESSION is the default value but is not supported when setting TARGET for bid_strategy.

The SITE_VISITS goal supports IMPRESSION values.

Type: enum

Possible values: APP_CLICK, IMPRESSION, LINK_CLICK
start_time
optional
The time, expressed in ISO 8601, that the line item will begin serving.

Type: string

Example: 2017-07-05T00:00:00Z
total_budget_amount_local_micro
optional
The total budget amount to be allocated to the line item. The currency associated with the specified funding instrument will be used. For USD, $37.50 is represented as 37500000.

Type: long

Example: 37500000
daily_budget_amount_local_micro
optional
The daily budget amount to be allocated to the campaign. The currency associated with the specified funding instrument will be used. For USD, $5.50 is represented as 5500000. When not provided the campaign will spend evenly based upon total budget and for duration of campaign flight time. Only available when budget_optimization is set to LINE_ITEM for the parent campaign

Note: This should be less than or equal to the total_budget_amount_local_micro.

Type: long

Example: 5500000

Example Request

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items/9cqi0?bid_amount_local_micro=140000

Example Response

    {
      "request": {
        "params": {
          "line_item_id": "9cqi0",
          "bid_amount_local_micro": 140000,
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "advertiser_user_id": "756201191646691328",
        "name": null,
        "placements": [
          "ALL_ON_TWITTER"
        ],
        "start_time": "2017-07-10T00:00:00Z",
        "bid_amount_local_micro": 140000,
        "advertiser_domain": null,
        "target_cpa_local_micro": null,
        "primary_web_event_tag": null,
        "goal": "ENGAGEMENT",
        "daily_budget_amount_local_micro": null,
        "product_type": "PROMOTED_TWEETS",
        "end_time": null,
        "bid_strategy": "MAX",
        "duration_in_days": null,
        "standard_delivery": null,
        "total_budget_amount_local_micro": null,
        "objective": "ENGAGEMENTS",
        "id": "9cqi0",
        "entity_status": "PAUSED",
        "automatic_tweet_promotion": null,
        "frequency_cap": null,
        "android_app_store_identifier": null,
        "categories": [],
        "currency": "USD",
        "pay_by": "ENGAGEMENT",
        "created_at": "2017-07-07T17:42:20Z",
        "ios_app_store_identifier": null,
        "updated_at": "2022-06-03T23:51:36Z",
        "campaign_id": "8yn7m",
        "creative_source": "MANUAL",
        "deleted": false
      }
    }

DELETE accounts/:account_id/line_items/:line_item_id

Delete the specified line item belonging to the current account.

Note: Deleting a line item is not reversible and subsequent attempts to delete the resource will return HTTP 404.

Note: When a line item is deleted, its child promoted_tweets are only returned in the GET accounts/:account_id/promoted_tweets and GET accounts/:account_id/promoted_tweets/:promoted_tweet_id endpoints if with_deleted=true is specified in the request. These promoted_tweets are not actually deleted, though ("deleted": false in the response). We do not cascade deletes.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/line_items/:line_item_id

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
line_item_id
required
A reference to the line item you are operating with in the request.

Type: string

Exampple: 9f2ix

Example Request

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items/9f2ix

Example Response

    {
      "data": {
        "bid_strategy": "MAX",
        "advertiser_user_id": "756201191646691328",
        "name": "Untitled",
        "placements": [],
        "start_time": null,
        "bid_amount_local_micro": 100000,
        "advertiser_domain": null,
        "target_cpa_local_micro": null,
        "primary_web_event_tag": null,
        "pay_by": "ENGAGEMENT",
        "product_type": "PROMOTED_TWEETS",
        "end_time": "2017-07-21T00:00:00Z",
        "duration_in_days": 1,
        "total_budget_amount_local_micro": null,
        "objective": "ENGAGEMENTS",
        "id": "9f2ix",
        "entity_status": "ACTIVE",
        "goal": "ENGAGEMENT",
        "frequency_cap": 5,
        "categories": [],
        "currency": "USD",
        "created_at": "2017-07-14T00:01:50Z",
        "updated_at": "2017-08-09T07:41:08Z",
        "campaign_id": "90r8n",
        "creative_source": "MANUAL",
        "deleted": true
      },
      "request": {
        "params": {
          "line_item_id": "9f2ix",
          "account_id": "18ce54d4x5t"
        }
      }
    }

Line Item Curated Categories

Additional details on usage can be found at the Video Views Pre-roll Objective Guide

GET accounts/:account_id/line_item_curated_categories

Retrieve details for some or all line item curated categories associated with the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
count
optional
Specifies the number of records to try and retrieve per distinct request.

Type: int

Default: 200
Min, Max: 1, 1000
cursor
optional
Specifies a cursor to get the next page of results. See Pagination for more information.

Type: string

Example: 8x7v00oow
sort_by
optional
Sorts by supported attribute in ascending or descending order. See Sorting for more information.

Type: string

Example: created_at-asc
with_deleted
optional
Include deleted results in your request.

Type: boolean

Default: false
Possible values: true, false
with_total_count
optional
Include the total_count response attribute.

Note: This parameter and cursor are exclusive.

Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes.

Type: boolean

Default: false
Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/abc1/line_item_curated_categories

Example Response

    {
      "request": {
        "params": {
          "account_id": "abc1"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "line_item_id": "by5pw",
          "curated_category_id": "7op29tp2jzeo",
          "id": "1",
          "created_at": "2018-06-29T04:19:53Z",
          "updated_at": "2018-06-29T04:19:53Z",
          "deleted": false
        }
      ]
    }

GET accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id

Retrieves details for a specific line item curated category associated with the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
line_item_curated_category_id
required
A reference to the line item curated category you are operating with in the request.

Type: string

Example: 43853bhii885
with_deleted
optional
Include deleted results in your request.

Type: boolean

Default: false
Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/abc1/line_item_curated_categories/yav

Example Response

    {
      "request": {
        "params": {
          "line_item_curated_category_id": "yav",
          "account_id": "abc1"
        }
      },
      "data": {
        "line_item_id": "by5pw",
        "curated_category_id": "7op29tp2jzeo",
        "id": "yav",
        "created_at": "2018-06-29T04:19:53Z",
        "updated_at": "2018-06-29T04:19:53Z",
        "deleted": false
      }
    }

POST accounts/:account_id/line_item_curated_categories

Associate a curated category object with the specified line item.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
curated_category_id
required
A reference to the curated category entity you are operating with in the request.

Type: string

Example: 10miy
line_item_id
required
A reference to the line item you are operating with in the request.

Type: string

Example: 8v7jo

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/line_item_curated_categories?line_item_id=iqwka&curated_category_id=9ddrgesiap6o

Example Response

    {
      "request": {
        "params": {
          "curated_category_id": "9ddrgesiap6o",
          "line_item_id": "iqwka",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "iqwka",
        "curated_category_id": "9ddrgesiap6o",
        "id": "xq",
        "created_at": "2021-03-30T17:26:42Z",
        "updated_at": "2021-03-30T17:26:42Z",
        "deleted": false
      }
    }

PUT accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id

Update the specified line item curated category.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
line_item_curated_category_id
required
A reference to the line item curated category you are operating with in the request.

Type: string

Example: 1bzq3
curated_category_id
optional
A reference to the curated category entity you are operating with in the request.

Type: string

Example: 10miy
line_item_id
optional
A reference to the line item you are operating with in the request.

Type: string

Example: 8v7jo

Example Request

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/line_item_curated_categories/xq?curated_category_id=8tujl1p3yn0g

Example Response

    {
      "request": {
        "params": {
          "line_item_curated_category_id": "xq",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "iqwka",
        "curated_category_id": "8tujl1p3yn0g",
        "id": "xq",
        "created_at": "2021-03-30T17:26:42Z",
        "updated_at": "2021-03-30T18:22:52Z",
        "deleted": true
      }
    }

DELETE accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id

Delete the specified line item curated category.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
line_item_curated_category_id
required
A reference to the line item curated category you are operating with in the request.

Type: string

Example: 1bzq3

Example Request

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/line_item_curated_categories/xq

Example Response

    {
      "request": {
        "params": {
          "line_item_curated_category_id": "xq",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "iqwka",
        "curated_category_id": "9ddrgesiap6o",
        "id": "xq",
        "created_at": "2021-03-30T17:26:42Z",
        "updated_at": "2021-03-30T18:22:52Z",
        "deleted": true
      }
    }

Line Item Placements

GET line_items/placements

Retrieve valid placement and product_type combinations.

Resource URL

https://ads-api.x.com/12/line_items/placements

Parameters

NameDescription
product_type
optional
Scope the response to just the valid placements for the specified product type.

Type: enum

Possible values: MEDIA, PROMOTED_ACCOUNT, PROMOTED_TWEETS

Example Request

GET https://ads-api.x.com/12/line_items/placements?product_type=PROMOTED_ACCOUNT

Example Response

    {
      "data": [
        {
          "product_type": "PROMOTED_ACCOUNT",
          "placements": [
            [
              "ALL_ON_TWITTER"
            ],
            [
              "TWITTER_TIMELINE"
            ]
          ]
        }
      ],
      "request": {
        "params": {
          "product_type": "PROMOTED_ACCOUNT"
        }
      }
    }

Media Creatives

GET accounts/:account_id/media_creatives

Retrieve details for some or all media creatives associated with the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/media_creatives

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
campaign_id
optional
Scope the response to just the media creatives associated with the specified campaign.

Type: string

Example: 8gdx6
count
optional
Specifies the number of records to try and retrieve per distinct request.

Type: int

Default: 200
Min, Max: 1, 1000
cursor
optional
Specifies a cursor to get the next page of results. See Pagination for more information.

Type: string

Example: 8x7v00oow
line_item_ids
optional
Scope the response to just the media creatives associated with the specified line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: 8v7jo
media_creative_ids
optional
Scope the response to just the desired media creatives by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: 1bzq3
sort_by
optional
Sorts by supported attribute in ascending or descending order. See Sorting for more information.

Type: string

Example: created_at-asc
with_deleted
optional
Include deleted results in your request.

Type: boolean

Default: false
Possible values: true, false
with_total_count
optional
Include the total_count response attribute.

Note: This parameter and cursor are exclusive.

Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes.

Type: boolean

Default: false
Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives?media_creative_ids=1bzq3

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "media_creative_ids": [
            "1bzq3"
          ]
        }
      },
      "next_cursor": null,
      "data": [
        {
          "line_item_id": "8v7jo",
          "landing_url": "https://dev.x.com",
          "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET",
          "id": "1bzq3",
          "entity_status": "ACTIVE",
          "created_at": "2017-07-05T06:00:42Z",
          "account_media_id": "10miy",
          "updated_at": "2019-01-11T20:21:26Z",
          "approval_status": "ACCEPTED",
          "deleted": false
        }
      ]
    }

GET accounts/:account_id/media_creatives/:media_creative_id

Retrieves details for a specific media creative associated with the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/media_creatives/:media_creative_id

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
media_creative_id
required
A reference to the media creative you are operating with in the request.

Type: string

Example: 43853bhii885
with_deleted
optional
Include deleted results in your request.

Type: boolean

Default: false
Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives/1bzq3

Example Response

    {
      "request": {
        "params": {
          "media_creative_id": "1bzq3",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "8v7jo",
        "landing_url": "https://dev.x.com",
        "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET",
        "id": "1bzq3",
        "entity_status": "ACTIVE",
        "created_at": "2017-07-05T06:00:42Z",
        "account_media_id": "10miy",
        "updated_at": "2019-01-11T20:21:26Z",
        "approval_status": "ACCEPTED",
        "deleted": false
      }
    }

POST accounts/:account_id/media_creatives

Associate an account media object with the specified line item.

Use this endpoint to promote in-stream ads (when the account media creative_type is PREROLL) or image ads (such as BANNER or INTERSTITIAL) on the Twitter Audience Platform.

Note: In order to add media assets to the Account Media resource, use the POST accounts/:account_id/media_library endpoint.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/media_creatives

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
account_media_id
required
A reference to the account media entity you are operating with in the request.

Type: string

Example: 10miy
line_item_id
required
A reference to the line item you are operating with in the request.

Type: string

Example: 8v7jo
landing_url
sometimes required
The URL of the website to direct a user to. This should only be used with TAP images (or “display creatives”). This value will be ignored if used with preroll assets. To associate a URL with a preroll asset, use the POST accounts/:account_id/preroll_call_to_actions endpoint.

Note: Required when the line item’s objective is set to WEBSITE_CLICKS.

Type: string

Example: https://blog.x.com/

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives?line_item_id=8v7jo&account_media_id=10miy

Example Response

    {
      "request": {
        "params": {
          "line_item_id": "8v7jo",
          "account_media_id": "10miy",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "8v7jo",
        "landing_url": "https://dev.x.com",
        "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET",
        "id": "1bzq3",
        "entity_status": "ACTIVE",
        "created_at": "2017-07-05T06:00:42Z",
        "account_media_id": "10miy",
        "updated_at": "2019-01-11T20:21:26Z",
        "approval_status": "ACCEPTED",
        "deleted": false
      }
    }

DELETE accounts/:account_id/media_creatives/:media_creative_id

Delete the specified media creative belonging to the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/media_creatives/:media_creative_id

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
media_creative_id
required
A reference to the media creative you are operating with in the request.

Type: string

Example: 1bzq3

Example Request

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives/1bzq3

Example Response

    {
      "request": {
        "params": {
          "media_creative_id": "1bzq3",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "8v7jo",
        "landing_url": "https://dev.x.com",
        "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET",
        "id": "1bzq3",
        "entity_status": "ACTIVE",
        "created_at": "2017-07-05T06:00:42Z",
        "account_media_id": "10miy",
        "updated_at": "2021-04-16T21:02:55Z",
        "approval_status": "ACCEPTED",
        "deleted": true
      }
    }

GET accounts/:account_id/promoted_accounts

Retrieve details for some or all promoted accounts associated with one or more line items under the current account.

Use GET users/lookup to obtain user data for the user accounts identified by user_id in the response.

An HTTP 400 will be returned if none of the specified line items are configured to contain promoted accounts.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/promoted_accounts

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
count
optional
Specifies the number of records to try and retrieve per distinct request.

Type: int

Default: 200
Min, Max: 1, 1000
cursor
optional
Specifies a cursor to get the next page of results. See Pagination for more information.

Type: string

Example: 8x7v00oow
line_item_ids
optional
Scope the response to just the promoted accounts associated with the specified line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: 9bpb2
promoted_account_ids
optional
Scope the response to just the desired promoted accounts by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: 19pl2
sort_by
optional
Sorts by supported attribute in ascending or descending order. See Sorting for more information.

Type: string

Example: created_at-asc
with_deleted
optional
Include deleted results in your request.

Type: boolean

Default: false
Possible values: true, false
with_total_count
optional
Include the total_count response attribute.

Note: This parameter and cursor are exclusive.

Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes.

Type: boolean

Default: false
Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts?promoted_account_ids=19pl2

Example Response

    {
      "request": {
        "params": {
          "promoted_account_ids": [
            "19pl2"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "line_item_id": "9bpb2",
          "user_id": "756201191646691328",
          "id": "19pl2",
          "entity_status": "ACTIVE",
          "created_at": "2017-07-05T05:54:13Z",
          "updated_at": "2017-07-05T05:54:13Z",
          "approval_status": "ACCEPTED",
          "deleted": false
        }
      ]
    }

GET accounts/:account_id/promoted_accounts/:promoted_account_id

Retrieve a specific reference to an account associated with a line item under the current account.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/promoted_accounts/:promoted_account_id

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
promoted_account_id
required
A reference to the promoted account you are operating with in the request.

Type: string

Example: 19pl2
with_deleted
optional
Include deleted results in your request.

Type: boolean

Default: false
Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts/19pl2

Example Response

    {
      "request": {
        "params": {
          "promoted_account_id": "19pl2",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "9bpb2",
        "user_id": "756201191646691328",
        "id": "19pl2",
        "entity_status": "ACTIVE",
        "created_at": "2017-07-05T05:54:13Z",
        "updated_at": "2017-07-05T05:54:13Z",
        "approval_status": "ACCEPTED",
        "deleted": false
      }
    }

POST accounts/:account_id/promoted_accounts

Associate an account (user_id) with the specified line item.

If the specified line item is not configured to be associated with Promoted Accounts, a HTTP 400 INCOMPATIBLE_LINE_ITEM error will be returned. If the specified user is ineligible for promotion, a HTTP 400 will be returned and no users will be promoted. If the provided user is already promoted, the request will be ignored.

For more information on Promoted Accounts, see our campaign management page.

Note: It is not possible to update (PUT) promoted accounts entities.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/promoted_accounts

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
line_item_id
required
A reference to the line item you are operating with in the request.

Type: string

Example: 9bpb2
user_id
required
A reference to the user you are operating with in the request. Use GET users/lookup to retrieve a user ID for a screen name.

Type: long

Example: 756201191646691328

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts?line_item_id=9bpb2&user_id=756201191646691328

Example Response

    {
      "data": {
        "line_item_id": "9bpb2",
        "user_id": "756201191646691328",
        "id": "19pl2",
        "entity_status": "ACTIVE",
        "created_at": "2017-07-05T05:54:13Z",
        "updated_at": "2017-07-05T05:54:13Z",
        "approval_status": "ACCEPTED",
        "deleted": false
      },
      "request": {
        "params": {
          "user_id": "756201191646691328",
          "line_item_id": "9bpb2",
          "account_id": "18ce54d4x5t"
        }
      }
    }

DELETE accounts/:account_id/promoted_accounts/:promoted_account_id

Disassociate an account from the specified line item.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/promoted_accounts/:promoted_account_id

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
promoted_account_id
required
The identifier refers to the instance of a Promoted Account associated with a line item.

Type: string

Example: 19pl2

Example Request

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts/19pl2

Example Response

    {
      "data": {
        "line_item_id": "9bpb2",
        "user_id": "756201191646691328",
        "id": "19pl2",
        "entity_status": "ACTIVE",
        "created_at": "2017-07-05T05:54:13Z",
        "updated_at": "2017-08-23T18:53:15Z",
        "approval_status": "ACCEPTED",
        "deleted": true
      },
      "request": {
        "params": {
          "promoted_account_id": "19pl2",
          "account_id": "18ce54d4x5t"
        }
      }
    }

GET accounts/:account_id/promoted_tweets

Retrieve references to Tweets associated with line items under the current account.

Use the GET accounts/:account_id/tweets endpoint to fetch the Tweet objects. Use the tweet_id values for each promoted_tweets object.

Note: When parent line items are deleted, promoted_tweets are only returned if with_deleted=true is specified in the request. These promoted_tweets are not actually deleted, though ("deleted": false in the response).

Resource URL

https://ads-api.x.com/12/accounts/:account_id/promoted_tweets

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
count
optional
Specifies the number of records to try and retrieve per distinct request.

Type: int

Default: 200
Min, Max: 1, 1000
cursor
optional
Specifies a cursor to get the next page of results. See Pagination for more information.

Type: string

Example: 8x7v00oow
line_item_ids
optional
Scope the response to just the Tweets associated with specific line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: 96uzp
promoted_tweet_ids
optional
Scope the response to just the desired promoted Tweets by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: 1efwlo
sort_by
optional
Sorts by supported attribute in ascending or descending order. See Sorting for more information.

Type: string

Example: created_at-asc
with_deleted
optional
Include deleted results in your request.

Type: boolean

Default: false
Possible values: true, false
with_total_count
optional
Include the total_count response attribute.

Note: This parameter and cursor are exclusive.

Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes.

Type: boolean

Default: false
Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets?promoted_tweet_ids=1efwlo

Example Response

    {
      "request": {
        "params": {
          "promoted_tweet_ids": [
            "1efwlo"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "line_item_id": "96uzp",
          "id": "1efwlo",
          "entity_status": "ACTIVE",
          "created_at": "2017-06-29T05:06:57Z",
          "updated_at": "2017-06-29T05:08:46Z",
          "approval_status": "ACCEPTED",
          "tweet_id": "880290790664060928",
          "deleted": false
        }
      ]
    }

GET accounts/:account_id/promoted_tweets/:promoted_tweet_id

Retrieve a specific reference to a Tweet associated with a line item under the current account.

Note: When parent line items are deleted, promoted_tweets are only returned if with_deleted=true is specified in the request. These promoted_tweets are not actually deleted, though ("deleted": false in the response).

Resource URL

https://ads-api.x.com/12/accounts/:account_id/promoted_tweets/:promoted_tweet_id

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
promoted_tweet_id
required
A reference to the promoted Tweet you are operating with in the request.

Type: string

Example: 1efwlo
with_deleted
optional
Include deleted results in your request.

Type: boolean

Default: false
Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets/1efwlo

Example Response

    {
      "request": {
        "params": {
          "promoted_tweet_id": "1efwlo",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "line_item_id": "96uzp",
        "id": "1efwlo",
        "entity_status": "ACTIVE",
        "created_at": "2017-06-29T05:06:57Z",
        "updated_at": "2017-06-29T05:08:46Z",
        "approval_status": "ACCEPTED",
        "tweet_id": "880290790664060928",
        "deleted": false
      }
    }

POST accounts/:account_id/promoted_tweets

Associate one or more Tweets with the specified line item. Not all Tweets are appropriate for promotion, depending on the campaign objective. Please see Objective-based Campaigns for more information.

When using the PROMOTED_ACCOUNT product type, associating a Tweet with the line_item will add timeline placements on mobile in addition to the standard PROMOTED_ACCOUNT placement.

Note: It is not possible to update (PUT) promoted Tweet entities.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/promoted_tweets

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
line_item_id
required
A reference to the line item you are operating with in the request.

Type: string

Example: 8v7jo
tweet_ids
required
A comma-separated list of identifiers corresponding to specific Tweets. Up to 50 IDs may be provided.

Type: long

Example: 822333526255120384

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets?line_item_id=8v7jo&tweet_ids=822333526255120384

Example Response

    {
      "data": [
        {
          "line_item_id": "8v7jo",
          "id": "1e8i2k",
          "entity_status": "ACTIVE",
          "created_at": "2017-06-24T04:21:36Z",
          "updated_at": "2017-06-24T04:21:36Z",
          "approval_status": "ACCEPTED",
          "tweet_id": "822333526255120384",
          "deleted": false
        }
      ],
      "request": {
        "params": {
          "line_item_id": "8v7jo",
          "tweet_ids": [
            822333526255120384
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "total_count": 1
    }

DELETE accounts/:account_id/promoted_tweets/:promoted_tweet_id

Disassociate a Tweet from the specified line item.

Note: A deleted promoted_tweets entity will be displayed as “Paused” in the ads.x.com UI. Similarly, “pausing” from the UI will disassociate the Tweet from its line item.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/promoted_tweets/:promoted_tweet_id

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
promoted_tweet_id
required
The identifier refers to the instance of a Promoted Tweet associated with a line item. This comes from the id field from a response item to GET accounts/:account_id/promoted_tweets, not the tweet_id of the Tweet in question. Supplied within the resource’s path.

Type: string

Example: 1gp8a5

Example Request

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets/1gp8a5

Example Response

    {
      "data": {
        "line_item_id": "9pl99",
        "id": "1gp8a5",
        "entity_status": "ACTIVE",
        "created_at": "2017-08-17T17:02:21Z",
        "updated_at": "2017-08-18T06:43:48Z",
        "approval_status": "ACCEPTED",
        "tweet_id": "844796297743757315",
        "deleted": true
      },
      "request": {
        "params": {
          "promoted_tweet_id": "1gp8a5",
          "account_id": "18ce54d4x5t"
        }
      }
    }

Promotable Users

GET accounts/:account_id/promotable_users

Retrieve details for some or all promotable users associated with the current account.

The promotable user type is either FULL or RETWEETS_ONLY. This controls the type of content that is allowed to be promoted by the account. Advertisers must obtain permission to promote another user’s content and contact Twitter to get them added to your account as a RETWEETS_ONLY promotable user.

Provided the permissions are set correctly, you can make requests to the promoted product endpoints that directly reference the Tweet ID of the Tweet you’d like to promote. You can use the POST accounts/:account_id/promoted-tweets endpoint to promote published Tweets and the POST accounts/:account_id/scheduled-promoted-tweets endpoint to promote another Twitter Ads account’s Scheduled Tweets.

You do not have to retweet the target Tweet. When you promote a Tweet with this approach, the tweet_id that is returned will be different from the Tweet ID that was provided. Behind the scenes, the Tweet is being retweeted as a nullcasted Tweet and then promoted. The tweet_id that is returned corresponds to this new Tweet.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/promotable_users

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
count
optional
Specifies the number of records to try and retrieve per distinct request.

Type: int

Default: 200
Min, Max: 1, 1000
cursor
optional
Specifies a cursor to get the next page of results. See Pagination for more information.

Type: string

Example: 8x7v00oow
promotable_user_ids
optional
Scope the response to just the desired promotable users by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: l310s
sort_by
optional
Sorts by supported attribute in ascending or descending order. See Sorting for more information.

Type: string

Example: created_at-asc
with_deleted
optional
Include deleted results in your request.

Type: boolean

Default: false
Possible values: true, false
with_total_count
optional
Include the total_count response attribute.

Note: This parameter and cursor are exclusive.

Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes.

Type: boolean

Default: false
Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promotable_users?promotable_user_ids=l310s

Example Response

    {
      "request": {
        "params": {
          "promotable_user_ids": [
            "l310s"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "user_id": "756201191646691328",
          "id": "l310s",
          "created_at": "2016-07-21T22:42:09Z",
          "updated_at": "2016-07-21T22:42:09Z",
          "deleted": false,
          "promotable_user_type": "FULL"
        }
      ]
    }

GET accounts/:account_id/promotable_users/:promotable_user_id

Retrieve a specific promotable user associated with the current account.

The promotable user type is either FULL or RETWEETS_ONLY. This controls the type of content that is allowed to be promoted by the account.

Advertisers must obtain permission to promote another user’s content. Provided the permissions are set correctly, you can make requests to the promoted product endpoints that directly reference the Tweet ID of the Tweet you’d like to promote.

You do not have to retweet the target Tweet. When you promote a Tweet with this approach, the tweet_id that is returned will be different from the Tweet ID that was provided. Behind the scenes, the Tweet is being retweeted as a nullcasted Tweet and then promoted. The tweet_id that is returned corresponds to this new Tweet.

Resource URL

https://ads-api.x.com/12/accounts/:account_id/promotable_users/:promotable_user_id

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
promotable_user_id
optional
A reference to the promotable user you are operating on within the request

Type: string

Example: l310s
with_deleted
optional
Include deleted results in your request.

Type: boolean

Default: false
Possible values: true, false

Example Request

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promotable_users/l310s

Example Response

    {
      "request": {
        "params": {
          "promotable_user_id": "l310s",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "user_id": "2417045708",
        "id": "l310s",
        "created_at": "2017-03-10T17:51:24Z",
        "updated_at": "2017-03-10T17:51:24Z",
        "deleted": false,
        "promotable_user_type": "RETWEETS_ONLY"
      }
    }

Publishers

GET publishers

Retrieve a list of Content Category publishers’ details

Additional details can be found in the Video Views Preroll Objective Guide

Resource URL

https://ads-api.x.com/12/publishers

Parameters

No request parameters

Example Request

GET https://ads-api.x.com/12/publishers

Example Response

    {
      "request": {
        "params": {}
      },
      "next_cursor": null,
      "data": [
        {
          "monetizable_country_codes": [
            "US"
          ],
          "promotion_eligible_country_codes": [
            "US"
          ],
          "username": "PeoplesSports",
          "user_id": "1353868435021721602",
          "monetization_restricted": true,
          "content_category_ids": [
            "se"
          ]
        },
        {
          "monetizable_country_codes": [
            "JP"
          ],
          "promotion_eligible_country_codes": [
            "JP"
          ],
          "username": "NewYork_Jack",
          "user_id": "1331177123436851206",
          "monetization_restricted": true,
          "content_category_ids": [
            "sk"
          ]
        },
        {
          "monetizable_country_codes": [
            "JP"
          ],
          "promotion_eligible_country_codes": [
            "JP"
          ],
          "username": "twispatv",
          "user_id": "1331165719128461314",
          "monetization_restricted": true,
          "content_category_ids": [
            "sm"
          ]
        },
        {
          "monetizable_country_codes": [
            "US"
          ],
          "promotion_eligible_country_codes": [
            "US"
          ],
          "username": "LAThieves",
          "user_id": "1316808678897455105",
          "monetization_restricted": true,
          "content_category_ids": [
            "s0"
          ]
        },
        {
          "monetizable_country_codes": [
            "US"
          ],
          "promotion_eligible_country_codes": [
            "US"
          ],
          "username": "Quicktake_EE",
          "user_id": "1305900477427724290",
          "monetization_restricted": true,
          "content_category_ids": [
            "sr"
          ]
        },
        {
          "monetizable_country_codes": [
            "BR"
          ],
          "promotion_eligible_country_codes": [
            "BR"
          ],
          "username": "eufloribella",
          "user_id": "1300812459054436354",
          "monetization_restricted": true,
          "content_category_ids": [
            "sm"
          ]
        },
        {
          "monetizable_country_codes": [
            "EG"
          ],
          "promotion_eligible_country_codes": [
            "KW",
            "EG",
            "SA",
            "AE",
            "LB",
            "QA"
          ],
          "username": "Egypt2021EN",
          "user_id": "1296077573399678977",
          "monetization_restricted": true,
          "content_category_ids": [
            "se"
          ]
        },
        {
          "monetizable_country_codes": [
            "US"
          ],
          "promotion_eligible_country_codes": [
            "US"
          ],
          "username": "ClubShayShay",
          "user_id": "1283068366706454529",
          "monetization_restricted": true,
          "content_category_ids": [
            "se"
          ]
        },
        {
          "monetizable_country_codes": [
            "IN",
            "KW",
            "ID",
            "EG",
            "SG",
            "TH",
            "MY",
            "PH",
            "ES",
            "US",
            "AU",
            "SA",
            "AE",
            "LB",
            "GB",
            "FR",
            "KR",
            "BR",
            "MX",
            "QA",
            "CA",
            "JP"
          ],
          "promotion_eligible_country_codes": [
            "KW",
            "EG",
            "SA",
            "AE",
            "LB",
            "QA"
          ],
          "username": "hiaahsanshow",
          "user_id": "1253421442143641601",
          "monetization_restricted": false,
          "content_category_ids": [
            "sh"
          ]
        },
        {
          "monetizable_country_codes": [
            "TH"
          ],
          "promotion_eligible_country_codes": [
            "TH"
          ],
          "username": "HoneKrasae",
          "user_id": "1240684293719904256",
          "monetization_restricted": true,
          "content_category_ids": [
            "sr"
          ]
        },
        {
          "monetizable_country_codes": [
            "US"
          ],
          "promotion_eligible_country_codes": [
            "US"
          ],
          "username": "Sportskind",
          "user_id": "1232708694418300930",
          "monetization_restricted": true,
          "content_category_ids": [
            "se"
          ]
        },
        {
          "monetizable_country_codes": [
            "IN",
            "KW",
            "ID",
            "EG",
            "SG",
            "TH",
            "MY",
            "PH",
            "ES",
            "US",
            "AU",
            "SA",
            "AE",
            "LB",
            "GB",
            "FR",
            "KR",
            "BR",
            "MX",
            "QA",
            "CA",
            "JP"
          ],
          "promotion_eligible_country_codes": [
            "KW",
            "EG",
            "SA",
            "AE",
            "LB",
            "QA"
          ],
          "username": "almeerathShow",
          "user_id": "1229410512762437633",
          "monetization_restricted": false,
          "content_category_ids": [
            "sh"
          ]
        },
        {
          "monetizable_country_codes": [
            "US"
          ],
          "promotion_eligible_country_codes": [
            "US"
          ],
          "username": "SeeYourVoiceFOX",
          "user_id": "1225490734653947904",
          "monetization_restricted": true,
          "content_category_ids": [
            "sh"
          ]
        },
        {
          "monetizable_country_codes": [
            "IN",
            "KW",
            "ID",
            "EG",
            "SG",
            "TH",
            "MY",
            "PH",
            "ES",
            "US",
            "AU",
            "SA",
            "AE",
            "LB",
            "GB",
            "FR",
            "KR",
            "BR",
            "MX",
            "QA",
            "CA",
            "JP"
          ],
          "promotion_eligible_country_codes": [
            "US"
          ],
          "username": "AUProSports",
          "user_id": "1219303449768185859",
          "monetization_restricted": false,
          "content_category_ids": [
            "se"
          ]
        }
      ]
    }

Recommendations

GET accounts/:account_id/recommendations

Status: Closed Beta

Retrieve campaign recommendations associated with this ads account. Currently there is a limit of 1 recommendation per funding instrument.

Resource URL

https://ads-api.x.com/5/accounts/:account_id/recommendations

Parameters

NameDescription
account_id
required
The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t

Example Request

GET https://ads-api.x.com/5/accounts/18ce54d4x5t/recommendations

Example Response

    "request": {
      "params": {
        "account_id": "18ce54d4x5t"
      }
    },
    "total_count": 1,
    "data": [
      {
        "funding_instrument_id": "gpvzb",
        "id": "62ce8zza1q0w",
        "account_id": "18ce54d4x5t",
        "status": "PENDING",
        "message": "Recommendation for testing",
        "created_at": "2016-11-14T23:07:54Z",
        "updated_at": "2016-11-14T23:07:54Z"
      }
    ]

GET accounts/:account_id/recommendations/:recommendation_id

Status: Closed Beta

Retrieve a specific campaign recommendation associated with this ads account.

The campaign recommendation contains a full set of changes suggested for the campaign structure represented as an object tree. The response tree is intended to work in conjunction with the Batch API endpoints, but it can also be mapped to single update endpoints as appropriate (Create for POST, Update for PUT, Delete for DELETE).

Resource URL

https://ads-api.x.com/5/accounts/:account_id/recommendations/:recommendation_id