Advertiser API
Programatically schedule campaigns and manage ads on X through this suite of APIs.
What Can You Promote?
Promoted Ads
- 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
- 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
}
2. 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
}
3. 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
}
}
}
4. 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"
}
}
}
5. 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"
}
}
}
6. 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.