** | **OAuth 2.0
Authorization Code with PKCE** | | [Tweet lookup](/x-api/posts/lookup/introduction)
Retrieve multiple Tweets with a list of IDs
[GET /2/tweets](/x-api/posts/post-lookup-by-post-ids)
Retrieve a single Tweet with an ID
[GET /2/tweets/:id](/x-api/posts/post-lookup-by-post-id) | ✅ | ✅ | ✅
Scopes:
tweet.read
users.read | | [Manage Tweets](/x-api/posts/manage-tweets/introduction)
Post a Tweet
[POST /2/tweets](/x-api/posts/creation-of-a-post)
Delete a Tweet
[DELETE /2/tweets/:id](/x-api/posts/post-delete-by-post-id) | ✅ | | ✅
Scopes:
tweet.read
tweet.write
users.read | | [Timelines](/x-api/posts/timelines/introduction)
User Tweet timeline
[GET /2/users/:id/tweets](/x-api/posts/user-posts-timeline-by-user-id)
User mention timeline
[GET /2/users/:id/mentions](/x-api/posts/user-mention-timeline-by-user-id)
Reverse chronological home timeline
[GET /2/users/:id/timelines/reverse\_cronological](/x-api/posts/timelines#user-mention-timeline-3) | ✅
✅ | ✅ | ✅
Scopes:
tweet.read
users.read
✅
Scopes:
tweet.read
users.read | | [Recent search](/x-api/posts/search/introduction#recent-search)
Search for Tweets published in the last 7 days
[GET /2/tweets/search/recent](/x-api/posts/recent-search) | ✅ | ✅ | ✅
Scopes:
tweet.read
users.read | | [Full-archive search](/x-api/posts/search/introduction#full-archive-search)
Only available to those with Academic Research access
Search the full archive of Tweets
[GET /2/tweets/search/all](/x-api/posts/full-archive-search) | | ✅ | | | [Filtered stream](/x-api/posts/filtered-stream/introduction)
Add or delete rules from your stream
[POST /2/tweets/search/stream/rules](/x-api/posts/adddelete-rules)
Retrieve your stream's rules
[GET /2/tweets/search/stream/rules](/x-api/posts/rules-lookup)
Connect to the stream
[GET /2/tweets/search/stream](/x-api/posts/filtered-stream) | | ✅ | | | [Volume streams](/x-api/posts/volume-streams/introduction)
Streams about 1% of all Tweets in real-time.
[GET /2/tweets/sample/stream](/x-api/posts/sample-stream) | | ✅ | | | [Manage Retweets](/x-api/posts/retweets/introduction#manage-retweets)
Retweet a Tweet
[POST /2/users/:id/retweets](/x-api/posts/retrieve-posts-that-repost-a-post)
Delete a Retweet
[DELETE /2/users/:id/retweets/:source\_tweet\_id](/x-api/posts/causes-the-user-in-the-path-to-unretweet-the-specified-post) | ✅ | | ✅
Scopes:
tweet.read
tweet.write
users.read | | [Retweets lookup](/x-api/posts/retweets/introduction#retweets-lookup)
Users who have Retweeted a Tweet
[GET /2/tweets/:id/retweeted\_by](/x-api/users/returns-user-objects-that-have-retweeted-the-provided-post-id) | ✅ | ✅ | ✅
Scopes:
tweet.read
users.read | | Bookmarks [lookup](/x-api/posts/bookmarks/introduction#bookmarks-lookup)
Get bookmarked Tweets
[GET /2/tweets/:id/bookmarks](/x-api/bookmarks/bookmarks-by-user) | | | ✅
Scopes:
tweet.read
users.read
bookmark.read | | [Manage Bookmarks](/x-api/posts/bookmarks/introduction#manage-bookmarks)
Bookmark a Tweet
[POST /2/tweets/:id/bookmarks](/x-api/bookmarks/add-post-to-bookmarks)
Remove a Bookmark of a Tweet
[DELETE /2/users/:id/bookmarks:tweet\_id](/x-api/bookmarks/remove-a-bookmarked-post) | | | ✅
Scopes:
tweet.read
users.read
bookmark.write | | [Manage Likes](/x-api/posts/likes/introduction#manage-likes)
Like a Tweet
[POST /2/users/:id/likes](/x-api/posts/causes-the-user-in-the-path-to-like-the-specified-post)
Undo a Like of a Tweet
[DELETE /2/users/:id/likes/:tweet\_id](/x-api/posts/causes-the-user-in-the-path-to-unlike-the-specified-post) | ✅ | | ✅
Scopes:
tweet.read
users.read
like.write | | [Likes lookup](/x-api/posts/likes/introduction#likes-lookup)
Users who have liked a Tweet
[GET /2/tweets/:id/liking\_users](/x-api/users/returns-user-objects-that-have-liked-the-provided-post-id)
Tweets liked by a user
[GET /2/users/:id/liked\_tweets](/x-api/posts/returns-post-objects-liked-by-the-provided-user-id) | ✅ | ✅ | ✅
Scopes:
tweet.read
users.read
like.read | | [Hide replies](/x-api/posts/hide-replies/introduction)
Hides or unhides a reply to a Tweet.
[PUT /2/tweets/:id/hidden](/x-api/posts/hide-replies) | ✅ | | ✅
Scopes:
tweet.read
users.read
tweet.moderate.write | | [Users lookup](/x-api/users/lookup/introduction)
Retrieve multiple users with IDs
[GET /2/users](/x-api/users/user-lookup-by-ids)
Retrieve a single user with an ID
[GET /2/users/:id](/x-api/users/user-lookup-by-id)
Retrieve multiple users with usernames
[GET /2/users/by](/x-api/users/user-lookup-by-usernames)
Retrieve a single user with a usernames
[GET /2/users/by/username/:username](/x-api/users/user-lookup-by-username)
Get information about an authenticated user
[GET /2/users/me](/x-api/users/user-lookup-me) | ✅ | ✅ | ✅
Scopes:
tweet.read
users.read | | [Manage follows](/x-api/users/follows/introduction#manage-follows)
Allows a user ID to follow another user
[POST /2/users/:id/following](/x-api/users/follow-user)
Allows a user ID to unfollow another user
[DELETE /2/users/:source\_user\_id/following/:target\_user\_id](/x-api/users/unfollow-user) | ✅ | | ✅
Scopes:
tweet.read
users.read
follows.write | | [Follows lookup](/x-api/users/follows/introduction#follows-lookup)
Lookup following of a user by ID
[GET /2/users/:id/following](/x-api/users/following-by-user-id)
Lookup followers of a user by ID
[GET /2/users/:id/followers](/x-api/users/followers-by-user-id) | ✅ | ✅ | ✅
Scopes:
tweet.read
users.read
follows.read | | [Blocks lookup](/x-api/users/blocks/introduction#blocks-lookup)
Returns a list of users who are blocked by the specified user ID
[GET /2/users/:id/blocking](/x-api/users/returns-user-objects-that-are-blocked-by-provided-user-id) | ✅ | | ✅
Scopes:
tweet.read
users.read
block.read | | [Manage Mutes](/x-api/users/mutes/introduction#manage-mutes)
Allows a user ID to mute another user
[POST /2/users/:id/muting](/x-api/users/mute-user-by-user-id)
Allows a user ID to unmute another user
[DELETE /2/users/:source\_user\_id/muting/:target\_user\_id](/x-api/users/unmute-user-by-user-id) | ✅ | | ✅
Scopes:
tweet.read
users.read
mute.write | | [Mutes lookup](/x-api/users/mutes/introduction#mutes-lookup)
Returns a list of users who are muted by the specified user ID
[GET /2/users/:id/muting](/x-api/users/returns-user-objects-that-are-muted-by-the-provided-user-id) | ✅ | | ✅
Scopes:
tweet.read
users.read
mute.read | | [Spaces lookup](/x-api/spaces/lookup/introduction)
Lookup Space by ID
[GET /2/spaces/:id](/x-api/spaces/space-lookup-by-space-id)
Lookup multiple Spaces
[GET /2/spaces](/x-api/spaces/space-lookup-up-space-ids)
Discover Spaces created by user ID
[GET /2/spaces/by/creator\_ids](/x-api/spaces/space-lookup-by-their-creators) | | ✅ | ✅
Scopes:
tweet.read
users.read
space.read | | [Spaces lookup](/x-api/spaces/lookup/introduction)
Get users who purchased a ticket to a Space
[GET /2/spaces/:id/buyers](/x-api/spaces/retrieve-the-list-of-users-who-purchased-a-ticket-to-the-given-space) | | | ✅
Scopes:
tweet.read
users.read
space.read | | [Spaces search](/x-api/spaces/search/introduction)
Returns live or scheduled Spaces matching your specified search terms.
[GET /2/spaces/search](/x-api/spaces/search-for-spaces) | | ✅ | ✅
Scopes:
tweet.read
users.read
space.read | | [List lookup](/x-api/lists/list-lookup/introduction)
Lookup a specific list by ID
[GET /2/lists/:id](/x-api/lists/list-lookup-by-list-id)
Lookup a user's owned List
[GET /2/users/:id/owned\_lists](/x-api/lists/get-a-users-owned-lists) | ✅ | ✅ | ✅
Scopes:
tweet.read
users.read
list.read | | [Manage Lists](/x-api/lists/manage-lists/introduction)
Creates a new List on behalf of an authenticated user
[POST /2/lists](/x-api/lists/create-list) | ✅ | | ✅
Scopes:
tweet.read
users.read
list.read
list.write | | [Manage Lists](/x-api/lists/manage-lists/introduction)
Deletes a List the authenticated user owns
[DELETE /2/lists/:id](/x-api/lists/delete-list)
Updates the metadata for a List the authenticated user owns
[PUT /2/lists/:id](/x-api/lists/update-list) | ✅ | | ✅
Scopes:
tweet.read
users.read
list.write | | [List Tweets lookup](/x-api/lists/list-tweets/introduction)
Lookup Tweets from a specified List
[GET /2/lists/:id/tweets](/x-api/posts/list-posts-timeline-by-list-id) | ✅ | ✅ | ✅
Scopes:
tweet.read
users.read
list.read | | [List members lookup](/x-api/lists/list-members/introduction#list-members-lookup)
Returns a list of members from a specified List
[GET /2/lists/:id/members](/x-api/users/returns-user-objects-that-are-members-of-a-list-by-the-provided-list-id)
Returns all Lists a specified user is a member of
[GET /2/users/:id/list\_memberships](/x-api/lists/get-a-users-list-memberships) | ✅ | ✅ | ✅
Scopes:
tweet.read
users.read
list.read | | [Manage List members](/x-api/lists/list-members/introduction#manage-list-members)
Add a member to a List that the authenticated user owns
[POST /2/lists/:id/members](/x-api/users/returns-user-objects-that-are-members-of-a-list-by-the-provided-list-id)
Removes a member from a List the authenticated user owns
[DELETE /2/lists/:id/members/:user\_id](/x-api/lists/remove-a-list-member) | ✅ | | ✅
Scopes:
tweet.read
users.read
list.write | | [List follows lookup](/x-api/lists/list-lookup/introduction)
Returns all followers of a specified List
[GET /2/lists/:id/followers](/x-api/users/returns-user-objects-that-follow-a-list-by-the-provided-list-id)
Returns all Lists a specified user follows
[GET /2/users/:id/followed\_lists](/x-api/lists/get-users-followed-lists) | ✅ | ✅ | ✅
Scopes:
tweet.read
users.read
list.read | | [Manage List follows](/x-api/lists/manage-lists/introduction)
Follows a List on behalf of an authenticated user
[POST /2/users/:id/followed\_lists](/x-api/lists/follow-a-list)
Unfollows a List on behalf of an authenticated user
[DELETE /2/users/:id/followed\_lists/:list\_id](/x-api/lists/unfollow-a-list) | ✅ | | ✅
Scopes:
tweet.read
users.read
list.write | | [Pinned List lookup](/x-api/lists/pinned-lists/introduction)
Returns the pinned Lists of the authenticated user
[GET /2/users/:id/pinned\_lists](/x-api/lists/get-a-users-pinned-lists) | ✅ | | ✅
Scopes:
tweet.read
users.read
list.read | | [Manage pinned List](/x-api/lists/pinned-lists/introduction)
Pins a List on behalf of an authenticated user
[POST /2/users/:id/pinned\_lists](/x-api/lists/pin-a-list)
Unpins a List on behalf of an authenticated user
[DELETE /2/users/:id/pinned\_lists/:list\_id](/x-api/lists/unpin-a-list) | ✅ | | ✅
Scopes:
tweet.read
users.read
list.write | | [Batch compliance](/x-api/compliance/batch-compliance/introduction)
Creates a new compliance job
[POST /2/compliance/jobs](/x-api/compliance/create-compliance-job)
Returns status and download information about a specified compliance job
[GET /2/compliance/jobs/:job\_id](/x-api/compliance/get-compliance-job)
Returns a list of recent compliance jobs
[GET /2/compliance/jobs](/x-api/compliance/list-compliance-jobs) | | ✅ | | # API Key and Secret Source: https://docs.x.com/fundamentals/authentication/oauth-1-0a/api-key-and-secret ### API Key and Secret The API Key and Secret (also known as Consumer Key and Secret) are the most fundamental credentials required to access the X API. These credentials act as the username and password for your X App, and are used by the X API to understand which App requests are coming from. These credentials can be used by [authentication endpoints](/resources/fundamentals/authentication/api-reference) to generate additional credentials, such as [user Access Tokens and Secrets](/resources/fundamentals/authentication/oauth-1-0a/api-key-and-secret), and [Bearer Tokens](/resources/fundamentals/authentication/oauth-2-0/bearer-tokens). You also need to use these credentials along with Access Tokens and other authorization parameters to [authorize requests](/resources/fundamentals/authentication/oauth-1-0a/authorizing-a-request) that require OAuth 1.0a User Context authentication. #### How to acquire an API Key and Secret To acquire a X API Key and Secret, please follow these steps: 1. [Sign up for a X developer account](https://developer.x.com/en/apply-for-access) 2. Create a [X App](/resources/fundamentals/developer-apps) within the [Developer Console](/resources/fundamentals/developer-portal). Note that if you would like to use [X API v2](/x-api/introduction), you must use keys and tokens from a developer App. When you create your X App, you will be presented with your API Key and Secret, along with a Bearer Token. Please note that we only display these credentials once, so make sure to save them in your password manager or somewhere secure. We have more recommendations on how to handle your keys and tokens within our [authentication best practices](/resources/fundamentals/authentication/guides/authentication-best-practices) page, including details on what you should do if your credentials have been compromised. #### How to find and regenerate your API Key and Secret after App creation If you've already created an App and need to find or regenerate your API Key and Secret, please follow these steps: 1. Navigate to the Developer Console 2. Expand the 'Apps' dropdown in the sidenav 3. Open the App which is associated with the API Key and Secret that you would like to find or regenerate 4. Navigate to the Keys and tokens tab From there, you will find all of the credentials associated with your App. #### How to use your API Key and Secret If you are just exploring the X Developer Platform, we recommend that you use a [tool or library](/resources/tools-and-libraries) to see what’s available on the platform. These tools handle authentication gracefully, and can save you a lot of time and frustration. We specifically recommend [getting started with Postman](/tutorials/postman-getting-started) or [Insomnia](https://insomnia.rest/) for beginner developers. If you are interested in building a request from scratch, please read our guide on [authorizing an OAuth 1.0a request](/resources/fundamentals/authentication/oauth-1-0a/authorizing-a-request). # Authorizing a request Source: https://docs.x.com/fundamentals/authentication/oauth-1-0a/authorizing-a-request ### Authorizing a request The purpose of this document is to show you how to modify HTTP requests for the purpose of sending authorized requests to the X API. All of X's APIs are based on the HTTP protocol. This means that any software you write which uses X's APIs sends a series of structured messages to X’s servers. For example, a request to post the text “**Hello Ladies + Gentlemen, a signed OAuth request!**” as a Tweet will look something like this: ``` POST /1.1/statuses/update.json?include_entities=true HTTP/1.1 Accept: */* Connection: close User-Agent: OAuth gem v0.4.4 Content-Type: application/x-www-form-urlencoded Content-Length: 76 Host: api.x.com status=Hello%20Ladies%20%2b%20Gentlemen%2c%20a%20signed%20OAuth%20request%21 ``` Any HTTP library should be able to generate and issue the above request with a minimum of difficulty. However, the above request is considered invalid, since there is no way of knowing: 1. Which application is making the request 2. Which user the request is posting on behalf of 3. Whether the user has granted the application authorization to post on the user’s behalf 4. Whether the request has been tampered by a third party while in transit To allow applications to provide this information, X’s API relies on the [OAuth 1.0a protocol](http://tools.ietf.org/html/rfc5849). At a very simplified level, X’s implementation requires that requests needing authorization contain an additional HTTP Authorization header with enough information to answer the questions listed above. A version of the HTTP request shown above, modified to include this header, looks like this (normally the Authorization header would need to be on one line, but has been wrapped for legibility here): ``` POST /1.1/statuses/update.json?include_entities=true HTTP/1.1 Accept: */* Connection: close User-Agent: OAuth gem v0.4.4 Content-Type: application/x-www-form-urlencoded Authorization: OAuth oauth\_consumer\_key="xvz1evFS4wEEPTGEFPHBog", oauth_nonce="kYjzVBB8Y0ZFabxSWbWovY3uYSQ2pTgmZeNu2VS4cg", oauth_signature="tnnArxj06cWHq44gCs1OSKk%2FjLY%3D", oauth\_signature\_method="HMAC-SHA1", oauth_timestamp="1318622958", oauth_token="370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb", oauth_version="1.0" Content-Length: 76 Host: api.x.com status=Hello%20Ladies%20%2b%20Gentlemen%2c%20a%20signed%20OAuth%20request%21 ``` When this request was created, it would have been accepted by the X API as valid. If this signing process sounds like it is beyond the scope of your integration, consider using [Web Intents](https://dev.x.com/web/intents), which do not need to use OAuth to interact with the X API. **Collecting parameters** You should be able to see that the header contains 7 key/value pairs, where the keys all begin with the string “oauth\_”. For any given X API request, collecting these 7 values and creating a similar header will allow you to specify authorization for the request. How each value was generated is described below: **Consumer key** The oauth\_consumer\_key identifies which application is making the request. Obtain this value from the settings page for your [X app](/resources/fundamentals/developer-apps) in the [Developer Console](/resources/fundamentals/developer-portal). | | | | :------------------- | :--------------------- | | oauth\_consumer\_key | xvz1evFS4wEEPTGEFPHBog | **Nonce** The oauth\_nonce parameter is a unique token your application should generate for each unique request. X will use this value to determine whether a request has been submitted multiple times. The value for this request was generated by base64 encoding 32 bytes of random data, and stripping out all non-word characters, but any approach which produces a relatively random alphanumeric string should be OK here. | | | | :----------- | :----------------------------------------- | | oauth\_nonce | kYjzVBB8Y0ZFabxSWbWovY3uYSQ2pTgmZeNu2VS4cg | **Signature** The oauth\_signature parameter contains a value which is generated by running all of the other request parameters and two secret values through a signing algorithm. The purpose of the signature is so that X can verify that the request has not been modified in transit, verify the application sending the request, and verify that the application has authorization to interact with the user’s account. The process for calculating the oauth\_signature for this request is described in [Creating a signature](/resources/fundamentals/authentication/oauth-1-0a/creating-a-signature). | | | | :--------------- | :--------------------------- | | oauth\_signature | tnnArxj06cWHq44gCs1OSKk/jLY= | **Signature method** The oauth\_signature\_method used by X is HMAC-SHA1. This value should be used for any authorized request sent to X’s API. | | | | :----------------------- | :-------- | | oauth\_signature\_method | HMAC-SHA1 | **Timestamp** The oauth\_timestamp parameter indicates when the request was created. This value should be the number of seconds since the Unix epoch at the point the request is generated, and should be easily generated in most programming languages. X will reject requests which were created too far in the past, so it is important to keep the clock of the computer generating requests in sync with NTP. | | | | :--------------- | :--------- | | oauth\_timestamp | 1318622958 | **Token** The oauth\_token parameter typically represents a user’s permission to share access to their account with your application. There are a few authentication requests where this value is not passed or is a different form of token, but those are covered in detail in [Obtaining access tokens](/resources/fundamentals/authentication/oauth-1-0a/obtaining-user-access-tokens). For most general-purpose requests, you will use what is referred to as an **access token**. You can generate a valid [access token](/resources/fundamentals/authentication/oauth-1-0a/obtaining-user-access-tokens) for your account on the settings page for your [X app](/resources/fundamentals/developer-apps) on the [Developer Console](/resources/fundamentals/developer-portal). | | | | :----------- | :------------------------------------------------- | | oauth\_token | 370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb | **Version** The oauth\_version parameter should always be 1.0 for any request sent to the X API. | | | | :------------- | :-- | | oauth\_version | 1.0 | #### Building the header string To build the header string, imagine writing to a string named DST. 1. Append the string “OAuth ” (including the space at the end) to DST. 2. For each key/value pair of the 7 parameters listed above: 1. [Percent encode](/resources/fundamentals/authentication/oauth-1-0a/obtaining-user-access-tokens) the key and append it to DST. 2. Append the equals character ‘=’ to DST. 3. Append a double quote ‘”’ to DST. 4. [Percent encode](/resources/fundamentals/authentication/oauth-1-0a/obtaining-user-access-tokens) the value and append it to DST. 5. Append a double quote ‘”’ to DST. 6. If there are key/value pairs remaining, append a comma ‘,’ and a space ‘ ‘ to DST. Pay particular attention to the percent encoding of the values when building this string. For example, the oauth\_signature value of tnnArxj06cWHq44gCs1OSKk/jLY= must be encoded as tnnArxj06cWHq44gCs1OSKk%2FjLY%3D. Performing these steps on the parameters collected above results in the following string: ``` OAuth oauth\_consumer\_key="xvz1evFS4wEEPTGEFPHBog", oauth\_nonce="kYjzVBB8Y0ZFabxSWbWovY3uYSQ2pTgmZeNu2VS4cg", oauth\_signature="tnnArxj06cWHq44gCs1OSKk%2FjLY%3D", oauth\_signature\_method="HMAC-SHA1", oauth\_timestamp="1318622958", oauth\_token="370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb", oauth_version="1.0" ``` This value should be set as the Authorization header for the request. # Creating a signature Source: https://docs.x.com/fundamentals/authentication/oauth-1-0a/creating-a-signature ### Creating a signature This page explains how to generate an OAuth 1.0a HMAC-SHA1 signature for an HTTP request. This signature will be suitable for passing to the X API as part of an authorized request, as described in [authorizing a request.](/resources/fundamentals/authentication/oauth-1-0a/authorizing-a-request) The request used to demonstrate signing is a POST to [https://api.x.com/1.1/statuses/update.json](https://api.x.com/1.1/statuses/update.json). The raw request looks like this: ``` POST /1.1/statuses/update.json?include_entities=true HTTP/1.1 Accept: */* Connection: close User-Agent: OAuth gem v0.4.4 Content-Type: application/x-www-form-urlencoded Content-Length: 76 Host: api.x.com status=Hello%20Ladies%20%2b%20Gentlemen%2c%20a%20signed%20OAuth%20request%21 ``` **Collecting the request method and URL** To produce a signature, start by determining the HTTP method and URL of the request. These two are known when creating the request, so they are easy to obtain. The request method will almost always be GET or POST for X API requests. | | | | :---------- | :--- | | HTTP Method | POST | The base URL is the URL to which the request is directed, minus any query string or hash parameters. It is important to use the correct protocol here, so make sure that the “https\://” portion of the URL matches the actual request sent to the API. | | | | :------- | :--------------------------------------------------------------------------------------- | | Base URL | [https://api.x.com/1.1/statuses/update.json](https://api.x.com/1.1/statuses/update.json) | #### Collecting parameters Next, gather all of the parameters included in the request. There are two such locations for these additional parameters - the URL (as part of the query string) and the request body. The sample request includes a single parameter in both locations: ``` POST /1.1/statuses/update.json?include_entities=true HTTP/1.1 Accept: */* Connection: close User-Agent: OAuth gem v0.4.4 Content-Type: application/x-www-form-urlencoded Content-Length: 76 Host: api.x.com status=Hello%20Ladies%20%2b%20Gentlemen%2c%20a%20signed%20OAuth%20request%21 ``` An HTTP request has parameters that are URL encoded, but you should collect the raw values. In addition to the request parameters, every oauth\_\* parameter needs to be included in the signature, so collect those too. Here are the parameters from [authorizing a request](/resources/fundamentals/authentication/oauth-1-0a/authorizing-a-request): | | | | :----------------------- | :------------------------------------------------- | | status | Hello Ladies + Gentlemen, a signed OAuth request! | | include\_entities | true | | oauth\_consumer\_key | xvz1evFS4wEEPTGEFPHBog | | oauth\_nonce | kYjzVBB8Y0ZFabxSWbWovY3uYSQ2pTgmZeNu2VS4cg | | oauth\_signature\_method | HMAC-SHA1 | | oauth\_timestamp | 1318622958 | | oauth\_token | 370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb | | oauth\_version | 1.0 | These values need to be encoded into a single string, which will be used later on. The process to build the string is very specific: 1. [Percent encode](/resources/fundamentals/authentication/oauth-1-0a/percent-encoding-parameters) every key and value that will be signed. 2. Sort the list of parameters alphabetically [\[1\]](/resources/fundamentals/authentication/oauth-1-0a/creating-a-signature) by encoded key [\[2\]](/resources/fundamentals/authentication/oauth-1-0a/creating-a-signature). 3. For each key/value pair: 4. Append the encoded key to the output string. 5. Append the ‘=’ character to the output string. 6. Append the encoded value to the output string. 7. If there are more key/value pairs remaining, append a ‘&’ character to the output string. \[1] The OAuth spec says to sort lexicographically, which is the default alphabetical sort for many libraries. \[2] In the case of two parameters with the same encoded key, the OAuth spec says to continue sorting based on value. However, X does not accept duplicate keys in API requests **Parameter string** The following *parameter string* will be produced by repeating these steps with the parameters collected above: | status | Hello Ladies + Gentlemen, a signed OAuth request! | | :----------------------- | :------------------------------------------------- | | `include_entities` | true | | `oauth_consumer_key` | xvz1evFS4wEEPTGEFPHBog | | `oauth_nonce` | kYjzVBB8Y0ZFabxSWbWovY3uYSQ2pTgmZeNu2VS4cg | | `oauth_signature_method` | HMAC-SHA1 | | `oauth_timestamp` | 1318622958 | | `oauth_token` | 370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb | | `oauth_version` | 1.0 | #### Creating the signature base string The three values collected so far must be joined to make a single string, from which the signature will be generated. This is called the **signature base string** by the OAuth specification. To encode the HTTP method, base URL, and parameter string into a single string: 1. Convert the HTTP Method to uppercase and set the output string equal to this value. 2. Append the ‘&’ character to the output string. 3. [Percent encode](/resources/fundamentals/authentication/oauth-1-0a/percent-encoding-parameters) the URL and append it to the output string. 4. Append the ‘&’ character to the output string. 5. [Percent encode](/resources/fundamentals/authentication/oauth-1-0a/percent-encoding-parameters) the parameter string and append it to the output string. This will produce the following *signature base string*: ``` POST&https%3A%2F%2Fapi.x.com%2F1.1%2Fstatuses%2Fupdate.json&include_entities%3Dtrue%26oauth_consumer_key%3Dxvz1evFS4wEEPTGEFPHBog%26oauth_nonce%3DkYjzVBB8Y0ZFabxSWbWovY3uYSQ2pTgmZeNu2VS4cg%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1318622958%26oauth_token%3D370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb%26oauth_version%3D1.0%26status%3DHello%2520Ladies%2520%252B%2520Gentlemen%252C%2520a%2520signed%2520OAuth%2520request%2521 ``` Make sure to percent encode the parameter string. The signature base string should contain exactly 2 ampersand ‘&’ characters. The percent ‘%’ characters in the parameter string should be encoded as %25 in the signature base string. #### Getting a signing key The last pieces of data to collect are secrets which identify the [X app](/resources/fundamentals/developer-apps) making the request, and the user the request is on behalf of. It is very important to note that these values are incredibly sensitive and should never be shared with anyone. The value which identifies your app to X is called the **consumer secret** and can be found in the [Developer Console](/resources/fundamentals/developer-portal) by viewing the [app details page](/resources/fundamentals/developer-apps). This will be the same for every request your X app sends. | | | | :-------------- | :------------------------------------------ | | Consumer secret | kAcSOqF21Fu85e7zjz7ZN2U4ZRhfV3WpwPAoE3Z7kBw | The value which identifies the account your application is acting on behalf of is called the **OAuth token secret**. This value can be obtained in several ways, all of which are described in [obtaining access tokens](/resources/fundamentals/authentication/oauth-1-0a/obtaining-user-access-tokens). | | | | :----------------- | :---------------------------------------- | | OAuth token secret | LswwdoUaIvS8ltyTt5jkRh4J50vUPVVHtR2YPi5kE | Once again, it is very important to keep these values private to your application. If you feel that your values have been compromised, regenerate your tokens (the tokens on this page have been marked as invalid for real requests). Both of these values need to be combined to form a **signing key** which will be used to generate the signature. The signing key is simply the [percent encoded](/resources/fundamentals/authentication/oauth-1-0a/percent-encoding-parameters) token secret: Note that there are some flows, such as when obtaining a [request token](/resources/fundamentals/authentication/oauth-1-0a/obtaining-user-access-tokens), where the token secret is not yet known. In this case, the signing key should consist of the [percent encoded](/resources/fundamentals/authentication/oauth-1-0a/percent-encoding-parameters) **consumer secret** followed by an ampersand character ‘&’. | | | | :---------- | :------------------------------------------------------------------------------------- | | Signing key | kAcSOqF21Fu85e7zjz7ZN2U4ZRhfV3WpwPAoE3Z7kBw\&LswwdoUaIvS8ltyTt5jkRh4J50vUPVVHtR2YPi5kE | #### Calculating the signature Finally, the signature is calculated by passing the signature base string and signing key to the HMAC-SHA1 hashing algorithm. The details of the algorithm are explained as hash\_hmac function. The output of the HMAC signing function is a binary string. This needs to be base64 encoded to produce the signature string. For example, the output given the base string and signing key given on this page is 2E CF 77 84 98 99 6D 0D DA 90 5D C7 17 7C 75 07 3F 3F CD 4E. That value, when converted to base64, is the OAuth signature for this request: | | | | :-------------- | :--------------------------- | | OAuth signature | Ls93hJiZbQ3akF3HF3x1Bz8/zU4= | # OAuth Echo Source: https://docs.x.com/fundamentals/authentication/oauth-1-0a/oauth-echo ### OAuth Echo OAuth Echo is a means to securely delegate OAuth authorization with a third party while interacting with an API. There are four parties involved in this interaction: * **the User** who is using X through a particular, authorized X application * **the Consumer**, or the X application that is attempting to interact with the 3rd party media provider (e.g. the photo-sharing site) * **the Delegator**, or the 3rd party media provider * **the Service Provider** a.k.a. X itself Essentially, prepare a request for the delegator to send to the X API on behalf of an application and a user. Add what would otherwise be a signed OAuth request into an HTTP header and ask the delegator to send that request to X after completing the intermediary operation. Here’s an example: the User wants to upload a photo. The Consumer is going to call upload on the Delegator with a POST. The POST should contain the image, but it should also contain two additional items as HTTP headers: * `x-auth-service-provider` — effectively, this is the realm that identity delegation should be sent to — in the case of X, set this to [https://api.x.com/1.1/account/verify\_credentials.json](https://api.x.com/1.1/account/verify_credentials.json). iOS5-based X integrations will add an additional application\_id parameter to this URL that will also be used to calculate the oauth\_signature used in x-verify-credentials-authorization. * `x-verify-credentials-authorization` — Consumer should create all the OAuth parameters necessary so it could call [https://api.x.com/1.1/account/verify\_credentials.json](https://api.x.com/1.1/account/verify_credentials.json) using OAuth in the HTTP header (e.g. it should look like OAuth oauth\_consumer\_key=”...”, oauth\_token=”...”, oauth\_signature\_method=”...”, oauth\_signature=”...”, oauth\_timestamp=”...”, oauth\_nonce=”...”, oauth\_version=”...” ). Keep in mind that the entire transaction period needs to occur within an amount of time where the `oauth_timestamp` will still be valid. Alternatively, instead of sending these two parameters in the header, they could be sent in the POST as x\_auth\_service\_provider and x\_verify\_credentials\_authorization — in this case, remember to escape and include the parameters in the OAuth signature base string — similar to encoding parameters in any request. It’s best to use HTTP headers to keep the operations as separate as possible. The Delegators goal, at this point, is to verify that the User is who they say they are before it saves the media. Once the Delegator receives all the data above via its upload method, it should temporarily store the image, and then construct a call to the endpoint specified in the x-auth-service-provider header — in this case, [https://api.x.com/1.1/account/verify\_credentials.json](https://api.x.com/1.1/account/verify_credentials.json), using the same OAuth authentication header provided by the Consumer in the x-verify-credentials-authorization header. #### OAuth Echo best practices Use the URL provided by `x-auth-service-provider` to perform the lookup, *not* a hard-coded value. Apple iOS, for example, adds an additional application\_id parameter to all OAuth requests, and its existence should be maintained at each stage of OAuth Echo. For the OAuth authorization portion, take the header value in x-verify-credentials-authorization, and place that into its own Authorization header for its call to the service provider. For good measure, confirm that the value in `x-auth-service-provider` is what it should be. * If the Service Provider returns an HTTP 200, then good. The Delegator should permanently store the image, generate a URL, and return it. * If the Service Provider doesn’t return an HTTP 200, then dump the image, and then return an error back to the Consumer. # Obtaining Access Tokens using 3-legged OAuth flow Source: https://docs.x.com/fundamentals/authentication/oauth-1-0a/obtaining-user-access-tokens ### Obtaining Access Tokens using 3-legged OAuth flow To perform actions on behalf of another user, you'll need to obtain their access tokens. Access tokens specify the X account the request is made on behalf of, so for you to obtain these they will need to first grant you access. These tokens do not expire but can be revoked by the user at any time. X allows you to obtain user access tokens through the 3-legged OAuth flow, which allows your application to obtain an **access token** and access token secret by redirecting a user to X and having them authorize your application. This flow is almost identical to the flow described in [implementing Log in with X](/resources/fundamentals/authentication/guides/log-in-with-x), with two exceptions: * The [GET oauth/authorize](/resources/fundamentals/authentication/api-reference#get-oauth-authorize) endpoint is used instead of [GET oauth/authenticate](/resources/fundamentals/authentication/api-reference#get-oauth-authenticate). * The user will **always** be prompted to authorize access to your application, even if access was previously granted. Before you get started, you will need to check your [application's](/resources/fundamentals/developer-apps) permissions and know the consumer keys and callback URL. If you don't have a callback URL or publicly accessible UI, consider using [PIN-based authorization](/resources/fundamentals/authentication/oauth-1-0a/pin-based-oauth), which is intended for applications that cannot access or embed a web browser in order to redirect the user after authorization. The possible states for the 3-legged sign in interaction are illustrated in the following flowchart:  #### Overview of the process At a high level, the 3-Legged OAuth process will: 1. Create a request for a consumer application to obtain a request token. 2. Have the user authenticate, and send the consumer application a request token. 3. Convert the request token into a usable user access token. **Terminology clarification** In the guide below, you may see different terms referring to the same thing. **Client credentials:** * App Key === API Key === Consumer API Key === Consumer Key === Customer Key === `oauth_consumer_key` * App Key Secret === API Secret Key === Consumer Secret === Consumer Key === Customer Key === `oauth_consumer_secret` * Callback URL === `oauth_callback` **Temporary credentials:** * Request Token === `oauth_token` * Request Token Secret === `oauth_token_secret` * oauth\_verifier **Token credentials:** * Access token === Token === resulting `oauth_token` * Access token secret === Token Secret === resulting `oauth_token_secret` #### Walkthrough steps **Step 1: [POST oauth/request\_token](/resources/fundamentals/authentication/api-reference#post-oauth-request-token)** Create a request for a consumer application to obtain a request token. The only unique parameter in this request is oauth\_callback, which must be a [URL encoded](/resources/fundamentals/authentication/oauth-1-0a/percent-encoding-parameters) version of the URL you wish your user to be redirected to when they complete step 2. The remaining parameters are added by the OAuth signing process. Please note - any callback URL that you use with the [POST oauth/request\_token](/resources/fundamentals/authentication/api-reference#post-oauth-request-token) endpoint will have to be configured within your [developer App's](/resources/fundamentals/developer-apps) settings in the app details page of Developer Console. **Request includes:** `oauth_callback="https%3A%2F%2FyourCallbackUrl.com"` `oauth_consumer_key="cChZNFj6T5R0TigYB9yd1w" ` Your app should examine the HTTP status of the response. Any value other than 200 indicates a failure. The body of the response will contain the `oauth_token`, `oauth_token_secret`, and `oauth_callback_confirmed` parameters. Your app should verify that `oauth_callback_confirmed` is true and store the other two values for the next steps. **Response includes** `oauth_token=NPcudxy0yU5T3tBzho7iCotZ3cnetKwcTIRlX0iwRl0` `oauth_token_secret=veNRnAWe6inFuo8o2u8SLLZLjolYDmDP7SzL0YfYI` `oauth_callback_confirmed=true` **Step 2: [GET oauth/authorize](/resources/fundamentals/authentication/api-reference#get-oauth-authorize)** Have the user authenticate, and send the consumer application a request token. **Example URL to redirect user to:** `https://api.x.com/oauth/authorize?oauth_token=NPcudxy0yU5T3tBzho7iCotZ3cnetKwcTIRlX0iwRl0` Upon successful authentication, your `callback_url` would receive a request containing the `oauth_token` and `oauth_verifier` parameters. Your application should verify that the token matches the request token received in step 1. **Request from client’s redirect:** `https://yourCallbackUrl.com?oauth_token=NPcudxy0yU5T3tBzho7iCotZ3cnetKwcTIRlX0iwRl0&oauth_verifier=uw7NjWHT6OJ1MpJOXsHfNxoAhPKpgI8BlYDhxEjIBY` **Step 3: [POST oauth/access\_token](/resources/fundamentals/authentication/api-reference#post-oauth-access-token)** Convert the request token into a usable access token. To render the request token into a usable access token, your application must make a request to the [POST oauth/access\_token](/resources/fundamentals/authentication/api-reference#post-oauth-access-token) endpoint, containing the `oauth_verifier` value obtained in step 2. The request token is also passed in the `oauth_token` portion of the header, but this will have been added by the signing process. **Request includes:** `POST /oauth/access_token` `oauth_consumer_key=cChZNFj6T5R0TigYB9yd1w` `oauth_token=NPcudxy0yU5T3tBzho7iCotZ3cnetKwcTIRlX0iwRl0` `oauth_verifier=uw7NjWHT6OJ1MpJOXsHfNxoAhPKpgI8BlYDhxEjIBY` A successful response contains the `oauth_token`, `oauth_token_secret` parameters. The token and token secret should be stored and used for future authenticated requests to the X API. To determine the identity of the user, use [GET account/verify\_credentials](/resources/fundamentals/authentication/api-reference). **Response includes:** `oauth_token=7588892-kagSNqWge8gB1WwE3plnFsJHAZVfxWD7Vb57p0b4` `oauth_token_secret=PbKfYqSryyeKDWz4ebtY3o5ogNLG11WJuZBc9fQrQo` **Using these credentials for OAuth 1.0a (application-user) required requests** Now you've obtained the user access tokens; you can use them to access certain APIs such as [POST statuses/update](/x-api/posts/manage-tweets/introduction) to create Tweets on the users' behalf. **Request includes:** `POST statuses/update.json` `oauth_consumer_key=cChZNFj6T5R0TigYB9yd1w` `oauth_token=7588892-kagSNqWge8gB1WwE3plnFsJHAZVfxWD7Vb57p0b4` #### Sample use case The standard flow is web-based and uses the 3-legged authorization OAuth flow. The screenshots outlined here are part of a sample that you can view the source of at [https://github.com/xdevplatform/twauth-web](https://github.com/xdevplatform/twauth-web). At some point in your application, you will want to redirect to X in order to authorize your application.
key (does not change) | xvz1evFS4wEEPTGEFPHBog | | RFC 1738 encoded consumer
secret (does not change) | L8qq9PZyRg6ieKGEKhZolGC0vJWLw8iEJ88DRdyOg | | Bearer Token credentials | xvz1evFS4wEEPTGEFPHBog:L8qq9PZyRg6ieKGEKhZolGC0vJWLw8iEJ88DRdyOg | | Base64 encoded Bearer Token credentials | :: eHZ6MWV2RlM0d0VFUFRHRUZQSEJvZzpMOHFxOVBaeVJnNmllS0dFS2hab2xHQzB2SldMdzhpRUo4OERSZHlPZw== | **Step 2: Obtain an App only Access Token (Bearer Token)** The value calculated in step 1 must be exchanged for an App only Access Token by issuing a request to [POST oauth2/token](/resources/fundamentals/authentication/api-reference#post-oauth2-token): * The request must be an HTTP POST request. * The request must include an `Authorization` header with the value of `Basic
[**Learn More**](/resources/fundamentals/authentication/oauth-1-0a/api-key-and-secret)
[**Learn More**](/resources/fundamentals/authentication/oauth-2-0/overview)
[**Learn More**](/resources/fundamentals/authentication/basic-auth)
[**Learn More**](/resources/fundamentals/authentication/oauth-2-0/authorization-code)
Owned Reads let you access your own data at reduced cost. Requests for your own posts, bookmarks, followers, likes, and more are priced at \$0.001 per resource.
[**View tutorial**](/tutorials/explore-a-users-posts)
[**View tutorial**](/tutorials/postman-getting-started)
[**View tutorial**](/tutorials/getting-started-with-r-and-v2-of-the-x-api)
[**View tutorial**](/tutorials/getting-historical-posts-using-the-full-archive-search-endpoint)
[**View tutorial**](/tutorials/post-processing-x-data-with-the-google-cloud-platform)
(lightweight)"] --> B["Memory Buffer
(FIFO)"] --> C["Processing Thread(s)
(heavy work)"] ``` *** ## Next steps
← conversation_id for all replies"] --> B["Reply 1 (ID: 1234567891)
conversation_id: 1234567890"] A --> C["Reply 2 (ID: 1234567892)
conversation_id: 1234567890"] B --> D["Reply to Reply 1
conversation_id: 1234567890"] C --> E["Reply to Reply 2
conversation_id: 1234567890"] ``` No matter how deep the thread goes, all posts share the same `conversation_id`. *** ## Requesting conversation\_id Add `conversation_id` to your `tweet.fields`: ```bash theme={null} curl "https://api.x.com/2/tweets/1234567891?tweet.fields=conversation_id,in_reply_to_user_id,referenced_tweets" \ -H "Authorization: Bearer $TOKEN" ``` Response: ```json theme={null} { "data": { "id": "1234567891", "text": "@user Great point!", "conversation_id": "1234567890", "in_reply_to_user_id": "2244994945", "referenced_tweets": [{ "type": "replied_to", "id": "1234567890" }] } } ``` *** ## Getting a full conversation Use `conversation_id` as a search operator to retrieve all posts in a thread: ```bash theme={null} curl "https://api.x.com/2/tweets/search/recent?\ query=conversation_id:1234567890&\ tweet.fields=author_id,created_at,in_reply_to_user_id&\ expansions=author_id" \ -H "Authorization: Bearer $TOKEN" ``` This returns all replies to the original post, sorted reverse-chronologically. *** ## Use cases
`"id": "2244994945"` | Use this to programmatically retrieve information about a specific Twitter user. | | name (default) | string | The name of the user, as they’ve defined it on their profile. Not necessarily a person’s name. Typically capped at 50 characters, but subject to change.
`"name": "Twitter Dev"` | | | username (default) | string | The Twitter screen name, handle, or alias that this user identifies themselves with. Usernames are unique but subject to change. Typically a maximum of 15 characters long, but some historical accounts may exist with longer names.
`"username": "TwitterDev"` | | | affiliation | object | Contains details about a user's affiliation. | Can be used to get a user's affiliate badge. | | confirmed\_email | string | The confirmed email of the authenticated user. | | | connection\_status | array | Provides a list of relation between the authenticating user and the user being looked up such as following, followed, follow request sent, follow request received, blocking, muting
"connection\_status": \[
"follow\_request\_received",
"follow\_request\_sent",
"blocking",
"followed\_by",
"following",
"muting"
] | Can be used to determine the connection status between the authenticating user and the user being looked up. | | created\_at | date (ISO 8601) | The UTC datetime that the user account was created on Twitter.
`"created_at": "2013-12-14T04:35:55.000Z"` | Can be used to determine how long a someone has been using Twitter | | description | string | The text of this user's profile description (also known as bio), if the user provided one.
`"description": "The voice of the X Dev team and your official source for updates, news, and events, related to the X API."` | | | entities | object | Contains details about text that has a special meaning in the user's description.
`"entities": {
"url": {
"urls": [
{
"start": 0,
"end": 23,
"url": "https://t.co/3ZX3TNiZCY",
"expanded_url": "/content/developer-twitter/en/community",
"display_url": "developer.x.com/en/community"
}
]
},
"description": {
"urls": [
{
"start": 0,
"end": 23,
"url": "https://t.co/3ZX3TNiZCY",
"expanded_url": "/content/developer-twitter/en/community",
"display_url": "developer.x.com/en/community"
},
"hashtags": [
{
"start": 23,
"end": 30,
"tag": "DevRel"
},
{
"start": 113,
"end": 130,
"tag": "BlackLivesMatter"
},
"mentions": [
{
"start": 0,
"end": 10,
"tag": "TwitterDev"
},
"cashtags": [
{
"start": 12,
"end": 16,
"tag": "twtr"
}
]
}
}` | Entities are JSON objects that provide additional information about hashtags, urls, user mentions, and cashtags associated with the description. Reference each respective entity for further details.
All user ******start****** indices are inclusive, while all user ******end****** indices are exclusive. | | is\_identity\_verified | boolean | Indicates if the user is ID verified. | | | location | string | The location specified in the user's profile, if the user provided one. As this is a freeform value, it may not indicate a valid location, but it may be fuzzily evaluated when performing searches with location queries.
`"location": "127.0.0.1"` | | | most\_recent\_tweet\_id | string | Unique identifier of this user's most recent Tweet. | Determine the most recent Tweet of the user. | | parody | boolean | Indicates whether or not this user account has the Parody label. | | | pinned\_tweet\_id | string | Unique identifier of this user's pinned Tweet.
`"pinned_tweet_id": "1255542774432063488"` | Determine the Tweet pinned to the top of the user’s profile. Can potentially be used to determine the user’s language. | | profile\_banner\_url | string | The URL to the profile banner for this user, as shown on the user's profile.
`"profile_banner_url": "https://pbs.twimg.com/profile_banners/1716450569358098432/1721022977"` | Can be used to download this user's profile banner. | | profile\_image\_url | string | The URL to the profile image for this user, as shown on the user's profile.
`"profile_image_url": "https://pbs.twimg.com/profile_images/1267175364003901441/tBZNFAgA_normal.jpg"` | Can be used to download this user's profile image. | | protected | boolean | Indicates if this user has chosen to protect their Tweets (in other words, if this user's Tweets are private).
`"protected": false` | | | public\_metrics | object | Contains details about activity for this user.
`"public_metrics": { "followers_count": 507902, "following_count": 1863, "tweet_count": 3561, "listed_count": 1550 }` | Can potentially be used to determine a Twitter user’s reach or influence, quantify the user’s range of interests, and the user’s level of engagement on Twitter. | | receives\_your\_dm | boolean | Indicates whether or not this user will receive the authenticated user's DM. | | | subscription | object | Contains details on whether or not the user is subscribed to the authenticated user. | | | subscription\_type | string | A string representing the type of X Premium subscription the authenticated user has. Example: `None`, `Basic`, `Premium`,`PremiumPlus`. Will always return `None` if the user is not the authenticated user. | | | url | string | The URL specified in the user's profile, if present.
`"url": "https://t.co/3ZX3TNiZCY"` | A URL provided by a Twitter user in their profile. This could be a homepage, but is not always the case. | | verified | boolean | Indicates if this user is a verified Twitter User.
`"verified": true` | Indicates whether or not this Twitter user has a verified account. A verified account lets people know that an account of public interest is authentic. | | verified\_followers\_count | string | A string representing the number of verified followers of a user. | | | verified\_type | string | A string representing the type of verification a user has. Example: "blue", "business", "government" | | | withheld | object | Contains withholding details for [withheld content](https://help.x.com/en/rules-and-policies/tweet-withheld-by-country), if applicable. | | **Retrieving a user object** **Sample Request** In the following request, we are requesting fields for the user on the [users lookup](/x-api/users/lookup/introduction) endpoint. Be sure to replace `$BEARER_TOKEN` with your own generated [Bearer Token](/resources/fundamentals/authentication#using-and-generating-an-app-only-bearer-token). ```{ theme={null} curl --request GET 'https://api.x.com/2/users? ids=2244994945&user.fields=created_at,description,entities,id,location,name,pinned_tweet_id,profile_image_url,protected,url,username,verified,withheld&expansions=pinned_tweet_id' --header 'Authorization: Bearer $BEARER_TOKEN' } ``` **Sample Response** ```{ theme={null} "data": [ { "id": "2244994945", "name": "Twitter Dev", "username": "TwitterDev", "location": "127.0.0.1", "entities": { "url": { "urls": [ { "start": 0, "end": 23, "url": "https://t.co/3ZX3TNiZCY", "expanded_url": "/content/developer-twitter/en/community", "display_url": "developer.x.com/en/community" } ] }, "description": { "hashtags": [ { "start": 23, "end": 30, "tag": "DevRel" }, { "start": 113, "end": 130, "tag": "BlackLivesMatter" } ] } }, "verified": true, "description": "The voice of Twitter's #DevRel team, and your official source for updates, news, & events about Twitter's API. \n\n#BlackLivesMatter", "url": "https://t.co/3ZX3TNiZCY", "profile_image_url": "https://pbs.twimg.com/profile_images/1267175364003901441/tBZNFAgA_normal.jpg", "protected": false, "pinned_tweet_id": "1255542774432063488", "created_at": "2013-12-14T04:35:55.000Z" } ], "includes": { "tweets": [ { "id": "1255542774432063488", "text": "During these unprecedented times, what’s happening on Twitter can help the world better understand & respond to the pandemic. \n\nWe're launching a free COVID-19 stream endpoint so qualified devs & researchers can study the public conversation in real-time. https://t.co/BPqMcQzhId" } ] } } ``` ### Space Spaces allow expression and interaction via live audio conversations. The Space data dictionary contains relevant metadata about a Space; all the details are updated in real time. User objects can be found and expanded in the user resource. These objects are available for expansion by adding at least one of `host_ids`, `creator_id`, `speaker_ids`, `mentioned_user_ids` to the `expansions` query parameter. Unlike Tweets, Spaces are ephemeral and become unavailable after they end or when they are canceled by their creator. When your app handles Spaces data, you are responsible for returning the most up-to-date information and must remove data that is no longer available from the platform. The [Spaces lookup endpoints](/x-api/spaces/lookup/introduction) can help you ensure you respect the users’ expectations and intent. | Field Value | Type | Description | How it can be used | | :----------------- | :-------------- | :------------------------------------------------------------------------------------------ | :------------------------------------------------------ | | id (default) | string | The unique identifier of the requested Space.
`"id": "1zqKVXPQhvZJB"` | Uniquely identify a Space returned in the response. | | state (default) | string | Indicates if the Space has started, will start, or has ended.
`"state": "live"` | Filter live or scheduled Spaces. | | created\_at | date (ISO 8601) | Creation time of this Space.
`"created_at": "2021-07-04T23:12:08.000Z"` | Understand when a Space was created and sort by time. | | creator\_id | string | Unique identifier of the Space creator.
`"creator_id": "2244994945"` | | | ended\_at | date (ISO 8601) | Time when the Space ended, if applicable.
`"ended_at": "2021-07-04T00:11:44.000Z"` | Determine when a live Space ended for runtime duration. | | host\_ids | array | Unique identifiers of the Space hosts.
`"host_ids": ["2244994945", "6253282"]` | Expand User objects, understand engagement. | | lang | string | Language of the Space, if detected.
`"lang": "en"` | Classify Spaces by language. | | is\_ticketed | boolean | Indicates if this is a ticketed Space.
`"is_ticketed": false` | Highlight content of interest. | | invited\_user\_ids | array | List of user IDs invited as speakers.
`"invited_user_ids": ["2244994945", "6253282"]` | Expand User objects, understand engagement. | | participant\_count | integer | Number of users in the Space, including Hosts and Speakers.
`"participant_count": 420` | Understand engagement, create reports. | | subscriber\_count | integer | Number of people who set a reminder for a Space.
`"subscriber_count": 36` | Understand event interest. | | scheduled\_start | date (ISO 8601) | Scheduled start time of the Space.
`"scheduled_start": "2021-07-14T08:00:00.000Z"` | Integrate with calendar notifications. | | speaker\_ids | array | List of users who spoke at any point.
`"speaker_ids": ["2244994945", "6253282"]` | Expand User objects, understand engagement. | | started\_at | date (ISO 8601) | Actual start time of a Space.
`"started_at": "2021-07-14T08:00:12.000Z"` | Determine Space start time. | | title | string | Title of the Space.
`"title": "Say hello to the Space data object!"` | Understand keywords, hashtags, mentions. | | topic\_ids | array | IDs of topics selected by the Space creator.
`"topic_ids": ["2244994945", "6253282"]` | Understand keywords, hashtags, mentions. | | updated\_at | date (ISO 8601) | Last update to Space metadata.
`"updated_at": "2021-07-11T14:44:44.000Z"` | Keep information up to date. | \*\*Retrieving a Space Object \*\* **Sample Request** In the following request, we are requesting fields for the Space on the [Spaces lookup endpoint](/x-api/spaces/lookup/introduction). Be sure to replace `$BEARER_TOKEN` with your own generated [Bearer Token](/resources/fundamentals/authentication#using-and-generating-an-app-only-bearer-token). ```bash theme={null} curl "https://api.x.com/2/spaces/1DXxyRYNejbKM?space.fields=created_at,creator_id,created_athost_ids,lang,is_ticketed,invited_user_ids,participant_count,scheduled_start,speaker_ids,started_at,state,title,updated_at&expansions=creator_id,host_ids,invited_user_ids,speaker_ids" --header "Authorization: Bearer $BEARER_TOKEN" ``` \*\* Sample Response \*\* ``` { "data": { "id": "1zqKVXPQhvZJB", "state": "live", "created_at": "2021-07-04T23:12:08.000Z", "host_ids": [ "2244994945", "6253282" ], "lang": "en", "is_ticketed": false, "invited_user_ids": [ "2244994945", "6253282" ], "participant_count": 420, "scheduled_start": "2021-07-14T08:00:00.000Z", "speaker_ids": [ "2244994945", "6253282" ], "started_at": "2021-07-14T08:00:12.000Z", "title": "Say hello to the Space data object!", "updated_at": "2021-07-11T14:44:44.000Z" }, "includes": { "users": [ { "id": "2244994945", "name": "Twitter Dev", "username": "TwitterDev" }, { "id": "6253282", "name": "Twitter API", "username": "TwitterAPI" } ] } } ``` ### List The list object contains [Twitter Lists](https://help.x.com/en/using-twitter/twitter-lists) metadata describing the referenced List. The List object is the primary object returned in the List lookup endpoint. When requesting additional List fields on this endpoint, simply use the fields parameter `list.fields`. The List object is not found as a child of other data objects. However, user objects can be found and expanded in the user resource. These objects are available for expansion by adding `owner_id` to the `expansions` query parameter. Use this expansion with the `list.fields` field parameter when requesting additional fields to complete the primary List object and `user.fields` to complete the expansion object. | Field Value | Type | Description | How it can be used | | :-------------- | :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------- | | id (default) | string | The unique identifier of this List.
`"id": "2244994945"` | Use this to programmatically retrieve information about a specific List. | | name (default) | string | The name of the List, as defined when creating the List.
`"name": "Twitter Lists"` | | | created\_at | date (ISO 8601) | The UTC datetime when the List was created.
`"created_at": "2013-12-14T04:35:55.000Z"` | Determine how long a List has been on Twitter. | | description | string | A brief description to inform users about the List.
`"description": "People that are active members of the Bay area cycling community on Twitter."` | | | follower\_count | integer | Shows how many users follow this List.
`"follower_count": 198` | | | member\_count | integer | Shows how many members are part of this List.
`"member_count": 60` | | | private | boolean | Indicates if the List is private.
`"private": false` | | | owner\_id | string | Unique identifier of this List's owner.
`"owner_id": "1255542774432063488"` | Can be used to find out if this user owns other Lists and expand User objects. | **Retrieving a User Object** **Sample Request** In the following request, we are requesting fields for the user on the [List lookup by ID](/x-api/lists/list-lookup/introduction) endpoint. Replace `$BEARER_TOKEN` with your generated [Bearer Token](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only). ```bash theme={null} curl --request GET 'https://api.x.com/2/lists/1355797419175383040?list.fields=created_at,description,private,follower_count,member_count,owner_id&expansions=owner_id' --header 'Authorization: Bearer $BEARER_TOKEN' ``` \*\* Sample Response\*\* ``` { "data": { "name": "Twitter Comms", "member_count": 60, "id": "1355797419175383040", "private": false, "description": "", "follower_count": 198, "owner_id": "257366942", "created_at": "2021-01-31T08:37:48.000Z" }, "includes": { "users": [ { "created_at": "2011-02-25T07:51:26.000Z", "name": "Ashleigh Hay 🤸🏼♀️", "id": "257366942", "username": "shleighhay", "verified": false } ] } } ``` ### Media Media refers to any image, GIF, or video attached to a Tweet. The media object is not a primary object on any endpoint, but can be found and expanded in the Tweet object. The object is available for expansion with `?expansions=attachments.media_keys` to get the condensed object with only default fields. Use the expansion with the field parameter: `media.fields` when requesting additional fields to complete the object. | Field value | Type | Description | How it can be used | | :------------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------- | | media\_key (default) | string | Unique identifier of the expanded media content.
` "media_key": "13_1263145212760805376"` | Can be used to programmatically retrieve media | | type (default) | string | Type of content (animated\_gif, photo, video).
` "type": "video"` | Classify the media as a photo, GIF, or video | | url | string | A direct URL to the media file on Twitter. | Returns a Media object with a URL field for photos | | duration\_ms | integer | Available when type is video. Duration in milliseconds of the video.
` "duration_ms": 46947` | | | height | integer | Height of this content in pixels.
` "height": 1080` | | | non\_public\_metrics | object | Non-public engagement metrics for the media content at the time of the request. Requires user context authentication.
` "non_public_metrics": { "playback_0_count": 1561, "playback_100_count": 116, "playback_25_count": 559, "playback_50_count": 305, "playback_75_count": 183,}` | Determine video engagement: how many users played through to each quarter of the video. | | organic\_metrics | object | Engagement metrics for the media content, tracked in an organic context, at the time of the request. Requires user context authentication.
` "organic_metrics": { "playback_0_count": 1561, "playback_100_count": 116, "playback_25_count": 559, "playback_50_count": 305, "playback_75_count": 183, "view_count": 629}` | Determine organic media engagement. | | preview\_image\_url | string | URL to the static placeholder preview of this content.
` "preview_image_url": "https://pbs.twimg.com/media/EYeX7akWsAIP1_1.jpg"` | | | promoted\_metrics | object | Engagement metrics for the media content, tracked in a promoted context, at the time of the request. Requires user context authentication.
` "promoted_metrics": { "playback_0_count": 259, "playback_100_count": 15, "playback_25_count": 113, "playback_50_count": 57, "playback_75_count": 25, "view_count": 124}` | Determine media engagement when the Tweet was promoted. | | public\_metrics | object | Public engagement metrics for the media content at the time of the request.
` "public_metrics": { "view_count": 6865141}` | Determine total number of views for the video attached to the Tweet. | | width | integer | Width of this content in pixels.
` "width": 1920` | | | alt\_text | string | A description of an image to enable and support accessibility. Can be up to 1000 characters long. Alt text can only be added to images at the moment.
` "alt_text": "Rugged hills along the Na Pali coast on the island of Kauai"` | Can be used to provide a written description of an image in case a user is visually impaired. | | variants | array | Each media object may have multiple display or playback variants, with different resolutions or formats.
` "variants": [{ "bit_rate": 632000, "content_type": "video/mp4", "url": "https://video.twimg.com/ext_tw_video/1527322141724532740/pu/vid/320x568/lnBaR2hCqE-R_90a.mp4?tag=12"}]` | | **Retrieving a media object** **Sample Request** In the following request, we are requesting fields for the media object attached to the Tweet on the [Tweet lookup](/x-api/posts/lookup/introduction) endpoint. Since media is a child object of a Tweet, the `attachment.media_keys` expansion is required. Be sure to replace `$BEARER_TOKEN` with your own generated [Bearer Token](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only). ```bash theme={null} curl --request GET 'https://api.x.com/2/tweets?ids=1263145271946551300&expansions=attachments.media_keys&media.fields=duration_ms,height,media_key,preview_image_url,public_metrics,type,url,width,alt_text' --header 'Authorization: Bearer $BEARER_TOKEN' ``` ``` { "data": [ { "text": "Testing, testing...\n\nA new way to have a convo with exactly who you want. We’re starting with a small % globally, so keep your 👀 out to see it in action. https://t.co/pV53mvjAVT", "id": "1263145271946551300", "attachments": { "media_keys": [ "13_1263145212760805376" ] } } ], "includes": { "media": [ { "duration_ms": 46947, "type": "video", "height": 1080, "media_key": "13_1263145212760805376", "public_metrics": { "view_count": 6909260 }, "preview_image_url": "https://pbs.twimg.com/media/EYeX7akWsAIP1_1.jpg", "width": 1920 } ] } } ``` ### Poll A poll included in a Tweet is not a primary object on any endpoint, but can be found and expanded in the Tweet object. The object is available for expansion with `?expansions=attachments.poll_ids` to get the condensed object with only default fields. Use the expansion with the field parameter: `poll.fields` when requesting additional fields to complete the object. | Field value | Type | Description | | :---------------- | :-------------- | :-------------------------------------------------------------------------------------------------------------------------------- | | id (default) | string | Unique identifier of the expanded poll. | | | | `{"id": "1199786642791452673"}` | | options (default) | array | Contains objects describing each choice in the referenced poll. | | | | `{"options": [ { "position": 1, "label": "“C Sharp”", "votes": 795 }, { "position": 2, "label": "“C Hashtag”", "votes": 156 } ]}` | | duration\_minutes | integer | Specifies the total duration of this poll. | | | | `{"duration_minutes": 1440}` | | end\_datetime | date (ISO 8601) | Specifies the end date and time for this poll. | | | | `{"end_datetime": "2019-11-28T20:26:41.000Z"}` | | voting\_status | string | Indicates if this poll is still active and can receive votes, or if the voting is now closed. | | | | `{"voting_status": "closed"}` | **Retrieving a poll object** **Sample Request** In the following request, we are requesting fields for the poll object attached to the Tweet on the [Tweets lookup](/x-api/posts/lookup/introduction) endpoint. Since poll is a child object of a Tweet, the `attachments.poll_id` expansion is required. Be sure to replace `$BEARER_TOKEN` with your own generated [Bearer Token](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only). ```bash theme={null} curl --request GET 'https://api.x.com/2/tweets?ids=1199786642791452673&expansions=attachments.poll_ids&poll.fields=duration_minutes,end_datetime,id,options,voting_status' --header 'Authorization: Bearer $BEARER_TOKEN' ``` **Sample Response** ``` { "data": [ { "text": "C#", "id": "1199786642791452673", "attachments": { "poll_ids": [ "1199786642468413448" ] } } ], "includes": { "polls": [ { "id": "1199786642468413448", "voting_status": "closed", "duration_minutes": 1440, "options": [ { "position": 1, "label": "“C Sharp”", "votes": 795 }, { "position": 2, "label": "“C Hashtag”", "votes": 156 } ], "end_datetime": "2019-11-28T20:26:41.000Z" } ] } } ``` ### Place The place tagged in a Tweet is not a primary object on any endpoint, but can be found and expanded in the Tweet resource. The object is available for expansion with `?expansions=geo.place_id` to get the condensed object with only default fields. Use the expansion with the field parameter: `place.fields` when requesting additional fields to complete the object. | Field value | Type | Description | How it can be used | | :------------------- | :----- | :------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------- | | full\_name (default) | string | A longer-form detailed place name. | Classify a Tweet by a specific place name | | | | `"full_name": "Manhattan, NY"` | | | id (default) | string | The unique identifier of the expanded place, if this is a point of interest tagged in the Tweet. | Use this to programmatically retrieve a place | | | | `"id": "01a9a39529b27f36"` | | | contained\_within | array | Returns the identifiers of known places that contain the referenced place. | | | country | string | The full-length name of the country this place belongs to. | Classify a Tweet by country name | | | | `"country": "United States"` | | | country\_code | string | The ISO Alpha-2 country code this place belongs to. | Classify a Tweet by country code | | | | `"country_code": "US"` | | | geo | object | Contains place details in GeoJSON format. | | | | | \`\`\`json | | | | | "geo": | | | | | "type": "Feature", | | | | | "bbox": \[ | | | | | -74.026675, | | | | | 40.683935, | | | | | -73.910408, | | | | | 40.877483 | | | | | ], | | | | | "properties": | | | | | } | | | | | \`\`\` | | | name | string | The short name of this place. | Classify a Tweet by a specific place name | | | | `"name": "Manhattan"` | | | place\_type | string | Specified the particular type of information represented by this place information, such as a city name, or a point of interest. | Classify a Tweet by a specific type of place | | | | `"place_type": "city"` | | **Retrieving a place object** **Sample Request** In the following request, we are requesting fields for the place object attached to the Tweet on the [Tweets lookup](/x-api/posts/lookup/introduction) endpoint. Since place is a child object of a Tweet, the `geo.place_id` expansion is required. Be sure to replace `$BEARER_TOKEN` with your own generated [Bearer Token](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only). ```bash theme={null} curl --request GET 'https://api.x.com/2/tweets?ids=1136048014974423040&expansions=geo.place_id&place.fields=contained_within,country,country_code,full_name,geo,id,name,place_type' --header 'Authorization: Bearer $BEARER_TOKEN' ``` **Sample Response** ``` { "data": [ { "text": "We’re sharing a live demo of the new Twitter Developer Labs program, led by a member of our DevRel team, @jessicagarson #TapIntoTwitter https://t.co/ghv7f4dW5M", "id": "1136048014974423040", "geo": { "place_id": "01a9a39529b27f36" } } ], "includes": { "places": [ { "geo": { "type": "Feature", "bbox": [ -74.026675, 40.683935, -73.910408, 40.877483 ], "properties": {} }, "country_code": "US", "name": "Manhattan", "id": "01a9a39529b27f36", "place_type": "city", "country": "United States", "full_name": "Manhattan, NY" } ] } } ``` ### Direct Message events Direct Message (DM) conversations are made up of events. The X API v2 currently supports three event types: MessageCreate, ParticipantsJoin, and ParticipantsLeave. DM event objects are returned by the [Direct Message lookup](/x-api/direct-messages/lookup/introduction) endpoints, and a MessageCreate event is created when Direct Messages are successfully created with the [Manage Direct Messages](/x-api/direct-messages/lookup/introduction) endpoints. When requesting DM events, there are three default event object attributes, or fields, included: id, event\_type, and text. To receive additional event fields, use the [fields](/x-api/fundamentals/fields) parameter dm\_event.fields to select others. Other available event fields include the following: dm\_conversation\_id, created\_at, sender\_id, attachments, participant\_ids, and referenced\_tweets. Several of these fields provide the IDs of other X objects related to the Direct Message event: * sender\_id - The ID of the account that sent the message, or who invited a participant to a group conversation * partricipants\_ids - An array of account IDs. For ParticipantsJoin and ParticipantsLeave events this array will contain a single ID of the account that created the event * attachments - Provides media IDs for content that has been uploaded to Twitter by the sender * referenced\_tweets - If a Tweet URL is found in the text field, the ID of that Tweet is included in the response The sender\_id, participant\_ids, referenced\_tweets.id, and attachments.media\_keys [expansions](/x-api/fundamentals/expansions) are available to expand on these Twitter object IDs. | | | | | | :-------------------- | :----------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Field value** | **Type** | **Description** | **How it can be used** | | id (default) | string | The unique identifier of the event.
"id": "1050118621198921728" | Use this to programmatically retrieve a specific conversation event (available with v1.1 endpoints). | | event\_type (default) | string | Describes the type of event. Three types are currently supported:
\* MessageCreate
\* ParticipantsJoin
\* ParticipantsLeave
"event\_type": "MessageCreate" | When retrieving a conversation's history, understanding when messages were created, and for group conversations, understanding when participants joined and left. All GET methods support filtering on specific event types with the event\_type= query parameter. . | | text (default) | string | The actual UTF-8 text of the Direct Message.
"text": "Hello, just you!" | With chatbots, this can be used to analyze message contents and determining automated responses. Could be used to build conversation search features. | | entities | object | Entities that have been parsed out of the text of the DM. | Provides additional information about hashtags, URLs, mentions, etc. | | sender\_id | string | ID of the User creating the event. To expand this object in the response, include sender\_id as an expansion and use the user.fields query parameter to specify User object attributes of interest.
"sender\_id": "906948460078698496" | Retrieve the User object of who created the MessageCreate or ParticipantsJoin event. | | participant\_ids | array (of strings) | IDs of the participants joining and leaving a group conversation. Also used when creating new group conversations. To expand this object in the response, include participant\_ids as an expansion and use the user.fields query parameter to specify User object attributes of interest.
"participant\_ids": \[
"906948460078698496"
] | Used to retrieve User objects for participants joining and leaving group conversations. | | dm\_conversation\_id | string | The unique identifier of the conversation the event is apart of.
"dm\_conversation\_id": "1584988213961031680" | Use this to programmatically retrieve events from a conversation, and add Direct Messages to it. | | created\_at | date (ISO 8601) | Creation time (UTC) of the Tweet.
"created\_at": "2019-06-04T23:12:08.000Z" | This field can be used to understand when a Direct Message was created or when conversation participants joined or left. | | referenced\_tweets | array | ID for any Tweet mentioned in the Direct Message text. To expand this object in the response, include referenced\_tweets.id as an expansion and use the tweet.fields query parameter to specify Tweet object attributes of interest.
"referenced\_tweets": \[
"id": "1578868150510456833"
] | When Direct Messages reference a Tweet, these IDs can be used to lookup the Tweet's details. | | attachments | object | For Direct Messages with attached Media, provides the media key of the uploaded content (photo, video, or GIF). To expand this object in the response, include attachments.media\_keys as an expansion and use the media.fields query parameter to specify media object attributes of interest. Currently, one attachment is supported.
"attachments":
"media\_keys": \[
"3\_1136048009270239232"
]
| Understanding the media objects attached to Direct Messages. | **Retrieving a Direct Message event object** **Sample Request** For this example, we will build a request that retrieves events associated with a one-to-one conversation. This request will return fundamental Direct Message event fields, along with additional fields for referenced Tweets and their authors. Let's build a query that asks for: * Fundamental event attributes such as when it was created and what conversation it is part of (dm\_conversation). * The account ID and description of who sent the Direct Message. * The text of any referenced Tweet, and when it was posted. * The account ID and description of any referenced Tweet author. To return those attributes, your request query would include the following: `?dm_event.fields=id,sender_id,text,created_at,dm_conversation_id&expansions=sender_id,referenced_tweets.id&tweet.fields=created_at,text,author_id&user.fields=description` ```bash theme={null} curl --request GET 'https://api.x.com/2/dm_conversations/with/:participant_id/dm_events?tweet.fields=created_at,text,author_id&user.fields=description&expansions=sender_id,participant_ids,referenced_tweets.id&dm_event.fields=id,sender_id,text,participant_ids,created_at,' --header 'Authorization: Bearer $BEARER_TOKEN' ``` Be sure to replace \$BEARER\_TOKEN with your own generated [Bearer Token](/resources/fundamentals/authentication#using-and-generating-an-app-only-bearer-token). **Sample Response** ``` { "data": [{ "id": "1585047616894574596", "sender_id": "944480690", "text": "Hello, just you!", "created_at": "2022-10-25T23:16:15.000Z", "event_type": "MessageCreate", "dm_conversation_id": "944480690-906948460078698496" }, { "id": "1581048670673260549", "sender_id": "944480690", "text": "Simple Tweet link: https://t.co/IYFbRIdXHg", "referenced_tweets": [{ "id": "1578900353814519810" }], "created_at": "2022-10-14T22:25:52.000Z", "event_type": "MessageCreate", "dm_conversation_id": "944480690-906948460078698496" }, { "id": "1580705121553420292", "sender_id": "944480690", "text": "Adding a new 1-to-1 Direct Message.", "created_at": "2022-10-13T23:40:43.000Z", "event_type": "MessageCreate", "dm_conversation_id": "944480690-906948460078698496" } ], "includes": { "users": [{ "name": "API Demos", "description": "Hosting TwitterDev integrations... @TwitterDev #DevRel", "id": "944480690", "username": "FloodSocial" }, { "name": "the SnowBot", "description": "Home of the @TwitterDev SnowBot... Serving snow reports, snow photos, and snow research links... Chatbot is currently being remodeled for Twitter APIv2.", "id": "906948460078698496", "username": "SnowBotDev" } ], "tweets": [{ "text": "Feeling kind of bad that I didn’t wish everybody a happy new Colorado Water Year…\n\nHappy Water Year to all my Colorado friends and colleagues, new and old… \n\nMay this be a generous water year, although not too generous…", "id": "1578900353814519810", "created_at": "2022-10-09T00:09:13.000Z", "author_id": "944480690", "edit_history_tweet_ids": [ "1578900353814519810" ] } ] }, "meta": { "result_count": 3, "next_token": "18LAA581J5II7LA00C00ZZZZ", "previous_token": "1BLC45G1H8CAL5DG0G00ZZZZ" } } ``` ### Community Communities are dedicated places for X users to connect, share, and get closer to the discussions they care about most. Posts in Communities can be seen by anyone on X, but only others within the Community itself can engage and participate in the discussion. The Community object contains relevant metadata about a Community. | Field value | Type | Description | | | :------------ | :-------------- | :------------------------------------------------------------- | :- | | created\_at | date (ISO 8601) | Creation time of the Community. | | | id | string | The unique identifier of the Community. | | | name | string | The name of the Community. | | | description | string | The text of the Community’s description, if provided. | | | access | string | The access level of the Community.
Can be one of: | | | | | - `Public` | | | | | - `Closed` | | | join\_policy | string | The join policy for the Community.
Can be one of: | | | | | - `Open` | | | | | - `RestrictedJoinRequestsDisabled` | | | | | - `RestrictedJoinRequestsRequireAdminApproval` | | | | | - `RestrictedJoinRequestsRequireModeratorApproval` | | | | | - `SuperFollowRequired` | | | member\_count | integer | The number of members that have joined the Community. | | **Retrieving Community objects** **Sample Request** In the following request, we are requesting specific fields while searching for a list of Communities based on a provided keyword. Be sure to replace `$BEARER_TOKEN` with your own generated [Bearer Token](/resources/fundamentals/authentication#bearer-token-also-known-as-app-only). ```bash theme={null} curl --location 'https://api.x.com/2/communities/search?query=anime&community.fields=access,created_at,description,id,join_policy,member_count,name' --header 'Authorization: $BEARER_TOKEN' ``` **Sample Response** ``` { "data": [ { "id": "Q29tbXVuaXR5OjE3NTg3NDc4MTc2NDI3MDA5MjI=", "description": "Welcome to the Anime Community! Where anime fans gather to share their favorite shows and discuss everything anime-related.", "join_policy": "Open", "access": "Public", "member_count": 39915, "name": "Anime Community", "created_at": "2024-02-17T06:58:50.000Z" }, { "id": "Q29tbXVuaXR5OjE1MDY3OTM5NTMxMDYwNDI4OTE=", "description": "Join and text about anime 🥰", "join_policy": "Open", "access": "Public", "member_count": 26019, "name": "Anime World 🌸", "created_at": "2022-03-24T00:44:07.000Z" }, { "id": "Q29tbXVuaXR5OjE0OTY3NzYyMTU5Mzk1MzQ4NDk=", "description": "For all anime lovers and creators!", "join_policy": "Open", "access": "Public", "member_count": 5612, "name": "Anime", "created_at": "2022-02-24T09:17:13.000Z" } ], "meta": { "next_token": "7140dibdnow9c7btw481s8m561gat797rboud5r80xvzm" } } ``` ## How to use fields and expansions By default, the X API v2 data objects include a small number of default fields when making a request without the use of the [fields](/x-api/fundamentals/fields) or [expansions](/x-api/fundamentals/expansions) parameters. This guide will show you how to use the `fields` and `expansions` query parameters in your request to receive additional objects and fields in your response. In this guide, we will be requesting several fields in the following Tweet screenshot.  As you can see in the screenshot, there are several visible pieces of information related to the Tweet, including the Tweet author, Tweet metrics, created timestamp, video, and video view count. There are also several pieces of data that are not visible within the screenshot, but are still available to request. When making a request to the API, the default response is simple, containing only the default Tweet fields (id and text). You will also only receive the primary object that returns with the given endpoint that you are using, and not any of the associated data objects that might relate to the primary object. This simplicity, along with the fields and expansions parameters, enable you to request only those fields you require, depending on your use case. #### Requesting additional fields and objects. First off, we will be requesting a [Tweet object](/x-api/fundamentals/data-dictionary#tweet) using a Tweet ID and the [GET /tweets endpoint](/x-api/posts/lookup/introduction). Request: ```bash theme={null} curl --request GET --url 'https://api.x.com/2/tweets?ids=1260294888811347969' \ --header 'Authorization: Bearer $BEARER_TOKEN' ``` Response: ``` { "data": [ { "id": "1260294888811347969", "text": "Don’t miss the Tweets about your Tweet. \n\nNow on iOS, you can see Retweets with comments all in one place. https://t.co/oanjZfzC6y" } ] } ``` The following step-by-step guide will show you how to retrieve the additional data we can see in the screenshot. 1. Identify the additional fields that you would like to request by using our [object model](/x-api/fundamentals/data-dictionary#tweet), or by reviewing the list of fields in the endpoints’ API reference pages. In this case, we will be requesting the following additional fields: attachments, author\_id, created\_at, public\_metrics. 2. Build the `tweet.fields` query parameter with the above fields as its value using a comma-separated list: `?tweet.fields=attachments,author_id,created_at,public_metrics` 3. Add the query parameter to the GET /tweets request that you made earlier. Request: `curl --request GET --url 'https://api.x.com/2/tweets?ids=1260294888811347969&tweet.fields=attachments,author_id,created_at,public_metrics' \ --header 'Authorization: Bearer $BEARER_TOKEN'` Response: ``` { "data": [ { "id": "1260294888811347969", "text": "Don’t miss the Tweets about your Tweet. \n\nNow on iOS, you can see Retweets with comments all in one place. https://t.co/oanjZfzC6y", "author_id": "783214", "public_metrics": { "retweet_count": 5219, "reply_count": 1828, "like_count": 17141, "quote_count": 3255 }, "attachments": { "media_keys": [ "13_1260294804770041858" ] }, "created_at": "2020-05-12T19:44:51.000Z" } ] } ``` 4. Next, we are going to request fields related to the video that was included in the Tweet. To do so, we will use the `expansions` parameter with `attachments.media_keys` as the value, and add this to the request. ?expansions=attachments.media\_keys Request: ```bash theme={null} curl --request GET --url 'https://api.x.com/2/tweets?ids=1260294888811347969&tweet.fields=attachments,author_id,created_at,public_metrics&expansions=attachments.media_keys' \ --header 'Authorization: Bearer $BEARER_TOKEN' ``` Response, with the media object represented in the includes object: ``` { "data": [ { "id": "1260294888811347969", "text": "Don’t miss the Tweets about your Tweet. \n\nNow on iOS, you can see Retweets with comments all in one place. https://t.co/oanjZfzC6y", "public_metrics": { "retweet_count": 5219, "reply_count": 1828, "like_count": 17141, "quote_count": 3255 }, "created_at": "2020-05-12T19:44:51.000Z", "attachments": { "media_keys": [ "13_1260294804770041858" ] }, "author_id": "783214" } ], "includes": { "media": [ { "media_key": "13_1260294804770041858", "type": "video" } ] } } ``` 5. And finally, we are going to request the view count and duration of the video. These aren’t default fields so we have to specifically request them. Use the `media.fields` parameter with the comma-separated values, `public_metrics` and `duration_ms` in your request. ?media.fields=public\_metrics,duration\_ms Request: `curl --request GET --url 'https://api.x.com/2/tweets?ids=1260294888811347969&tweet.fields=attachments,author_id,created_at,public_metrics&expansions=attachments.media_keys&media.fields=duration_ms,public_metrics' --header 'Authorization: Bearer $BEARER_TOKEN'` Response, which now includes all the data that can be seen in the Tweet screenshot: ``` { "data": [ { "id": "1260294888811347969", "text": "Don’t miss the Tweets about your Tweet. \n\nNow on iOS, you can see Retweets with comments all in one place. https://t.co/oanjZfzC6y", "author_id": "783214", "public_metrics": { "retweet_count": 5219, "reply_count": 1828, "like_count": 17141, "quote_count": 3255 }, "created_at": "2020-05-12T19:44:51.000Z", "attachments": { "media_keys": [ "13_1260294804770041858" ] } } ], "includes": { "media": [ { "duration_ms": 36503, "media_key": "13_1260294804770041858", "public_metrics": { "view_count": 1534703 }, "type": "video" } ] } } ``` In total, we included the following parameters in this example: * ids=1260294888811347969 * tweet.fields=attachments,author\_id,created\_at,public\_metrics * expansions=attachments.media\_keys * media.fields=public\_metrics,duration\_ms When tied together, here is what the full query string looks like: ``` ?ids=1260294888811347969&tweet.fields=attachments,author\_id,created\_at,public\_metrics&expansions=attachments.media\_keys&media.fields=public\_metrics,duration\_ms ``` ## X API v2 Example payloads ### Tweet ```json theme={null} { "data": [ { "conversation_id": "1304102743196356610", "id": "1307025659294674945", "possibly_sensitive": false, "public_metrics": { "retweet_count": 11, "reply_count": 2, "like_count": 70, "quote_count": 1 }, "entities": { "urls": [ { "start": 74, "end": 97, "url": "https://t.co/oeF3ZHeKQQ", "expanded_url": "https://dev.to/twitterdev/understanding-the-new-tweet-payload-in-the-twitter-api-v2-1fg5", "display_url": "dev.to/twitterdev/und…", "images": [ { "url": "https://pbs.twimg.com/news_img/1317156296982867969/2uLfv-Bh?format=jpg&name=orig", "width": 1128, "height": 600 }, { "url": "https://pbs.twimg.com/news_img/1317156296982867969/2uLfv-Bh?format=jpg&name=150x150", "width": 150, "height": 150 } ], "status": 200, "title": "Understanding the new Tweet payload in the X API v2", "description": "X recently announced the new X API v2, rebuilt from the ground up to deliver new features...", "unwound_url": "https://dev.to/twitterdev/understanding-the-new-tweet-payload-in-the-twitter-api-v2-1fg5" } ] }, "text": "Here’s an article that highlights the updates in the new Tweet payload v2 https://t.co/oeF3ZHeKQQ", "in_reply_to_user_id": "2244994945", "created_at": "2020-09-18T18:36:15.000Z", "author_id": "2244994945", "referenced_tweets": [ { "type": "replied_to", "id": "1304102743196356610" } ], "lang": "en", "source": "Twitter Web App" } ], "includes": { "users": [ { "created_at": "2013-12-14T04:35:55.000Z", "profile_image_url": "https://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", "entities": { "url": { "urls": [ { "start": 0, "end": 23, "url": "https://t.co/3ZX3TNiZCY", "expanded_url": "https://developer.x.com/en/community", "display_url": "developer.x.com/en/community" } ] }, "description": { "hashtags": [ { "start": 17, "end": 28, "tag": "TwitterDev" }, { "start": 105, "end": 116, "tag": "TwitterAPI" } ] } }, "id": "2244994945", "verified": true, "location": "127.0.0.1", "description": "The voice of the #TwitterDev team and your official source for updates, news, and events, related to the #TwitterAPI.", "pinned_tweet_id": "1293593516040269825", "username": "TwitterDev", "public_metrics": { "followers_count": 513961, "following_count": 2039, "tweet_count": 3635, "listed_count": 1672 }, "name": "Twitter Dev", "url": "https://t.co/3ZX3TNiZCY", "protected": false } ], "tweets": [ { "conversation_id": "1304102743196356610", "id": "1304102743196356610", "possibly_sensitive": false, "public_metrics": { "retweet_count": 31, "reply_count": 12, "like_count": 104, "quote_count": 4 }, "entities": { "mentions": [ { "start": 146, "end": 158, "username": "suhemparack" } ], "urls": [ { "start": 237, "end": 260, "url": "https://t.co/CjneyMpgCq", "expanded_url": "https://x.com/TwitterDev/status/1304102743196356610/video/1", "display_url": "pic.x.com/CjneyMpgCq" } ], "hashtags": [ { "start": 8, "end": 19, "tag": "TwitterAPI" } ] }, "attachments": { "media_keys": [ "13_1303848070984024065" ] }, "text": "The new #TwitterAPI includes some improvements to the Tweet payload. You’re probably wondering — what are the main differences? 🧐\n\nIn this video, @SuhemParack compares the v1.1 Tweet payload with what you’ll find using our v2 endpoints. https://t.co/CjneyMpgCq", "created_at": "2020-09-10T17:01:37.000Z", "author_id": "2244994945", "lang": "en", "source": "Twitter Media Studio" } ] } } ``` ### Tweet reply ```json theme={null} { "data": [ { "lang": "en", "conversation_id": "1296887091901718529", "text": "See how @PennMedCDH are using Twitter data to understand the COVID-19 health crisis 📊\n\nhttps://t.co/1tdA8uDWes", "referenced_tweets": [ { "type": "replied_to", "id": "1296887091901718529" } ], "possibly_sensitive": false, "entities": { "annotations": [ { "start": 30, "end": 36, "probability": 0.6318, "type": "Product", "normalized_text": "Twitter" } ], "mentions": [ { "start": 8, "end": 19, "username": "PennMedCDH" } ], "urls": [ { "start": 87, "end": 110, "url": "https://t.co/1tdA8uDWes", "expanded_url": "https://developer.x.com/en/use-cases/success-stories/penn", "display_url": "developer.x.com/en/use-cases/s…", "status": 200, "title": "Penn Medicine Center for Digital Health", "description": "Penn Med Center for Digital Health has created a COVID-19 Twitter map that includes charts detailing sentiment, symptoms reported, state-by-state data cuts, and border data on the COVID-19 outbreak. In addition, their Penn Med With You initiative uses aggregate regional information from Twitter to inform their website and text-messaging service. The service uses this information to disseminate relevant and timely resources.", "unwound_url": "https://developer.x.com/en/use-cases/success-stories/penn" } ] }, "id": "1296887316556980230", "public_metrics": { "retweet_count": 9, "reply_count": 3, "like_count": 26, "quote_count": 2 }, "author_id": "2244994945", "in_reply_to_user_id": "2244994945", "context_annotations": [ { "domain": { "id": "46", "name": "Brand Category", "description": "Categories within Brand Verticals that narrow down the scope of Brands" }, "entity": { "id": "781974596752842752", "name": "Services" } }, { "domain": { "id": "47", "name": "Brand", "description": "Brands and Companies" }, "entity": { "id": "10045225402", "name": "Twitter" } }, { "domain": { "id": "123", "name": "Ongoing News Story", "description": "Ongoing News Stories like 'Brexit'" }, "entity": { "id": "1220701888179359745", "name": "COVID-19" } } ], "source": "Twitter Web App", "created_at": "2020-08-21T19:10:05.000Z" } ], "includes": { "users": [ { "created_at": "2013-12-14T04:35:55.000Z", "id": "2244994945", "protected": false, "username": "TwitterDev", "verified": true, "entities": { "url": { "urls": [ { "start": 0, "end": 23, "url": "https://t.co/3ZX3TNiZCY", "expanded_url": "https://developer.x.com/en/community", "display_url": "developer.x.com/en/community" } ] }, "description": { "hashtags": [ { "start": 17, "end": 28, "tag": "TwitterDev" }, { "start": 105, "end": 116, "tag": "TwitterAPI" } ] } }, "description": "The voice of the #TwitterDev team and your official source for updates, news, and events, related to the #TwitterAPI.", "pinned_tweet_id": "1293593516040269825", "public_metrics": { "followers_count": 513962, "following_count": 2039, "tweet_count": 3635, "listed_count": 1672 }, "location": "127.0.0.1", "name": "Twitter Dev", "profile_image_url": "https://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", "url": "https://t.co/3ZX3TNiZCY" }, { "created_at": "2013-07-23T16:58:03.000Z", "id": "1615654896", "protected": false, "username": "PennMedCDH", "verified": false, "entities": { "url": { "urls": [ { "start": 0, "end": 23, "url": "https://t.co/7eS9RuwIb9", "expanded_url": "http://centerfordigitalhealth.upenn.edu/", "display_url": "centerfordigitalhealth.upenn.edu" } ] }, "description": { "mentions": [ { "start": 0, "end": 13, "username": "PennMedicine" } ] } }, "description": "@PennMedicine's Center for Digital Health advances science by researching the implications of the advancement of digital health technology in health care.", "public_metrics": { "followers_count": 1348, "following_count": 455, "tweet_count": 1288, "listed_count": 92 }, "location": "Philadelphia, PA", "name": "Penn Med CDH", "profile_image_url": "https://pbs.twimg.com/profile_images/1067488849725726723/MoO3FQ44_normal.jpg", "url": "https://t.co/7eS9RuwIb9" } ], "tweets": [ { "lang": "en", "conversation_id": "1296887091901718529", "text": "Dr. @RainaMerchant and her team at the Penn Medicine CDH are helping build the future of health care.\n\nThe team is using insights from social data in many different ways — ranging from uncovering risk factors to shedding light on public sentiment. 🔎", "possibly_sensitive": false, "entities": { "annotations": [ { "start": 39, "end": 55, "probability": 0.8274, "type": "Organization", "normalized_text": "Penn Medicine CDH" } ], "mentions": [ { "start": 4, "end": 18, "username": "RainaMerchant" } ] }, "id": "1296887091901718529", "public_metrics": { "retweet_count": 9, "reply_count": 7, "like_count": 32, "quote_count": 0 }, "author_id": "2244994945", "source": "Twitter Web App", "created_at": "2020-08-21T19:09:12.000Z" } ] } } ``` ### Extended Tweet ```json theme={null} { "data": [ { "conversation_id": "1296121314218897408", "id": "1296121314218897408", "possibly_sensitive": false, "public_metrics": { "retweet_count": 54, "reply_count": 9, "like_count": 172, "quote_count": 23 }, "entities": { "urls": [ { "start": 192, "end": 215, "url": "https://t.co/khXhTurm9x", "expanded_url": "https://devcommunity.x.com/t/hide-replies-now-available-in-the-new-twitter-api/140996", "display_url": "devcommunity.com/t/hide-replies…", "images": [ { "url": "https://pbs.twimg.com/news_img/1296121315514957825/3CI24hSI?format=png&name=orig", "width": 400, "height": 400 }, { "url": "https://pbs.twimg.com/news_img/1296121315514957825/3CI24hSI?format=png&name=150x150", "width": 150, "height": 150 } ], "status": 200, "title": "Hide replies now available in the new Twitter API", "description": "Today, we’re happy to announce the general availability of the hide replies endpoint in the new Twitter API. The hide replies endpoint allows you to build tools that help people hide or unhide replies to their Tweets. People manage their replies for many reasons, including to give less attention to comments that are abusive, distracting, misleading, or to make conversations more engaging. Through this endpoint, you can build tools to help people on Twitter hide or unhide replies faster and more...", "unwound_url": "https://devcommunity.x.com/t/hide-replies-now-available-in-the-new-twitter-api/140996" } ], "hashtags": [ { "start": 178, "end": 189, "tag": "TwitterAPI" } ] }, "text": "The hide replies endpoint is launching today! \n\nDevelopers can hide replies to Tweets - a crucial way developers can help improve the health of the public conversation using the #TwitterAPI.\n\nhttps://t.co/khXhTurm9x", "created_at": "2020-08-19T16:26:16.000Z", "context_annotations": [ { "domain": { "id": "65", "name": "Interests and Hobbies Vertical", "description": "Top level interests and hobbies groupings, like Food or Travel" }, "entity": { "id": "848920371311001600", "name": "Technology", "description": "Technology and computing" } }, { "domain": { "id": "66", "name": "Interests and Hobbies Category", "description": "A grouping of interests and hobbies entities, like Novelty Food or Destinations" }, "entity": { "id": "848921413196984320", "name": "Computer programming", "description": "Computer programming" } } ], "author_id": "2244994945", "lang": "en", "source": "Twitter Web App" } ], "includes": { "users": [ { "created_at": "2013-12-14T04:35:55.000Z", "profile_image_url": "https://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", "entities": { "url": { "urls": [ { "start": 0, "end": 23, "url": "https://t.co/3ZX3TNiZCY", "expanded_url": "https://developer.x.com/en/community", "display_url": "developer.x.com/en/community" } ] }, "description": { "hashtags": [ { "start": 17, "end": 28, "tag": "TwitterDev" }, { "start": 105, "end": 116, "tag": "TwitterAPI" } ] } }, "id": "2244994945", "verified": true, "location": "127.0.0.1", "description": "The voice of the #TwitterDev team and your official source for updates, news, and events, related to the #TwitterAPI.", "pinned_tweet_id": "1293593516040269825", "username": "TwitterDev", "public_metrics": { "followers_count": 513962, "following_count": 2039, "tweet_count": 3635, "listed_count": 1672 }, "name": "Twitter Dev", "url": "https://t.co/3ZX3TNiZCY", "protected": false } ] } } ``` ### Tweet with media ```json theme={null} { "data": [ { "lang": "en", "conversation_id": "1293593516040269825", "text": "It’s finally here! 🥁 Say hello to the new #TwitterAPI.\n\nWe’re rebuilding the X API v2 from the ground up to better serve our developer community. And today’s launch is only the beginning.\n\nhttps://t.co/32VrwpGaJw https://t.co/KaFSbjWUA8", "attachments": { "media_keys": [ "7_1293565706408038401" ] }, "possibly_sensitive": false, "entities": { "annotations": [ { "start": 78, "end": 88, "probability": 0.4381, "type": "Product", "normalized_text": "Twitter API" } ], "hashtags": [ { "start": 42, "end": 53, "tag": "TwitterAPI" } ], "urls": [ { "start": 195, "end": 218, "url": "https://t.co/32VrwpGaJw", "expanded_url": "https://blog.x.com/developer/en_us/topics/tools/2020/introducing_new_twitter_api.html", "display_url": "blog.x.com/developer/en_u…", "images": [ { "url": "https://pbs.twimg.com/news_img/1336475659279818754/_cmRh7QE?format=jpg&name=orig", "width": 1200, "height": 627 }, { "url": "https://pbs.twimg.com/news_img/1336475659279818754/_cmRh7QE?format=jpg&name=150x150", "width": 150, "height": 150 } ], "status": 200, "title": "Introducing a new and improved X API", "description": "Introducing the new X API - rebuilt from the ground up to deliver new features faster so developers can help the world connect to the public conversation happening on Twitter.", "unwound_url": "https://blog.x.com/developer/en_us/topics/tools/2020/introducing_new_twitter_api.html" }, { "start": 219, "end": 242, "url": "https://t.co/KaFSbjWUA8", "expanded_url": "https://x.com/TwitterDev/status/1293593516040269825/video/1", "display_url": "pic.x.com/KaFSbjWUA8" } ] }, "id": "1293593516040269825", "public_metrics": { "retweet_count": 958, "reply_count": 171, "like_count": 2848, "quote_count": 333 }, "author_id": "2244994945", "context_annotations": [ { "domain": { "id": "46", "name": "Brand Category", "description": "Categories within Brand Verticals that narrow down the scope of Brands" }, "entity": { "id": "781974596752842752", "name": "Services" } }, { "domain": { "id": "47", "name": "Brand", "description": "Brands and Companies" }, "entity": { "id": "10045225402", "name": "Twitter" } }, { "domain": { "id": "65", "name": "Interests and Hobbies Vertical", "description": "Top level interests and hobbies groupings, like Food or Travel" }, "entity": { "id": "848920371311001600", "name": "Technology", "description": "Technology and computing" } }, { "domain": { "id": "66", "name": "Interests and Hobbies Category", "description": "A grouping of interests and hobbies entities, like Novelty Food or Destinations" }, "entity": { "id": "848921413196984320", "name": "Computer programming", "description": "Computer programming" } } ], "source": "Twitter Web App", "created_at": "2020-08-12T17:01:42.000Z" } ], "includes": { "media": [ { "height": 720, "duration_ms": 34875, "media_key": "7_1293565706408038401", "type": "video", "preview_image_url": "https://pbs.twimg.com/ext_tw_video_thumb/1293565706408038401/pu/img/66P2dvbU4a02jYbV.jpg", "public_metrics": { "view_count": 279438 }, "width": 1280 } ], "users": [ { "created_at": "2013-12-14T04:35:55.000Z", "id": "2244994945", "protected": false, "username": "TwitterDev", "verified": true, "entities": { "url": { "urls": [ { "start": 0, "end": 23, "url": "https://t.co/3ZX3TNiZCY", "expanded_url": "https://developer.x.com/en/community", "display_url": "developer.x.com/en/community" } ] }, "description": { "hashtags": [ { "start": 17, "end": 28, "tag": "TwitterDev" }, { "start": 105, "end": 116, "tag": "TwitterAPI" } ] } }, "description": "The voice of the #TwitterDev team and your official source for updates, news, and events, related to the #TwitterAPI.", "pinned_tweet_id": "1293593516040269825", "public_metrics": { "followers_count": 513962, "following_count": 2039, "tweet_count": 3635, "listed_count": 1672 }, "location": "127.0.0.1", "name": "Twitter Dev", "profile_image_url": "https://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", "url": "https://t.co/3ZX3TNiZCY" } ] } }` ### Retweet `{ "data": [ { "public_metrics": { "retweet_count": 19, "reply_count": 0, "like_count": 0, "quote_count": 0 }, "conversation_id": "1229851574555508737", "id": "1229851574555508737", "entities": { "annotations": [ { "start": 28, "end": 38, "probability": 0.261, "type": "Product", "normalized_text": "Alexa Skill" }, { "start": 44, "end": 50, "probability": 0.7332, "type": "Product", "normalized_text": "Twitter" } ], "mentions": [ { "start": 3, "end": 15, "username": "suhemparack" } ] }, "text": "RT @suhemparack: I built an Alexa Skill for Twitter using APL that allows you to view Tweets and Trends on the echo show!\n\nCheck it out her…", "created_at": "2020-02-18T19:33:59.000Z", "possibly_sensitive": false, "author_id": "2244994945", "referenced_tweets": [ { "type": "retweeted", "id": "1229843515603144704" } ], "context_annotations": [ { "domain": { "id": "47", "name": "Brand", "description": "Brands and Companies" }, "entity": { "id": "10026792024", "name": "Amazon" } }, { "domain": { "id": "48", "name": "Product", "description": "Products created by Brands. Examples: Ford Explorer, Apple iPhone." }, "entity": { "id": "968221983803494400", "name": "Amazon - Alexa", "description": "Alexa" } }, { "domain": { "id": "46", "name": "Brand Category", "description": "Categories within Brand Verticals that narrow down the scope of Brands" }, "entity": { "id": "781974596752842752", "name": "Services" } }, { "domain": { "id": "47", "name": "Brand", "description": "Brands and Companies" }, "entity": { "id": "10045225402", "name": "Twitter" } } ], "source": "Twitter Web App", "lang": "en" } ], "includes": { "users": [ { "profile_image_url": "https://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", "username": "TwitterDev", "name": "Twitter Dev", "location": "127.0.0.1", "url": "https://t.co/3ZX3TNiZCY", "entities": { "url": { "urls": [ { "start": 0, "end": 23, "url": "https://t.co/3ZX3TNiZCY", "expanded_url": "https://developer.x.com/en/community", "display_url": "developer.x.com/en/community" } ] }, "description": { "hashtags": [ { "start": 17, "end": 28, "tag": "TwitterDev" }, { "start": 105, "end": 116, "tag": "TwitterAPI" } ] } }, "id": "2244994945", "description": "The voice of the #TwitterDev team and your official source for updates, news, and events, related to the #TwitterAPI.", "verified": true, "public_metrics": { "followers_count": 513962, "following_count": 2039, "tweet_count": 3635, "listed_count": 1672 }, "pinned_tweet_id": "1293593516040269825", "created_at": "2013-12-14T04:35:55.000Z", "protected": false }, { "profile_image_url": "https://pbs.twimg.com/profile_images/1230703695051935747/TbQKe91L_normal.jpg", "username": "suhemparack", "name": "Suhem Parack", "location": "Seattle, WA", "url": "https://t.co/8IkCzClPCz", "entities": { "url": { "urls": [ { "start": 0, "end": 23, "url": "https://t.co/8IkCzClPCz", "expanded_url": "https://developer.x.com", "display_url": "developer.x.com" } ] }, "description": { "mentions": [ { "start": 42, "end": 50, "username": "Twitter" } ] } }, "id": "857699969263964161", "description": "Developer Relations for Academic Research @Twitter. Talk to me about research with Twitter data. Previously: Amazon Alexa. Views are my own", "verified": false, "public_metrics": { "followers_count": 738, "following_count": 512, "tweet_count": 460, "listed_count": 12 }, "pinned_tweet_id": "1296498078233571329", "created_at": "2017-04-27T20:56:22.000Z", "protected": false } ], "tweets": [ { "public_metrics": { "retweet_count": 19, "reply_count": 1, "like_count": 71, "quote_count": 6 }, "conversation_id": "1229843515603144704", "id": "1229843515603144704", "entities": { "annotations": [ { "start": 11, "end": 21, "probability": 0.3342, "type": "Product", "normalized_text": "Alexa Skill" }, { "start": 27, "end": 33, "probability": 0.6727, "type": "Product", "normalized_text": "Twitter" } ], "urls": [ { "start": 127, "end": 150, "url": "https://t.co/l5J8wq748G", "expanded_url": "https://dev.to/twitterdev/building-an-alexa-skill-for-twitter-using-alexa-presentation-language-1aj0", "display_url": "dev.to/twitterdev/bui…", "status": 200, "unwound_url": "https://dev.to/twitterdev/building-an-alexa-skill-for-twitter-using-alexa-presentation-language-1aj0" } ] }, "text": "I built an Alexa Skill for Twitter using APL that allows you to view Tweets and Trends on the echo show!\n\nCheck it out here 👇\n\nhttps://t.co/l5J8wq748G", "created_at": "2020-02-18T19:01:58.000Z", "possibly_sensitive": false, "author_id": "857699969263964161", "context_annotations": [ { "domain": { "id": "47", "name": "Brand", "description": "Brands and Companies" }, "entity": { "id": "10026792024", "name": "Amazon" } }, { "domain": { "id": "48", "name": "Product", "description": "Products created by Brands. Examples: Ford Explorer, Apple iPhone." }, "entity": { "id": "968221983803494400", "name": "Amazon - Alexa", "description": "Alexa" } }, { "domain": { "id": "46", "name": "Brand Category", "description": "Categories within Brand Verticals that narrow down the scope of Brands" }, "entity": { "id": "781974596752842752", "name": "Services" } }, { "domain": { "id": "47", "name": "Brand", "description": "Brands and Companies" }, "entity": { "id": "10045225402", "name": "Twitter" } } ], "source": "Twitter Web App", "lang": "en" } ] } }` ### Quote Tweet `{ "data": [ { "lang": "en", "conversation_id": "1328399838128467969", "text": "As planned, the Labs v2 endpoints referenced below have now been retired. Please let us know in the forums if you have questions or need help with the X API v2! https://t.co/JaxttUMmjX", "referenced_tweets": [ { "type": "quoted", "id": "1327011423252144128" } ], "possibly_sensitive": false, "entities": { "annotations": [ { "start": 151, "end": 157, "probability": 0.8115, "type": "Product", "normalized_text": "Twitter" } ], "urls": [ { "start": 167, "end": 190, "url": "https://t.co/JaxttUMmjX", "expanded_url": "https://x.com/TwitterDev/status/1327011423252144128", "display_url": "twitter.com/TwitterDev/sta…" } ] }, "id": "1328399838128467969", "public_metrics": { "retweet_count": 7, "reply_count": 4, "like_count": 29, "quote_count": 1 }, "author_id": "2244994945", "context_annotations": [ { "domain": { "id": "46", "name": "Brand Category", "description": "Categories within Brand Verticals that narrow down the scope of Brands" }, "entity": { "id": "781974596752842752", "name": "Services" } }, { "domain": { "id": "47", "name": "Brand", "description": "Brands and Companies" }, "entity": { "id": "10045225402", "name": "Twitter" } }, { "domain": { "id": "65", "name": "Interests and Hobbies Vertical", "description": "Top level interests and hobbies groupings, like Food or Travel" }, "entity": { "id": "848920371311001600", "name": "Technology", "description": "Technology and computing" } }, { "domain": { "id": "66", "name": "Interests and Hobbies Category", "description": "A grouping of interests and hobbies entities, like Novelty Food or Destinations" }, "entity": { "id": "848921413196984320", "name": "Computer programming", "description": "Computer programming" } } ], "source": "Twitter Web App", "created_at": "2020-11-16T18:09:36.000Z" } ], "includes": { "users": [ { "created_at": "2013-12-14T04:35:55.000Z", "id": "2244994945", "protected": false, "username": "TwitterDev", "verified": true, "entities": { "url": { "urls": [ { "start": 0, "end": 23, "url": "https://t.co/3ZX3TNiZCY", "expanded_url": "https://developer.x.com/en/community", "display_url": "developer.x.com/en/community" } ] }, "description": { "hashtags": [ { "start": 17, "end": 28, "tag": "TwitterDev" }, { "start": 105, "end": 116, "tag": "TwitterAPI" } ] } }, "description": "The voice of the #TwitterDev team and your official source for updates, news, and events, related to the #TwitterAPI.", "pinned_tweet_id": "1293593516040269825", "public_metrics": { "followers_count": 513962, "following_count": 2039, "tweet_count": 3635, "listed_count": 1672 }, "location": "127.0.0.1", "name": "Twitter Dev", "profile_image_url": "https://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", "url": "https://t.co/3ZX3TNiZCY" } ], "tweets": [ { "lang": "en", "conversation_id": "1327011423252144128", "text": "👋 Friendly reminder that Twitter Developer Labs v2 hide replies and recent search will be retired next Monday, November 16! We encourage you to migrate to the new hide replies and recent search endpoints now available in the v2 #TwitterAPI. Details: https://t.co/r6z6CI7kEy", "possibly_sensitive": false, "entities": { "annotations": [ { "start": 26, "end": 50, "probability": 0.4387, "type": "Product", "normalized_text": "Twitter Developer Labs v2" } ], "hashtags": [ { "start": 228, "end": 239, "tag": "TwitterAPI" } ], "urls": [ { "start": 250, "end": 273, "url": "https://t.co/r6z6CI7kEy", "expanded_url": "https://devcommunity.x.com/t/retiring-labs-v2-recent-search-and-hide-replies/145795", "display_url": "devcommunity.com/t/retiring-lab…", "images": [ { "url": "https://pbs.twimg.com/news_img/1327011425240313856/PkurOyu1?format=jpg&name=orig", "width": 1200, "height": 630 }, { "url": "https://pbs.twimg.com/news_img/1327011425240313856/PkurOyu1?format=jpg&name=150x150", "width": 150, "height": 150 } ], "status": 200, "title": "Retiring Labs v2 recent search and hide replies", "description": "As we said in our Early Access and hide replies announcements, the following Twitter Developer Labs v2 endpoints will be retired on November 16th. Labs v2 recent search Labs v2 hide replies If called, these endpoints will respond with an HTTP 410 status and return no data. Based on your feedback from Labs, we incorporated corresponding functionality into the X API v2. The relevant documentation can be found using the links below. Click here to enroll in v2 access if you haven’t already...", "unwound_url": "https://devcommunity.x.com/t/retiring-labs-v2-recent-search-and-hide-replies/145795" } ] }, "id": "1327011423252144128", "public_metrics": { "retweet_count": 8, "reply_count": 2, "like_count": 33, "quote_count": 4 }, "author_id": "2244994945", "context_annotations": [ { "domain": { "id": "46", "name": "Brand Category", "description": "Categories within Brand Verticals that narrow down the scope of Brands" }, "entity": { "id": "781974596752842752", "name": "Services" } }, { "domain": { "id": "47", "name": "Brand", "description": "Brands and Companies" }, "entity": { "id": "10045225402", "name": "Twitter" } }, { "domain": { "id": "65", "name": "Interests and Hobbies Vertical", "description": "Top level interests and hobbies groupings, like Food or Travel" }, "entity": { "id": "848920371311001600", "name": "Technology", "description": "Technology and computing" } }, { "domain": { "id": "66", "name": "Interests and Hobbies Category", "description": "A grouping of interests and hobbies entities, like Novelty Food or Destinations" }, "entity": { "id": "848921413196984320", "name": "Computer programming", "description": "Computer programming" } } ], "source": "Twitter Web App", "created_at": "2020-11-12T22:12:32.000Z" } ] } } ``` ### Retweeted quote Tweet ``` { "data": [ { "lang": "en", "conversation_id": "1225470895902412800", "text": "RT @AureliaSpecker: 📣 If you enjoyed the London commute tutorial I wrote in November last year, check out the refactored version that uses…", "referenced_tweets": [ { "type": "retweeted", "id": "1224709550214873090" } ], "possibly_sensitive": false, "entities": { "annotations": [ { "start": 42, "end": 47, "probability": 0.6999, "type": "Place", "normalized_text": "London" } ], "mentions": [ { "start": 3, "end": 18, "username": "AureliaSpecker" } ] }, "id": "1225470895902412800", "public_metrics": { "retweet_count": 12, "reply_count": 0, "like_count": 0, "quote_count": 0 }, "author_id": "2244994945", "context_annotations": [ { "domain": { "id": "46", "name": "Brand Category", "description": "Categories within Brand Verticals that narrow down the scope of Brands" }, "entity": { "id": "781974596752842752", "name": "Services" } }, { "domain": { "id": "47", "name": "Brand", "description": "Brands and Companies" }, "entity": { "id": "10045225402", "name": "Twitter" } }, { "domain": { "id": "65", "name": "Interests and Hobbies Vertical", "description": "Top level interests and hobbies groupings, like Food or Travel" }, "entity": { "id": "848920371311001600", "name": "Technology", "description": "Technology and computing" } }, { "domain": { "id": "66", "name": "Interests and Hobbies Category", "description": "A grouping of interests and hobbies entities, like Novelty Food or Destinations" }, "entity": { "id": "848921413196984320", "name": "Computer programming", "description": "Computer programming" } } ], "source": "Twitter for iPhone", "created_at": "2020-02-06T17:26:44.000Z" } ], "includes": { "users": [ { "created_at": "2013-12-14T04:35:55.000Z", "id": "2244994945", "protected": false, "username": "TwitterDev", "verified": true, "entities": { "url": { "urls": [ { "start": 0, "end": 23, "url": "https://t.co/3ZX3TNiZCY", "expanded_url": "https://developer.x.com/en/community", "display_url": "developer.x.com/en/community" } ] }, "description": { "hashtags": [ { "start": 17, "end": 28, "tag": "TwitterDev" }, { "start": 105, "end": 116, "tag": "TwitterAPI" } ] } }, "description": "The voice of the #TwitterDev team and your official source for updates, news, and events, related to the #TwitterAPI.", "pinned_tweet_id": "1293593516040269825", "public_metrics": { "followers_count": 513962, "following_count": 2039, "tweet_count": 3635, "listed_count": 1672 }, "location": "127.0.0.1", "name": "Twitter Dev", "profile_image_url": "https://pbs.twimg.com/profile_images/1283786620521652229/lEODkLTh_normal.jpg", "url": "https://t.co/3ZX3TNiZCY" }, { "created_at": "2013-01-18T23:45:43.000Z", "id": "1102321381", "protected": false, "username": "AureliaSpecker", "verified": false, "entities": { "description": { "mentions": [ { "start": 7, "end": 17, "username": "TwitterUK" }, { "start": 86, "end": 95, "username": "_dormrod" } ] } }, "description": "devrel @TwitterUK • Swiss in London • mother of houseplants • personal hairdresser to @_dormrod", "pinned_tweet_id": "1253069421322567681", "public_metrics": { "followers_count": 1036, "following_count": 1330, "tweet_count": 855, "listed_count": 26 }, "location": "London, UK", "name": "Aurelia Specker", "profile_image_url": "https://pbs.twimg.com/profile_images/1137517534104772608/8FBYgc6G_normal.jpg", "url": "" } ], "tweets": [ { "lang": "en", "conversation_id": "1224709550214873090", "text": "📣 If you enjoyed the London commute tutorial I wrote in November last year, check out the refactored version that uses Twitter's new search endpoint 🚇 https://t.co/87XIPZmZBJ\n\n#DEVcommunity #Pythontutorial @TwitterDev @TwitterAPI https://t.co/dXrJYvn3hY", "referenced_tweets": [ { "type": "quoted", "id": "1195000047089389573" } ], "possibly_sensitive": false, "entities": { "annotations": [ { "start": 22, "end": 27, "probability": 0.7075, "type": "Place", "normalized_text": "London" }, { "start": 120, "end": 126, "probability": 0.7355, "type": "Product", "normalized_text": "Twitter" } ], "mentions": [ { "start": 206, "end": 217, "username": "TwitterDev" }, { "start": 218, "end": 229, "username": "TwitterAPI" } ], "hashtags": [ { "start": 176, "end": 189, "tag": "DEVcommunity" }, { "start": 190, "end": 205, "tag": "Pythontutorial" } ], "urls": [ { "start": 151, "end": 174, "url": "https://t.co/87XIPZmZBJ", "expanded_url": "https://bit.ly/2OrnrCC", "display_url": "bit.ly/2OrnrCC", "status": 200, "unwound_url": "https://dev.to/twitterdev/migrate-to-twitter-s-newly-released-labs-recent-search-endpoint-3npe" }, { "start": 230, "end": 253, "url": "https://t.co/dXrJYvn3hY", "expanded_url": "https://x.com/AureliaSpecker/status/1195000047089389573", "display_url": "twitter.com/AureliaSpecker…" } ] }, "id": "1224709550214873090", "public_metrics": { "retweet_count": 12, "reply_count": 0, "like_count": 43, "quote_count": 2 }, "author_id": "1102321381", "context_annotations": [ { "domain": { "id": "46", "name": "Brand Category", "description": "Categories within Brand Verticals that narrow down the scope of Brands" }, "entity": { "id": "781974596752842752", "name": "Services" } }, { "domain": { "id": "47", "name": "Brand", "description": "Brands and Companies" }, "entity": { "id": "10045225402", "name": "Twitter" } }, { "domain": { "id": "65", "name": "Interests and Hobbies Vertical", "description": "Top level interests and hobbies groupings, like Food or Travel" }, "entity": { "id": "848920371311001600", "name": "Technology", "description": "Technology and computing" } }, { "domain": { "id": "66", "name": "Interests and Hobbies Category", "description": "A grouping of interests and hobbies entities, like Novelty Food or Destinations" }, "entity": { "id": "848921413196984320", "name": "Computer programming", "description": "Computer programming" } } ], "source": "Twitter Web App", "created_at": "2020-02-04T15:01:25.000Z" } ] } } ``` # Edit Posts Source: https://docs.x.com/x-api/fundamentals/edit-posts Working with edited posts in the X API Posts on X can be edited within 30 minutes of posting, up to 5 times. The X API provides full access to edit history and metadata. *** ## Edit rules | Rule | Details | | :-------------- | :-------------------------------------------- | | **Time window** | 30 minutes from original post | | **Edit limit** | 5 edits maximum | | **ID behavior** | Each edit creates a new post ID | | **Deletion** | Deleting any version deletes the entire chain | *** ## What can't be edited Some post types are not editable: * Promoted posts (ads) * Posts with polls * Replies to others (non-self-thread) * Reposts (Quote posts *can* be edited) * Community posts * Collaborative posts * Scheduled posts *** ## Edit data in responses ### Default fields All post responses include `edit_history_tweet_ids` by default: ```json theme={null} { "data": { "id": "1234567891", "text": "Updated text (edited)", "edit_history_tweet_ids": ["1234567890", "1234567891"] } } ``` * Single ID = never edited * Multiple IDs = edit history (oldest first) ### Edit controls Request `edit_controls` for edit status: ```bash theme={null} curl "https://api.x.com/2/tweets/1234567891?tweet.fields=edit_controls" \ -H "Authorization: Bearer $TOKEN" ``` ```json theme={null} { "data": { "id": "1234567891", "text": "Updated text (edited)", "edit_history_tweet_ids": ["1234567890", "1234567891"], "edit_controls": { "is_edit_eligible": true, "editable_until": "2024-01-15T12:30:00.000Z", "edits_remaining": 3 } } } ``` | Field | Description | | :----------------- | :-------------------------------- | | `is_edit_eligible` | Whether the post can be edited | | `editable_until` | Timestamp when edit window closes | | `edits_remaining` | Number of edits left (0-5) | *** ## Getting edit history Use the `edit_history_tweet_ids` expansion to get full post objects for all versions: ```bash theme={null} curl "https://api.x.com/2/tweets/1234567891?\ tweet.fields=edit_controls&\ expansions=edit_history_tweet_ids" \ -H "Authorization: Bearer $TOKEN" ``` ```json theme={null} { "data": { "id": "1234567891", "text": "Updated text (edited)", "edit_history_tweet_ids": ["1234567890", "1234567891"], "edit_controls": { "is_edit_eligible": true, "editable_until": "2024-01-15T12:30:00.000Z", "edits_remaining": 3 } }, "includes": { "tweets": [{ "id": "1234567890", "text": "Original text (with typo)", "edit_history_tweet_ids": ["1234567890", "1234567891"], "edit_controls": { "is_edit_eligible": true, "editable_until": "2024-01-15T12:30:00.000Z", "edits_remaining": 3 } }] } } ``` *** ## Which version is returned? By default, the API returns the **most recent version** of an edited post. To get a specific version, request it by its post ID directly: ```bash theme={null} # Get original version curl "https://api.x.com/2/tweets/1234567890" -H "Authorization: Bearer $TOKEN" # Get edited version curl "https://api.x.com/2/tweets/1234567891" -H "Authorization: Bearer $TOKEN" ``` *** ## Metrics for edited posts Each version of an edited post has its own engagement metrics. The metrics are attributed to the version that was visible when the engagement occurred. *** ## Availability Edit metadata is available: * For all posts created since September 29, 2022 * On all v2 endpoints that return posts * Including search, timelines, stream, and lookup Posts created before this date do not have edit metadata. *** ## Use cases
(lightweight)"] --> B["Memory Buffer
(expandable)"] --> C["Processing Thread(s)
(scalable)"] ``` *** ## Consider time zones Global events happen in global time zones. Events may occur: * After business hours * Over weekends * During holidays Ensure your team is prepared for spikes outside normal business hours. Consider: * Automated alerting systems * On-call rotations * Automated scaling responses *** ## Monitoring recommendations 1. **Track Post volume** in real-time 2. **Set up alerts** for volume thresholds (both increases and decreases) 3. **Monitor buffer sizes** to detect when your processing is falling behind 4. **Compare Post timestamps** to current time to identify lag *** ## Emergency measures Implement safeguards for extreme circumstances: * **Automated alerts** when volume passes preset thresholds * **Automated rule deletion** for rules bringing in excessive data * **Stream disconnection** in extreme circumstances to protect your systems * **Sampling operators** — add `sample:` to rules to reduce matching volume *** ## Next steps
rules"] --> B["Connect to
streaming endpoint"] --> C["Receive
matching Posts"] ``` *** ## Endpoints | Method | Endpoint | Description | | :----- | :------------------------------------------------------------------- | :-------------------- | | GET | [`/2/tweets/search/stream`](/x-api/stream/stream-filtered-posts) | Connect to the stream | | POST | [`/2/tweets/search/stream/rules`](/x-api/stream/update-stream-rules) | Add or delete rules | | GET | [`/2/tweets/search/stream/rules`](/x-api/stream/get-stream-rules) | List current rules | *** ## Access levels | Feature | Pay-per-use | Enterprise | | :---------------- | :---------- | :---------- | | Rules per project | 1,000 | 25,000+ | | Rule length | 1,024 chars | 2,048 chars | | Connections | 1 | Multiple | | All operators | ✓ | ✓ |
[Lookup using multiple Spaces IDs](/x-api/spaces/space-lookup-up-space-ids)
[Lookup by their creator ID](/x-api/spaces/space-lookup-by-their-creators)
[Lookup list of user who purchased a ticket](/x-api/spaces/retrieve-the-list-of-users-who-purchased-a-ticket-to-the-given-space) | | **Search Spaces** | [Search for spaces using a keyword](/x-api/spaces/search-for-spaces) | #### Understanding the lifecycle of Spaces Unlike other resources of the X Developer Platform, Spaces have a set lifecycle. Spaces can be scheduled up to 14 days in advance of their intended start date, and become unavailable after they end. A host can also cancel a previously scheduled Space anytime before it starts. Spaces are accessible while they are live; once ended, they will no longer be available for retrieval using the Spaces endpoints, and an error message will be returned to indicate this condition. When your app handles Spaces data, you are responsible for returning the most up-to-date information, and that you remove data that is no longer available from the platform. The [Spaces lookup endpoint](/x-api/spaces/lookup/introduction) can help you ensure you respect the expectations and intent of your users. ### Roles in Spaces These endpoints reflect the way Spaces work on the X app. In Spaces, X users can have defined roles depending on how they interact with and interact in a Space. ### Creator (or primary host) The primary Host is the user who created a Space, and the owner of the Space itself. Currently, Spaces can only have one Host, so the primary Host will be the only Host. In the [Spaces data dictionary](/x-api/fundamentals/data-dictionary#space), the primary Host information will be in the creator\_id field, which can be expanded into a [user object](/x-api/fundamentals/data-dictionary#user). ### Hosts The primary Hosts can make one or more users co-hosts. In the Spaces data dictionary, these Hosts will appear as host\_ids, which can be expanded into a list of user objects. Host designation can change throughout the duration of a Space, and the metadata returned by these endpoints will reflect the status at the time of the request. Your app will know the primary host by checking the creator\_id value, and who are the co-hosts by checking the host\_ids values. ### Speaker Speakers are users who have permission to talk in the Space. Zero or more Speakers can be present at any time, and there may be up to 10 Speakers (including the Hosts) in a Space. In the Space data dictionary, speakers will be returned in the speaker\_ids list, which you can expand into a list of user objects. ### Listener A Listener can listen to a Space, react anytime using the predefined reactions, and ask to become a speaker (when the Hosts allows this in the Space settings). Listener information will only be returned as an aggregate count of participants (including Hosts) in the participant\_count field. # Spaces Lookup Source: https://docs.x.com/x-api/spaces/lookup/introduction Retrieve Space details by ID or find Spaces by their creators The Spaces lookup endpoints let you retrieve information about live or scheduled Spaces. Look up Spaces by their ID or find Spaces created by specific users. ## Overview
[**View tutorial**](/tutorials/explore-a-users-posts)
[**View tutorial**](/tutorials/postman-getting-started)
[**View tutorial**](/tutorials/getting-started-with-r-and-v2-of-the-x-api)
[**View tutorial**](/tutorials/getting-historical-posts-using-the-full-archive-search-endpoint)
[**View tutorial**](/tutorials/post-processing-x-data-with-the-google-cloud-platform)
45 days (segmented) | | Segmentation | No | Yes | | Response returns | Metrics data | Processing state of the job\*\* | | Recommended use case | Real-time optimization
User interface requests | Regularly-scheduled syncing
Backfilling historical data |
2019-03-05T14:40:59Z | 2019-03-04T00:00:00Z
2019-03-06T00:00:00Z | **Note**: It's important to include the timestamps with hours, minutes, and seconds set to zero. Otherwise, if only the date is passed in, we will assume you're requesting analytics starting and ending at midnight in the ads account's timezone, which may not be desirable. For example, if the minimum activity start time is 2019-02-28T01:30:07Z and the timestamp is omitted for an ads account with an offset of -08:00:00, the analytics request will miss changes that happened between 01:30 and 08:00. Alternatively, if you would prefer to request analytics for just the returned activity time window without expanding to full days, you can. Using this approach, the derived start and end times would be 2019-03-04T20:00:00Z and 2019-03-05T15:00:00Z, respectively. (Note that ranges like these are not accepted if you specify `DAY` granularity in the analytics request.) #### Example This section demonstrates how to use Active Entities in conjunction with the synchronous analytics endpoint. (The responses have been slightly modified for readability.) In this example, the Active Entities endpoint is called at the top of each hour, with each request looking at the previous hour. The response determines how the synchronous analytics endpoint is used. The first Active Entities request is made at 03:00:00. The response indicates that line item dvcz7's metrics changed and that those change events apply to the window between 02:02:55 and 02:28:12. ``` `twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2019-02-11T02:00:00Z&end_time=2019-02-11T03:00:00Z"` ``` ```json theme={null} { "request": {}, "data": [ { "entity_id": "dvcz7", "activity_start_time": "2019-02-11T02:02:55Z", "activity_end_time": "2019-02-11T02:58:12Z", "placements": [ "ALL_ON_TWITTER" ] } ] } ``` Based on these activity start and end times and using the approach described above, the analytics `start_time` and `end_time` values are set to 2019-02-11T00:00:00Z and 2019-02-12T00:00:00Z, respectively. We see that the third element in each of the metrics arrays below are non-zero, as we expected based on the active entities information. ``` `twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=dvcz7&start_time=2019-02-11T00:00:00Z&end_time=2019-02-12T00:00:00Z&granularity=HOUR&metric_groups=ENGAGEMENT,VIDEO&placement=ALL_ON_TWITTER"` ``` ```json theme={null} { "data_type": "stats", "time_series_length": 24, "data": [ { "id": "dvcz7", "id_data": [ { "segment": null, "metrics": { "impressions": [ 0,0,2792,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 ], "engagements": [ 0,0,60,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 ], "video_total_views": [ 0,0,1326,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 ] } } ] } ], "request": {} } ``` The next Active Entities request happens at 04:00:00 and only looks at the previous hour. As mentioned above, a time window should only be requested once. Based on the response, we see that change events for this line item apply to *both* 02:00:00 and 03:00:00. In the subsequent analytics request, we expect to see changes for both hours. ``` `twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t/active_entities?entity= LINE_ITEM&start_time=2019-02-11T03:00:00Z&end_time=2019-02-11T04:00:00Z"` ``` ```json theme={null} { "request": {}, "data": [ { "entity_id": "dvcz7", "activity_start_time": "2019-02-11T02:07:17Z", "activity_end_time": "2019-02-11T03:49:22Z", "placements": [ "ALL_ON_TWITTER" ] } ] } ``` In addition to seeing non-zero metrics for 03:00:00, we see that the impressions, spend, and MRC video views have been updated from their previous values. Impressions, for example, are now 2,995 for the 02:00:00 hour, up from 2,792. This demonstrates how change events that were recorded during the 03:00:00 hour apply to the 02:00:00 hour. ``` `twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=dvcz7&start_time=2019-02-11T00:00:00Z&end_time=2019-02-12T00:00:00Z&granularity=HOUR&metric_groups=ENGAGEMENT,VIDEO&placement=ALL_ON_TWITTER"` ``` ```json theme={null} { "data_type": "stats", "time_series_length": 24, "data": [ { "id": "dvcz7", "id_data": [ { "segment": null, "metrics": { "impressions": [ 0,0,2995,734,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 ], "engagements": [ 0,0,65,7,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 ], "video_total_views": [ 0,0,1449,342,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 ] } } ] } ], "request": {} } ``` The Active Entities request at 05:00:00, again looking at just the previous hour, shows that change events apply to the 03:00:00 hour only. The changes to analytics metrics in the subsequent request reflect this. ``` `twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2019-02-11T04:00:00Z&end_time=2019-02-11T05:00:00Z"` ``` ```json theme={null} { "request": {}, "data": [ { "entity_id": "dvcz7", "activity_start_time": "2019-02-11T03:42:39Z", "activity_end_time": "2019-02-11T03:48:48Z", "placements": [ "ALL_ON_TWITTER" ] } ] } ``` The analytics response shows that only metrics for the 03:00:00 hour have changed; the values for the 02:00:00 hour are the same as they were during the previous analytics request. ``` `twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids= dvcz7&start_time=2019-02-11T00:00:00Z&end_time=2019-02-12T00:00:00Z&granularity=HOUR&metric_groups=ENGAGEMENT,VIDEO&placement=ALL_ON_TWITTER"` ``` ```json theme={null} { "data_type": "stats", "time_series_length": 24, "data": [ { "id": "dvcz7", "id_data": [ { "segment": null, "metrics": { "impressions": [ 0,0,2995,753,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 ], "engagements": [ 0,0,65,8,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 ], "video_total_views": [ 0,0,1449,351,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 ] } } ] } ], "request": {} } ``` Finally, at 06:00:00 we see that there are no additional change events. **Note**: This does *not* imply that metrics for this line item cannot change in the future, though. ``` `twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t/active_entities?entity=LINE_ITEM&start_time=2019-02-11T05:00:00Z&end_time=2019-02-11T06:00:00Z"` ``` ```json theme={null} { "request": {}, "data": [] } ``` ### Asynchronous Guide ## API Reference ### Asynchronous Analytics #### Introduction The asynchronous analytics endpoints allow partners and advertisers to request metrics by submitting create requests that the server processes asynchronously. (We refer to these as asynchronous analytics "jobs.") With this approach, the client's connection does not need to remain open until the request has been fulfilled. These endpoints, like their synchronous counterpart, allow partners and advertisers to request detailed statistics on campaign performance. They support requesting data for accounts, funding instruments, campaigns, line items, promoted Tweets, and media creatives. The difference between these and the synchronous endpoint is that the asynchronous analytics endpoints support longer date ranges, up to 90 days, as well as segmentation. Additional details on the differences between the two can be found on our [Analytics Overview](/x-ads-api/analytics) page. Unlike our synchronous endpoints, rate limiting is based on the number of concurrent jobs for a given account. In other words, it's based on the number of jobs that can be in a processing state at a given time. We count this at the ads account level. #### Usage Retrieving campaign metrics using the asynchronous analytics endpoints is a multi-step process. It involves creating a job, checking whether the job has finished processing, and, finally, downloading the data. The data file must be decompressed. The four specific steps are outlined below. 1. Create the job using the [POST stats/jobs/accounts/:account\_id](/x-ads-api/analytics#asynchronous-analytics) endpoint. 2. Make requests at regular intervals to the [GET stats/jobs/accounts/:account\_id](/x-ads-api/analytics#asynchronous-analytics) endpoint to determine whether the job has finished processing. 3. Once the job has finished processing, download the data file. 4. Unzip the data file. The response object returned in the data file has the same JSON schema as the synchronous analytics endpoint's response. Segmented campaign metrics are only available via the asynchronous analytics endpoints. Campaign metrics can be broken out by location, gender, interest, keyword, and more. For a full list of options, see the [Metrics and Segmentation](/x-ads-api/analytics#metrics-and-segmentation) page. In order to request segmented metrics, use the `segmentation_type` request parameter when creating the job. #### Example This section demonstrates how to use the asynchronous analytics endpoints. Start by creating a job using the [POST stats/jobs/accounts/:account\_id](/x-ads-api/analytics#asynchronous-analytics) endpoint. The example below requests engagement metrics—such as impressions, likes, clicks, etc.—for a specific line item over a week's time. (Note that the requested time range goes up to, but does not include March 20th since the timestamp is set to midnight.) ``` $ twurl -X POST -H ads-api.x.com "/9/stats/jobs/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=el32n&start_time=2019-03-12T00:00:00Z&end_time=2019-03-20T00:00:00Z&granularity=TOTAL&placement=ALL_ON_TWITTER&metric_groups=ENGAGEMENT" ``` ```json theme={null} { "request": { "params": { "start_time": "2019-03-12T00:00:00Z", "entity_ids": [ "el32n" ], "end_time": "2019-03-20T00:00:00Z", "placement": "ALL_ON_TWITTER", "granularity": "TOTAL", "entity": "LINE_ITEM", "metric_groups": [ "ENGAGEMENT" ] } }, "data": { "start_time": "2019-03-12T00:00:00Z", "segmentation_type": null, "url": null, "id_str": "1120829647711653888", "entity_ids": [ "el32n" ], "end_time": "2019-03-20T00:00:00Z", "country": null, "placement": "ALL_ON_TWITTER", "id": 1120829647711653888, "expires_at": null, "account_id": "18ce54d4x5t", "status": "PROCESSING", "granularity": "TOTAL", "entity": "LINE_ITEM", "created_at": "2019-04-23T23:19:46Z", "platform": null, "updated_at": "2019-04-23T23:19:46Z", "metric_groups": [ "ENGAGEMENT" ] } } ``` This response does not return the line item metrics. It simply provides information about the job you just created. The job ID is needed to check on the status of the job. This is shown in both the `id` and `id_str` response attributes. Next, you'll want to check whether the job you've created using the `id_str` from the previous response, has finished processing as indicated by `"status": "SUCCESS"` in the response. This means the data is ready to download. The `url` field contains the download link. ``` $ twurl -H ads-api.x.com "/9/stats/jobs/accounts/18ce54d4x5t?job_ids=1120829647711653888" ``` ```json theme={null} { "request": { "params": { "job_ids": [ 1120829647711653888 ] } }, "next_cursor": "1120828505715920896", "data": [ { "start_time": "2019-03-12T00:00:00Z", "segmentation_type": null, "url": "https://ton.twimg.com/advertiser-api-async-analytics/zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz", "id_str": "1120829647711653888", "entity_ids": [ "el32n" ], "end_time": "2019-03-20T00:00:00Z", "country": null, "placement": "ALL_ON_TWITTER", "id": 1120829647711653900, "expires_at": "2019-04-25T23:19:48Z", "account_id": "18ce54d4x5t", "status": "SUCCESS", "granularity": "TOTAL", "entity": "LINE_ITEM", "created_at": "2019-04-23T23:19:46Z", "platform": null, "updated_at": "2019-04-23T23:19:48Z", "metric_groups": [ "ENGAGEMENT" ] } ] } ``` While we're passing in a single job ID in the above example, in practice, you'll want to use the `job_ids` parameter to check on the status of multiple jobs at a time by specifying up to 200 job IDs. Next, download the data file using the listed `url` value. ``` $ wget https://ton.twimg.com/advertiser-api-async-analytics/zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz --2019-04-23 17:52:12-- https://ton.twimg.com/advertiser-api-async-analytics/zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz Resolving ton.twimg.com (ton.twimg.com)... 72.21.91.70 Connecting to ton.twimg.com (ton.twimg.com)|72.21.91.70|:443... connected. HTTP request sent, awaiting response... 200 OK Length: 381 [application/gzip] Saving to: 'zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz' zBkuuPeEVx-5OygDVcZpqNtwt51Z5 100%[=================================================>] 381 --.-KB/s in 0s 2019-04-23 17:52:12 (5.27 MB/s) - 'zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz' saved [381/381] ``` Finally, unzip the file. ``` `$ gunzip zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json.gz` ``` The contents of the file are shown below. ```json theme={null} `$ cat zBkuuPeEVx-5OygDVcZpqNtwt51Z5X9d-_AXNRcyhBlhBOgOfi6UDmGBvUFJAKnHY9ABN8z9f9V3Wn4l3OmF4KzJDmTUjNCikq9JwBUYm2AP8pRRoV-kPUgR0PaIqAb4.json` ``` ```json theme={null} { "data_type": "stats", "time_series_length": 1, "data": [ { "id": "el32n", "id_data": [ { "segment": null, "metrics": { "impressions": [ 3482 ], "tweets_send": null, "qualified_impressions": null, "follows": null, "app_clicks": null, "retweets": [ 102 ], "unfollows": null, "likes": [ 15 ], "engagements": [ 171 ], "clicks": [ 30 ], "card_engagements": null, "poll_card_vote": null, "replies": null, "carousel_swipes": null } } ] } ], "request": { "params": { "start_time": "2019-03-12T00:00:00Z", "segmentation_type": null, "entity_ids": [ "el32n" ], "end_time": "2019-03-20T00:00:00Z", "country": null, "placement": "ALL_ON_TWITTER", "granularity": "TOTAL", "entity": "LINE_ITEM", "platform": null, "metric_groups": [ "ENGAGEMENT" ] } } } ``` ### Reach and Average Frequency #### GET stats/accounts/:account\_id/reach/campaigns[](#get-stats-accounts-account-id-reach-campaigns "Permalink to this headline") Retrieve reach and average frequency analytics for specified campaigns. ### Resource URL[](#resource-url "Permalink to this headline") `https://ads-api.x.com/stats/accounts/:account_id/reach/campaigns` ### Parameters[](#parameters "Permalink to this headline") | Name | Description | | :------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` | | campaign\_ids
*required* | Scope the response to just the desired campaigns by specifying a comma-separated list of identifiers. Up to 20 IDs may be provided.
**Note**: Up to 20 campaign IDs may be provided.
Type: string
Example: `8fgzf` | | end\_time
*required* | Scopes the retrieved data to the specified end time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
**Note**: Must be expressed in whole hours (0 minutes and 0 seconds).
Type: string
Example: `2017-05-26T07:00:00Z` | | start\_time
*required* | Scopes the retrieved data to the specified start time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
**Note**: Must be expressed in whole hours (0 minutes and 0 seconds).
Type: string
Example: `2017-05-19T07:00:00Z` | ### Example Request[](#example-request "Permalink to this headline") `GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t/reach/campaigns?campaign_ids=8fgzf&start_time=2017-05-19&end_time=2017-05-26` ### Example Response[](#example-response "Permalink to this headline") ```json theme={null} { "request": { "params": { "campaign_ids": [ "8fgzf" ], "start_time": "2017-05-19T00:00:00Z", "end_time": "2017-05-26T00:00:00Z", "account_id": "18ce54d4x5t" } }, "data_type": "reach", "data": [ { "id": "8fgzf", "total_audience_reach": 1217, "average_frequency": 1.01 } ] } ``` #### GET stats/accounts/:account\_id/reach/funding\_instruments[](#get-stats-accounts-account-id-reach-funding-instruments "Permalink to this headline") Retrieve reach and average frequency analytics for specified funding instruments. ### Resource URL[](#resource-url "Permalink to this headline") `https://ads-api.x.com/stats/accounts/:account_id/reach/funding_instruments` ### Parameters[](#parameters "Permalink to this headline") | Name | Description | | :----------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` | | funding\_instrument\_ids
*required* | Scope the response to just the desired funding instruments by specifying a comma-separated list of identifiers. Up to 20 IDs may be provided.
**Note**: Up to 20 funding instrument IDs may be provided.
Type: string
Example: `lygyi` | | end\_time
*required* | Scopes the retrieved data to the specified end time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
**Note**: Must be expressed in whole hours (0 minutes and 0 seconds).
Type: string
Example: `2017-05-26T07:00:00Z` | | start\_time
*required* | Scopes the retrieved data to the specified start time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
**Note**: Must be expressed in whole hours (0 minutes and 0 seconds).
Type: string
Example: `2017-05-19T07:00:00Z` | ### Example Request[](#example-request "Permalink to this headline") ``` GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t/reach/funding_instruments?funding_instrument_ids=lygyi&start_time=2017-05-19&end_time=2017-05-26 ``` ### Example Response[](#example-response "Permalink to this headline") ```json theme={null} { "request": { "params": { "funding_instrument_ids": [ "lygyi" ], "start_time": "2017-05-19T00:00:00Z", "end_time": "2017-05-26T00:00:00Z", "account_id": "18ce54d4x5t" } }, "data_type": "reach", "data": [ { "id": "lygyi", "total_audience_reach": 1217, "average_frequency": 1.01 } ] } ``` ### Synchronous Analytics #### GET stats/accounts/:account\_id[](#get-stats-accounts-account-id "Permalink to this headline") Retrieve synchronous analytics for the current account. A maximum time range (`end_time` - `start_time`) of 7 days is allowed. ### Resource URL[](#resource-url "Permalink to this headline") `https://ads-api.x.com/12/stats/accounts/:account_id` ### Parameters[](#parameters "Permalink to this headline") | Name | Description | | :------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` | | end\_time
*required* | Scopes the retrieved data to the specified end time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
**Note**: Must be expressed in whole hours (0 minutes and 0 seconds).
Type: string
Example: `2017-05-26T07:00:00Z` | | entity
*required* | The entity type to retrieve data for.
Type: enum
Possible values: `ACCOUNT`, `CAMPAIGN`, `FUNDING_INSTRUMENT`, `LINE_ITEM`, `ORGANIC_TWEET`, `PROMOTED_ACCOUNT`, `PROMOTED_TWEET`, `MEDIA_CREATIVE` | | entity\_ids
*required* | The specific entities to retrieve data for. Specify a comma-separated list of entity IDs.
**Note**: Up to 20 entity IDs may be provided.
Type: string
Example: `8u94t` | | granularity
*required* | Specify how granular the retrieved data should be.
Type: enum
Possible values: `DAY`, `HOUR`, `TOTAL` | | metric\_groups
*required* | The specific metrics that should be returned. Specify a comma-separated list of metric groups. For more information see [Metrics and Segmentation](/x-ads-api/analytics#metrics-and-segmentation).
**Note**: `MOBILE_CONVERSION` data should be requested separately.
Type: enum
Possible values: `BILLING`, `ENGAGEMENT`, `LIFE_TIME_VALUE_MOBILE_CONVERSION`, `MEDIA`, `MOBILE_CONVERSION`, `VIDEO`, `WEB_CONVERSION` | | placement
*required* | Scopes the retrieved data to a particular placement.
**Note**: Only a single value accepted per request. For entities with both X and X Audience Platform placement, separate requests are required, one for each placement value.
Type: enum
Possible values: `ALL_ON_TWITTER`, `PUBLISHER_NETWORK`, `SPOTLIGHT`, `TREND` | | start\_time
*required* | Scopes the retrieved data to the specified start time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
**Note**: Must be expressed in whole hours (0 minutes and 0 seconds).
Type: string
Example: `2017-05-19T07:00:00Z` | ### Example Request[](#example-request "Permalink to this headline") ``` GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t?entity=LINE_ITEM&entity_ids=8u94t&start_time=2017-05-19&end_time=2017-05-26&granularity=TOTAL&placement=ALL_ON_TWITTER&metric_groups=ENGAGEMENT ``` ### Example Response[](#example-response "Permalink to this headline") ```json theme={null} { "data_type": "stats", "time_series_length": 1, "data": [ { "id": "8u94t", "id_data": [ { "segment": null, "metrics": { "impressions": [ 1233 ], "tweets_send": null, "qualified_impressions": null, "follows": null, "app_clicks": null, "retweets": null, "likes": [ 1 ], "engagements": [ 58 ], "clicks": [ 58 ], "card_engagements": null, "poll_card_vote": null, "replies": null, "carousel_swipes": null } } ] } ], "request": { "params": { "start_time": "2017-05-19T07:00:00Z", "segmentation_type": null, "entity_ids": [ "8u94t" ], "end_time": "2017-05-26T07:00:00Z", "country": null, "placement": "ALL_ON_TWITTER", "granularity": "TOTAL", "entity": "LINE_ITEM", "platform": null, "metric_groups": [ "ENGAGEMENT" ] } } } ``` ### Active Entities #### GET stats/accounts/:account\_id/active\_entities[](#get-stats-accounts-account-id-active-entities "Permalink to this headline") Retrieve details about which entities' analytics metrics have changed in a given time period. This endpoint should be used in conjunction with our analytics endpoints. The results of this endpoint indicate which ads entities to request analytics for. See our [Active Entities Guide](/x-ads-api/analytics#active-entities) for usage guidelines. Change events are available in hourly buckets. * The `start_time` and `end_time` values specify which hourly buckets to query. * The returned `data` array will include an object for every entity that should be included in subsequent analytics requests. * **IMPORTANT**: The dates that should be specified in subsequent analytics requests should be determined based on the `activity_start_time` and `activity_end_time` values. * These values represent the time ranges that the stored change events *apply to*. This is returned per entity. **Note**: A maximum time range (`end_time` - `start_time`) of 90 days is allowed. ### Resource URL[](#resource-url "Permalink to this headline") `https://ads-api.x.com/12/stats/accounts/:account_id/active_entities` ### Parameters[](#parameters "Permalink to this headline") | Name | Description | | :----------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` | | end\_time
*required* | Scopes the retrieved data to the specified end time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
**Note**: Must be expressed in whole hours (0 minutes and 0 seconds).
Type: string
Example: `2017-05-26T07:00:00Z` | | entity
*required* | The entity type to retrieve data for.
Type: enum
Possible values: `CAMPAIGN`, `FUNDING_INSTRUMENT`, `LINE_ITEM`, `MEDIA_CREATIVE`, `PROMOTED_ACCOUNT`, `PROMOTED_TWEET` | | start\_time
*required* | Scopes the retrieved data to the specified start time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
**Note**: Must be expressed in whole hours (0 minutes and 0 seconds).
Type: string
Example: `2017-05-19T07:00:00Z` | | campaign\_ids
*optional* | Scope the response to just entities associated with desired campaigns by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
**Note**: Exclusive with `funding_instrument_ids` and `line_item_ids`.
Type: string
Example: `8wku2` | | funding\_instrument\_ids
*optional* | Scope the response to just entities associated with desired funding instruments by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
**Note**: Exclusive with `campaign_ids` and `line_item_ids`.
Type: string
Example: `lygyi` | | line\_item\_ids
*optional* | Scope the response to just entities associated with desired line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
**Note**: Exclusive with `campaign_ids` and `line_item_ids`.
Type: string
Example: `8v7jo` | ### Example Request[](#example-request "Permalink to this headline") `GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t/active_entities?entity=PROMOTED_TWEET&start_time=2019-02-28&end_time=2019-03-01` ### Example Response[](#example-response "Permalink to this headline") ```json theme={null} { "request": { "params": { "account_id": "18ce54d4x5t", "entity": "PROMOTED_TWEET", "start_time": "2019-02-28T08:00:00Z", "end_time": "2019-03-01T08:00:00Z" } }, "data": [ { "entity_id": "2mvb28", "activity_start_time": "2019-02-28T01:30:07Z", "activity_end_time": "2019-03-01T07:42:55Z", "placements": [ "ALL_ON_TWITTER" ] }, { "entity_id": "2mvb29", "activity_start_time": "2019-02-27T11:30:07Z", "activity_end_time": "2019-03-01T07:42:50Z", "placements": [ "ALL_ON_TWITTER", "PUBLISHER_NETWORK" ] }, { "entity_id": "2mvfan", "activity_start_time": "2019-02-27T09:00:05Z", "activity_end_time": "2019-03-01T06:06:36Z", "placements": [ "PUBLISHER_NETWORK" ] }, { "entity_id": "2n17dx", "activity_start_time": "2019-02-28T02:02:26Z", "activity_end_time": "2019-03-01T07:52:44Z", "placements": [ "ALL_ON_TWITTER", "PUBLISHER_NETWORK" ] } ] } ``` # Audiences Source: https://docs.x.com/x-ads-api/audiences ## Custom Audiences ### Overview There are multiple ways for partners to create [Custom Audiences](https://business.x.com/en/targeting/tailored-audiences.html). * [Audience API (CRM)](#crm) * [Web](#web) * [Mobile](#mobile) * [Flexible](#flexible) Please note that you cannot exclude lookalike custom audiences from targeting. Additionally, you cannot target both a custom audience and a custom audience lookalike on the same ad line item (ad group). **Audience management** Audiences can be managed via audience partners and Ads API partners. We offer a series of endpoints in the API to access and maintain custom audiences. For custom audience information, we offer 2 endpoints: * [GET accounts/:account\_id/custom\_audiences](/x-ads-api/audiences) * [GET accounts/:account\_id/custom\_audiences/:custom\_audience\_id](/x-ads-api/audiences) For more details on how to upload and manage audiences, view the [Audience API guide](/x-ads-api/audiences). **Processing Times** Generally speaking audience changes are processed in batches that run every 6-8 hours. While an audience change is processing the existing audience to be updated is unaffected. We do not recommend making more than one update for additions and one update for removals per audience within this timeframe. **Targeting** An audience can only be targeted if it matches at least 100 users active within the past 90 days on X-owned and -operated clients. [GET accounts/:account\_id/custom\_audiences/:custom\_audience\_id](/x-ads-api/audiences) will indicate if an audience may not be targeted because it matches too few users. **Audience API (CRM)**
```
**Opt-Out File Configuration and Sending Opt-Out Files**
Partners should provide X with a list of users that to the partner’s best knowledge have selected to opt-out of targeted ad delivery. The format of file should be sent as:
| | | | |
| :---------------- | :---------------------------------- | :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Column Number** | **Column Name** | **Column Type** | **Description** |
| 1 | Partner ID | string | The “partner id” is the ID that X provides to the Partner in order to uniquely identify each Partner. |
| 2 | The user’s id in the partner system | string | The `p_user_id` is the unique ID that is used to identify the user by the Partner. The file containing these opt-out users should be uploaded using the [TON upload](/x-ads-api/audiences) endpoint and the path of uploaded data should be sent to the Global Opt Out endpoint here:[PUT accounts/:account\_id/custom\_audiences/global\_opt\_out](/x-ads-api/audiences). |
**Sending Membership Updates**
As specified in our endpoint documentation, when passing users via the [POST custom\_audience\_memberships](/x-ads-api/audiences) endpoint you should pass a customer ID to enable a cookie based match. Partners sending data with a `p_id` **must** set the `user_identifier_type` to `TALIST_PARTNER_USER_ID` or `TAWEB_PARTNER_USER_ID`.
All other steps will remain the same as those listed in the [Real-Time Audience API Integration Guide](/x-ads-api/audiences)
### Custom Audiences User Data
This document outlines the format for \[Custom Audience]/x-ads-api/audiences user data.
**Data normalization**
**Device IDs**:
* IDFA - lower-cased with dashes; ex: `4b61639e-47cc-4056-a16a-c8217e029462`
* AdID - original format on device is required, not capitalized with dashes; ex: `2f5f5391-3e45-4d02-b645-4575a08f86e`
* Android id - original format on device is required, not capitalized without dashes or spaces; ex: `af3802a465767e36`
**Email Addresses**:
* lowercase, remove leading and trailing spaces; ex: `support@x.com`
**X Usernames**:
* no @, lowercased and leading and trailing spaces trimmed; ex: `jack`
**X User IDs**:
* Standard integer; ex: `143567`
**Data hashing**
The data for each line must be hashed using `SHA256`, without a salt. Additionally, the final output hash must be in lower case. E.g., 49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d and \*\*not \*\*49E0BE2AECCFB51A8DEE4C945C8A70A9AC500CF6F5CB08112575F74DB9B1470D
```
# hasing user @AdsAPI using python
import hashlib
hashlib.sha256("adsapi".encode()).hexdigest()
#output
49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d
```
Additional code samples for hashing can be found at [github.com/xdevplatform/ads-platform-tools](https://github.com/xdevplatform/ads-platform-tools).
### Custom Audiences: Web
*required* | Specifies the granularity of the data returned for the time range denoted by `start_time` and `end_time`. For instance, when set to `HOUR`, you will be presented with a datapoint for each hour between `start_time` and `end_time`. request.
Type: enum
Possible values: `DAY`, `HOUR` | | keywords
*required* | A comma-separated string of keywords to narrow search by. All keywords are OR'ed with one another.
**Note**: A maximum of 10 keywords (`keywords` and `negative_keywords` combined) may be used.
Type: string
Example: `developers` | | start\_time
*required* | Scopes the retrieved data to data collected in the window of time between `start_time` and `end_time`. Expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
Type: string
Example: `2017-07-10T00:00:00Z` | | end\_time
*optional* | Scopes the retrieved data to data collected in the window of time between `start_time` and `end_time`. Expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
**Note**: Defaults to the current time.
Type: string
Example: `2017-07-11T00:00:00Z` | | location
*optional* | A targeting value you would get from the [GET targeting\_criteria/locations](/x-ads-api/campaign-management#get-targeting-criteria-locations) endpoint to narrow results in terms of where the user of the account is located. Note that at present only country level locations are supported.
Type: string
Example: `0ce8b9a7b2742f7e` | | negative\_keywords
*optional* | A comma-separated string of keywords to exclude. All negative keywords are OR'ed with one another.
**Note**: A maximum of 10 keywords (`keywords` and `negative_keywords` combined) may be used.
Type: string
Example: `rain` | **Example Request[](#example-request "Permalink to this headline")** ```json theme={null} GET https://ads-api.x.com/12/insights/keywords/search?end_time=2018-02-02&granularity=DAY&keywords=developers&start_time=2018-02-01 ``` **Example Response[](#example-response "Permalink to this headline")**\* ``` { "request": { "params": { "start_time": "2018-02-01T00:00:00Z", "end_time": "2018-02-02T00:00:00Z", "granularity": "DAY", "keywords": [ "developers" ] } }, "data": { "related_keywords": [ "dev", "developer", "coders", "mysql", "devs", "#technology", "#developers", "security", "programmers", "#tech", "javascript", "#iot", "#bigdata", "cloud", "devops", "php", "developer", "programmer", "engineer", "big data", "agile", "app", "programming", "ios", "maker", "startups", "developer's", "java", "#devops", "startup" ], "tweet_volume": [ 15707 ] } } ``` ### Tailored Audience Permissions #### GET accounts/:account\_id/tailored\_audiences/:tailored\_audience\_id/permissions[](#get-accounts-account-id-tailored-audiences-tailored-audience-id-permissions "Permalink to this headline") Retrieve details for some or all permissions associated with the specified tailored audience. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :---------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` | | tailored\_audience\_id
*required* | A reference to the tailored audience you are operating with in the request.
Type: string
Example: `1nmth` | | 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](/x-ads-api/introduction) for more information.
Type: string
Example: `8x7v00oow` | | granted\_account\_ids
*optional* | Scope the response to just the desired accounts by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
Type: string
Example: `18ce54aymz3` | | sort\_by
*optional* | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/introduction) for more information.
Type: string
Example: `created_at-asc` | | tailored\_audience\_permission\_ids
*optional* | Scope the response to just the desired tailored audience permissions by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
Type: string
Example: `ri` | | 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[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/1nmth/permissions` **Example Response[](#example-response "Permalink to this headline")** ``` { "request": { "params": { "account_id": "18ce54d4x5t", "tailored_audience_id": "1nmth" } }, "next_cursor": null, "data": [ { "tailored_audience_id": "1nmth", "permission_level": "READ_ONLY", "id": "ri", "created_at": "2017-06-08T23:17:59Z", "granted_account_id": "18ce54aymz3", "updated_at": "2017-06-08T23:17:59Z", "deleted": false } ] } ``` #### POST accounts/:account\_id/tailored\_audiences/:tailored\_audience\_id/permissions[](#post-accounts-account-id-tailored-audiences-tailored-audience-id-permissions "Permalink to this headline") Create a new permission object allowing the specified audience to be shared with a given account. **Note**: Creating or modifying permissions for a tailored audience requires that the audience be owned by the account attempting to modify permissions. You can check the ownership of a tailored audience by looking at the `is_owner` response attribute in the response for a given audience. **Note**: Audiences can only be shared between ads accounts under the same business or if the ads account that owns the audience has the `SHARE_AUDIENCE_OUTSIDE_BUSINESS` account feature. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :--------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` | | granted\_account\_id
*required* | The account you wish to grant the tailored audience permissions for.
Type: string
Example: `18ce54aymz3` | | permission\_level
*required* | The type of access to the tailored audience that the `granted_account_id` should have.
Type: enum
Possible values: `READ_ONLY`, `READ_WRITE` | | tailored\_audience\_id
*required* | A reference to the tailored audience you are operating with in the request.
Type: string
Example: `2906h` | **Example Request[](#example-request "Permalink to this headline")** `POST https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/2906h/permissions?granted_account_id=18ce54aymz3&permission_level=READ_ONLY` **Example Response[](#example-response "Permalink to this headline")** ``` { "request": { "params": { "account_id": "18ce54d4x5t", "granted_account_id": "18ce54aymz3", "permission_level": "READ_ONLY", "tailored_audience_id": "2906h" } }, "data": { "tailored_audience_id": "2906h", "permission_level": "READ_ONLY", "id": "14m", "created_at": "2017-09-12T23:49:34Z", "granted_account_id": "18ce54aymz3", "updated_at": "2017-09-12T23:49:34Z", "deleted": false } } ``` #### DELETE accounts/:account\_id/tailored\_audiences/:tailored\_audience\_id/permissions/:tailored\_audience\_permission\_id[](#delete-accounts-account-id-tailored-audiences-tailored-audience-id-permissions-tailored-audience-permission-id "Permalink to this headline") Revoke the specified Tailored Audience sharing permission. **Note**: Creating or modifying permissions for a tailored audience requires that the audience be owned by the account attempting to modify permissions. You can check the ownership of a tailored audience by looking at the `is_owner` response attribute in the response for a given audience. When revoked, we guarantee that the granted account (`granted_account_id`) will not be able to target the audience in future campaigns. Existing campaigns will continue to run with the shared audiences; campaigns do not stop and the audience does not get removed from the campaign. It is not possible to copy this campaign after the audience sharing permission has been revoked. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions/:tailored_audience_permission_id` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :--------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` | | tailored\_audience\_id
*required* | A reference to the tailored audience you are operating with in the request.
Type: string
Example: `1nmth` | | tailored\_audience\_permission\_id
*required* | A reference to the tailored audience permission you are operating with in the request.
Type: string
Example: `ri` | **Example Request[](#example-request "Permalink to this headline")** `DELETE https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/1nmth/permissions/ri` **Example Response[](#example-response "Permalink to this headline")** ``` { "request": { "params": { "account_id": "18ce54d4x5t", "tailored_audience_permission_id": "ri", "tailored_audience_id": "1nmth" } }, "data": { "tailored_audience_id": "1nmth", "permission_level": "READ_ONLY", "id": "ri", "created_at": "2017-06-08T23:17:59Z", "granted_account_id": "18ce54aymz3", "updated_at": "2017-08-30T18:29:35Z", "deleted": true } } ``` ### Targeted Audiences #### GET accounts/:account\_id/custom\_audiences/:custom\_audience\_id/targeted[](#get-accounts-account-id-custom-audiences-custom-audience-id-targeted "Permalink to this headline") Retrieve a list of active or all line items and campaigns that target a given `custom_audience_id` | Name | Description | | :------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` | | custom\_audience\_id
*required* | A reference to the custom audience you are operating with in the request.
Type: string
Example: `2906h` | | with\_active
*optional* | When `false`, includes line items that have `servable=false` status
Type: boolean
Default: `true`
Possible values: `true`, `false` | | cursor
*optional* | Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/introduction) for more information.
Type: string
Example: `8x7v00oow` | **Example Request[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h/targeted` **Example Response[](#example-response "Permalink to this headline")** ``` { "request": { "params": { "account_id": "18ce54d4x5t", "custom_audience_id": "2906h", } }, "next_cursor": null, "data": [ { "campaign_id": "59hod", "campaign_name": "test-campaign", "line_items": [ { "id": "5gzog", "name": "test-line-item", "servable": true } ] }, { "campaign_id": "arja7", "campaign_name": "Untitled campaign", "line_items": [ { "id": "bjw1q", "name": null, "servable": true } ] } ] } ``` ### Custom Audiences Users #### POST accounts/:account\_id/custom\_audiences/:custom\_audience\_id/users[](#post-accounts-account-id-custom-audiences-custom-audience-id-users "Permalink to this headline") This endpoint will allow partners to add, update and remove users from a given `custom_audience_id`. The endpoint will also accept multiple user identifier types per user as well. All data being provided in the `users` field of the request **except** `partner_user_id` must be hashed using `SHA256` and [normalized](/x-ads-api/audiences#twitter-user-id-normalization). **Batch Requests** * The current maximum batch size is `2500` **for this endpoint**. The batch size is determined by the number of operations (`Update`/`Delete`) per request. For example, over 2500 operation objects (`{"operation_type": "Update/Delete", [..] }`) in one array result in an error. * The max request POST body size this endpoint can accept is `5,000,000` bytes. * The rate limits for this endpoint are 1500 per 1 minute window * 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** The response returned by the Ads API contains two fields, a `success_count` and a `total_count`. These values must always be equal, and they are a count of the number of records in the request that have been processed by the backend. A situation where the number of records sent in the request body is **not** equal the `success_count` and `total_count` should be treated as an error condition, requiring a retry. **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 parameters) are show in the response under the `operation_errors` object. * The index of the error in the `operation_errors` refers to the index in the input item, with the corresponding error message #### Resource URL[](#resource-url "Permalink to this headline") `https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/users` #### Parameters[](#parameters "Permalink to this headline") | Name | Description | | :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | operation\_type
*required* | The per `users` group operation type being performed.
Type: enum
Possible values: `Update`, `Delete` | | params
*required* | A JSON object containing the `users` array, the `effective_at` and `expires_at` timestamps.
Type: JSON | | users
*required* | An array of JSON objects containing all params for an individual user.
Type: JSON | | effective\_at
*optional* | The UTC time at which the custom audience association(s) should take effect. Expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). Defaults to the current date and time.
Type: string
Example: `2017-07-05T07:00:00Z` | | expires\_at
*optional* | The UTC time at which the custom audience association(s) should expire. The specified time must be later than the value of `effective_at`. Expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). Defaults to 13 months from the request timestamp.
Type: string
Example: `2017-07-05T07:00:00Z` | Given the mutil-key approach to the `users` object, each element of this object is documented below: | Name | Description | | :---------------------------------- | :--------------------------------------------------------------------- | | email
*optional* | Email address(es) for the user.
Type: Array\[String] | | device\_id
*optional* | IDFA/AdID/Android ID
Type: Array\[String] | | handle
*optional* | The @handle(s) belonging to the user
Type: Array\[String] | | twitter\_id
*optional* | The X ID belonging to the user
Type: Array\[String] | | phone\_number
*optional* | Phone number(s) for the user
Type: Array\[String] | | partner\_user\_id
*optional* | The user's ID in the partners' system.
Type: Array\[String] | #### Example Request[](#example-request "Permalink to this headline") `POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/users` ``` [ { "operation_type": "Update", "params": { "effective_at": "2018-05-15T00:00:00Z", "expires_at": "2019-01-01T07:00:00Z", "users": [ { "email": [ "4798b8bbdcf6f2a52e527f46a3d7a7c9aefb541afda03af79c74809ecc6376f3" ], "handle": [ "7352f353c460e74c7ae226952d04f8aa307b12329c5512ec8cb6f1a0f8f9b2cb", "49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d" ] }, { "email": [ "5bf13d5ad4200407c5bc8b9bb578e425d05ef936fd488e3799a9d0806669223c" ], "twitter_id": [ "34d56c7159a7eea941f359653029410f813f65a1d2d13ecc5ccbdd5a8cb755cf", "00e7b76c9739dec57f4c4a20ec021a20ffcf26bd00f519b17ea00f0ed6048f85" ] } ] } }, { "operation_type": "Delete", "params": { "effective_at": "2018-05-15T00:00:00Z", "expires_at": "2019-01-01T07:00:00Z", "users": [ { "device_id": [ "8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92" ], "email": [ "4798b8bbdcf6f2a52e527f46a3d7a7c9aefb541afda03af79c74809ecc6376f3" ], "handle": [ "461222f5dd690a20651c3d19848015cb0369db3f8e937571ffb775de70750847" ], "twitter_id": [ "c623c7e163984493b46c547088542e95d0aaa529bc52bbecce3ff91eb6b7843b" ] }, { "email": [ "5bf13d5ad4200407c5bc8b9bb578e425d05ef936fd488e3799a9d0806669223c" ], "twitter_id": [ "858cdc7f313f84a3f3c48e9a6323307c1ef1bb7439b8e3623e140454b0fd8fa5", "bb074e154657b91d99bd1bb3757409149670e8ae7a0fe9136fae29a26a7881c8" ] } ] } } ] ``` #### Example Response[](#example-response "Permalink to this headline") ``` { "request": { "params": { "account_id": "18ce54d4x5t", "custom_audience_id": "1nmth" } }, "data": { "success_count": 4, "total_count": 4 } } ``` ### Custom Audience Permissions #### GET accounts/:account\_id/custom\_audiences/:custom\_audience\_id/permissions[](#get-accounts-account-id-custom-audiences-custom-audience-id-permissions "Permalink to this headline") Retrieve details for some or all permissions associated with the specified custom audience. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :-------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` | | custom\_audience\_id
*required* | A reference to the custom audience you are operating with in the request.
Type: string
Example: `1nmth` | | 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](/x-ads-api/introduction) for more information.
Type: string
Example: `8x7v00oow` | | granted\_account\_ids
*optional* | Scope the response to just the desired accounts by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
Type: string
Example: `18ce54aymz3` | | sort\_by
*optional* | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/sorting) for more information.
Type: string
Example: `created_at-asc` | | custom\_audience\_permission\_ids
*optional* | Scope the response to just the desired custom audience permissions by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
Type: string
Example: `ri` | | 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[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/permissions` **Example Response[](#example-response "Permalink to this headline")** ``` { "request": { "params": { "account_id": "18ce54d4x5t", "custom_audience_id": "1nmth" } }, "next_cursor": null, "data": [ { "custom_audience_id": "1nmth", "permission_level": "READ_ONLY", "id": "ri", "created_at": "2017-06-08T23:17:59Z", "granted_account_id": "18ce54aymz3", "updated_at": "2017-06-08T23:17:59Z", "deleted": false } ] } ``` #### POST accounts/:account\_id/custom\_audiences/:custom\_audience\_id/permissions[](#post-accounts-account-id-custom-audiences-custom-audience-id-permissions "Permalink to this headline") Create a new permission object allowing the specified audience to be shared with a given account. **Note**: Creating or modifying permissions for a custom audience requires that the audience be owned by the account attempting to modify permissions. You can check the ownership of a custom audience by looking at the `is_owner` response attribute in the response for a given audience. **Note**: Audiences can only be shared between ads accounts under the same business or if the ads account that owns the audience has the `SHARE_AUDIENCE_OUTSIDE_BUSINESS` account feature. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` | | granted\_account\_id
*required* | The account you wish to grant the custom audience permissions for.
Type: string
Example: `18ce54aymz3` | | permission\_level
*required* | The type of access to the custom audience that the `granted_account_id` should have.
Type: enum
Possible values: `READ_ONLY`, `READ_WRITE` | | custom\_audience\_id
*required* | A reference to the custom audience you are operating with in the request.
Type: string
Example: `2906h` | **Example Request[](#example-request "Permalink to this headline")** ``` POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h/permissions?granted_account_id=18ce54aymz3&permission_level=READ_ONLY ``` **Example Response[](#example-response "Permalink to this headline")** ``` { "request": { "params": { "account_id": "18ce54d4x5t", "granted_account_id": "18ce54aymz3", "permission_level": "READ_ONLY", "custom_audience_id": "2906h" } }, "data": { "custom_audience_id": "2906h", "permission_level": "READ_ONLY", "id": "14m", "created_at": "2017-09-12T23:49:34Z", "granted_account_id": "18ce54aymz3", "updated_at": "2017-09-12T23:49:34Z", "deleted": false } } ``` #### DELETE accounts/:account\_id/custom\_audiences/:custom\_audience\_id/permissions/:custom\_audience\_permission\_id[](#delete-accounts-account-id-custom-audiences-custom-audience-id-permissions-custom-audience-permission-id "Permalink to this headline") Revoke the specified Custom Audience sharing permission. **Note**: Creating or modifying permissions for a custom audience requires that the audience be owned by the account attempting to modify permissions. You can check the ownership of a custom audience by looking at the `is_owner` response attribute in the response for a given audience. When revoked, we guarantee that the granted account (`granted_account_id`) will not be able to target the audience in future campaigns. Existing campaigns will continue to run with the shared audiences; campaigns do not stop and the audience does not get removed from the campaign. It is not possible to copy this campaign after the audience sharing permission has been revoked. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_id` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` | | custom\_audience\_id
*required* | A reference to the custom audience you are operating with in the request.
Type: string
Example: `1nmth` | | custom\_audience\_permission\_id
*required* | A reference to the custom audience permission you are operating with in the request.
Type: string
Example: `ri` | **Example Request[](#example-request "Permalink to this headline")** `DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/permissions/ri` **Example Response[](#example-response "Permalink to this headline")** ``` { "request": { "params": { "account_id": "18ce54d4x5t", "custom_audience_permission_id": "ri", "custom_audience_id": "1nmth" } }, "data": { "custom_audience_id": "1nmth", "permission_level": "READ_ONLY", "id": "ri", "created_at": "2017-06-08T23:17:59Z", "granted_account_id": "18ce54aymz3", "updated_at": "2017-08-30T18:29:35Z", "deleted": true } } ``` ### Custom Audiences #### GET accounts/:account\_id/custom\_audiences[](#get-accounts-account-id-custom-audiences "Permalink to this headline") Retrieve details for some or all Custom Audiences associated with the current account. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/custom_audiences` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :-------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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](/x-ads-api/introduction) for more information.
Type: string
Example: `8x7v00oow` | | permission\_scope
*optional* | Allows filtering the response to lists you own or lists that have been shared with you. By default, without specifying this parameter you will only see audiences you own.
Type: enum
Default: `OWNER`
Possible values: `OWNER`, `SHARED` | | 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](/x-ads-api/fundamentals/sorting) for more information.
Type: string
Example: `created_at-asc` | | custom\_audience\_ids
*optional* | Scope the response to just the desired custom audiences by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
Type: string
Example: `1nmth` | | 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[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences?custom_audience_ids=1nmth` **Example Response[](#example-response "Permalink to this headline")** ``` { "request": { "params": { "custom_audience_ids": [ "1nmth" ], "account_id": "18ce54d4x5t" } }, "next_cursor": null, "data": [ { "targetable": true, "name": "twurl-using-subshell-for-file", "targetable_types": [ "CRM", "EXCLUDED_CRM" ], "audience_type": "CRM", "description": null, "permission_level": "READ_WRITE", "owner_account_id": "18ce54d4x5t", "id": "1nmth", "reasons_not_targetable": [], "created_at": "2017-01-08T08:19:58Z", "updated_at": "2017-01-08T16:21:13Z", "partner_source": "OTHER", "deleted": false, "audience_size": 1470 } ] } ``` #### GET accounts/:account\_id/custom\_audiences/:custom\_audience\_id[](#get-accounts-account-id-custom-audiences-custom-audience-id "Permalink to this headline") Retrieve specific Custom Audiences associated with the current account. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` | | custom\_audience\_id
*required* | A reference to the custom audience you are operating with in the request.
Type: string
Example: `2906h` | | with\_deleted
*optional* | Include deleted results in your request.
Type: boolean
Default: `false`
Possible values: `true`, `false` | **Example Request[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h` **Example Response[](#example-response "Permalink to this headline")** ``` { "request": { "params": { "custom_audience_id": "2906h", "account_id": "18ce54d4x5t" } }, "data": { "targetable": false, "name": "developers", "targetable_types": [ "CRM", "EXCLUDED_CRM" ], "audience_type": "CRM", "description": null, "permission_level": "READ_WRITE", "owner_account_id": "18ce54d4x5t", "id": "2906h", "reasons_not_targetable": [], "created_at": "2017-08-22T23:34:26Z", "updated_at": "2017-08-22T23:34:26Z", "partner_source": "OTHER", "deleted": false, "audience_size": 140321 } } ``` #### POST accounts/:account\_id/custom\_audiences[](#post-accounts-account-id-custom-audiences "Permalink to this headline") Create a new placeholder Custom Audience associated with the current account. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/custom_audiences` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :---------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` | | name
*required* | The display name for this audience. Unique name value must be used. Failure to do so will result in an error.
Type: string
Example: `ads api users` | | description
*optional* | A description for this audience.
Type: string
Example: `Collection of all users of the Ads API` | **Example Request[](#example-request "Permalink to this headline")** `POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences?name=developers` **Example Response[](#example-response "Permalink to this headline")** ``` { "data": { "targetable": false, "name": "developers", "targetable_types": [ "CRM", "EXCLUDED_CRM" ], "audience_type": "CRM", "description": null, "permission_level": "READ_WRITE", "owner_account_id": "18ce54d4x5t", "id": "2906h", "reasons_not_targetable": [ "PROCESSING", "TOO_SMALL" ], "created_at": "2017-08-22T23:34:26Z", "updated_at": "2017-08-22T23:34:26Z", "partner_source": "OTHER", "deleted": false, "audience_size": null }, "request": { "params": { "account_id": "18ce54d4x5t", "name": "developers" } } } ``` #### PUT accounts/:account\_id/custom\_audiences/:custom\_audience\_id[](#put-accounts-account-id-custom-audiences-custom-audience-id "Permalink to this headline") Update the specfic Custom Audience associated with the current account. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` | | custom\_audience\_id
*required* | A reference to the Custom Audience you are operating with in the request
Type: string
Example: `2906h` | | name
*optional* | The display name for this audience. Unique name value must be used. Failure to do so will result in an error.
Type: string
Example: `ads api users` | | description
*optional* | A description for this audience.
Type: string
Example: `Collection of all users of the Ads API` | **Example Request[](#example-request "Permalink to this headline")** `PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h?name=developers_changed` **Example Response[](#example-response "Permalink to this headline")** ``` { "data": { "targetable": false, "name": "developers_changed", "targetable_types": [ "CRM", "EXCLUDED_CRM" ], "audience_type": "CRM", "description": null, "permission_level": "READ_WRITE", "is_owner": true, "id": "2906h", "reasons_not_targetable": [ "PROCESSING", "TOO_SMALL" ], "created_at": "2017-08-22T23:34:26Z", "updated_at": "2017-08-22T23:34:26Z", "partner_source": "OTHER", "deleted": false, "audience_size": null }, "request": { "params": { "account_id": "18ce54d4x5t", "name": "developers_changed" } } } ``` #### POST batch/accounts/:account\_id/custom\_audiences[](#post-batch-accounts-account-id-custom-audiences "Permalink to this headline") Allows for batch creation of Custom Audiences. See the [Custom Audiences Overview](/x-ads-api/audiences) page for information on audiences. **Note:** This batch endpoint is currently in **closed beta** and available to select advertisers. During this beta period, only Flexible Audiences based on mobile custom audiences can be created. **Batch Requests** * The current maximum batch size is 10. * 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 parameter) are shown in the response under the `operation_errors` object. **Flexible Audiences** * Flexible Audiences are immutable once created. * Custom Audiences are passed in a tree structure with boolean logic combinations to create Flexible Audiences * A maximum of 10 Custom Audiences leaf nodes can be used to create a Flexible Audience. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/batch/accounts/:account_id/custom_audiences` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :----------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` | | audience\_type
*required* | The type of audience to create.
Type: enum
Possible values: `FLEXIBLE`, `MOBILE_AUDIENCE` | | child\_segments
*required* | An array containing objects which define the subset of a Custom Audience's members that you would like to target. Each object should contain a `custom_audience_id`, `frequency`, `frequency_comparator`, `lookback_window`, `negate`, and, in some cases, additional `child_segments`.
Type: array | | name
*required* | The display name for the audience. Unique name value must be used. Failure to do so will result in an error.
Type: string
Example: `my_flexible_audience_name` | | operation\_type
*required* | The per item operation type being performed.
Type: enum
Possible values: `Create`, `Update`, `Delete` | | boolean\_operator
*sometimes required* | The logical relationship between the child segments in its parent (containing) object. Required if child\_segments is non-empty for the parent object.
Type: enum
Possible values: `AND`, `OR` | | lookback\_window
*sometimes required* | An integer value specifying the range of days within which the user has taken the specific action and qualified for the given custom audience.
Type: int
Possible values: `1`, `7`, `14`, `30` | | segments
*sometimes required* | An object containing a `boolean_operator` and `child_segments` which define the subset of a Custom Audience's members that you would like to target.
Type: object | | custom\_audience\_id
*sometimes required* | The id of the custom audience to use as a child segment.
Type: string
Example: `tyfo` | | frequency
*optional* | An integer value specifying the frequency within the lookback window that the user has taken the specific action and qualified for the given custom audience.
Type: int
Default value: `1` | | frequency\_comparator
*optional* | The comparator to the `frequency` passed in the request.
**Note**: In the values below, `GTE` refers to greater than or equal, `LT` to less than, and so on.
Type: string
Possible values: `NUM_GTE`, `NUM_GT`, `NUM_EQ`, `NUM_LTE`, `NUM_LT` Default value: `NUM_GTE` | | negate
*optional* | Negates the segment and thus is excluded in the combination.
Type: boolean
Default value: `true`
Possible values: `true`, `false` | **Example Request[](#example-request "Permalink to this headline")** `POST https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/custom_audiences` ``` [ { "operation_type":"Create", "params":{ "name":"my_flexible_audience_name", "audience_type":"FLEXIBLE", "segments":{ "boolean_operator":"AND", "child_segments":[ { "custom_audience_id":"TYIF", "frequency":1, "frequency_comparator":"NUM_GT", "lookback_window":30, "negate":true, "child_segments":[ ] }, { "boolean_operator":"OR", "child_segments":[ { "custom_audience_id":"TXR1", "lookback_window":30, "child_segments":[ ] }, { "custom_audience_id":"TYFO", "frequency":1, "frequency_comparator":"NUM_GT", "lookback_window":30, "negate":true, "child_segments":[ ] } ] } ] } } } ] ``` **Example Response[](#example-response "Permalink to this headline")** ``` { "data": { "targetable": false, "name": "my_flexible_audience_name", "targetable_types": [ "FLEXIBLE", "EXCLUDED_FLEXIBLE" ], "audience_type": "FLEXIBLE", "id": "13ld7", "reasons_not_targetable": [ "PROCESSING", "TOO_SMALL" ], "metadata": [ { "custom_audience_id": "13ld7", "account_id": "qsx3w2", "name": "my_flexible_audience_name", "audience_source": "FLEXIBLE_AUDIENCE", "upload_status": "UPLOADED", "segments": { "boolean_operator": "AND", "frequency": 1, "frequency_comparator": "NUM_GTE", "negate": false, "child_segments": [ { "custom_audience_id": "tyif", "lookback_window": 30, "frequency": 1, "frequency_comparator": "NUM_GT", "negate": true, "child_segments": [ ] }, { "boolean_operator": "OR", "frequency": 1, "frequency_comparator": "NUM_GTE", "negate": false, "child_segments": [ { "custom_audience_id": "txr1", "lookback_window": 30, "frequency": 1, "frequency_comparator": "NUM_GTE", "negate": false, "child_segments": [ ] }, { "custom_audience_id": "tyfo", "lookback_window": 30, "frequency": 1, "frequency_comparator": "NUM_GT", "negate": true, "child_segments": [ ] } ] } ] } } ], "created_at": "2015-11-10T21:26:43Z", "updated_at": "2015-11-11T01:11:47Z", "partner_source": "OTHER", "deleted": false, "audience_size": null }, "request": [ { "params": { "name": "my_flexible_audience_name", "audience_type": "FLEXIBLE", "segments": { "boolean_operator": "AND", "child_segments": [ { "custom_audience_id": "TYIF", "lookback_window": 30, "frequency": 1, "frequency_comparator": "NUM_GT", "negate": true, "child_segments": [ ] }, { "boolean_operator": "OR", "child_segments": [ { "custom_audience_id": "TXR1", "lookback_window": 30, "child_segments": [ ] }, { "custom_audience_id": "TYFO", "lookback_window": 30, "frequency": 1, "frequency_comparator": "NUM_GT", "negate": true, "child_segments": [ ] } ] } ] }, "account_id": "qsx3w2" }, "operation_type": "Create" } ] } ``` #### DELETE accounts/:account\_id/custom\_audiences/:custom\_audience\_id[](#delete-accounts-account-id-custom-audiences-custom-audience-id "Permalink to this headline") Delete the specified Custom Audience belonging to the current account. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` | | custom\_audience\_id
*required* | A reference to the custom audience you are operating with in the request.
Type: string
Example: `2906h` | **Example Request[](#example-request "Permalink to this headline")** `DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h` **Example Response[](#example-response "Permalink to this headline")** ``` { "data": { "targetable": false, "name": "developers", "targetable_types": [ "CRM", "EXCLUDED_CRM" ], "audience_type": "CRM", "description": null, "permission_level": "READ_WRITE", "owner_account_id": "18ce54d4x5t", "id": "2906h", "reasons_not_targetable": [ "TOO_SMALL" ], "created_at": "2017-08-22T23:34:26Z", "updated_at": "2017-08-30T18:09:00Z", "partner_source": "OTHER", "deleted": true, "audience_size": null }, "request": { "params": { "custom_audience_id": "2906h", "account_id": "18ce54d4x5t" } } } ``` ### Do Not Reach Lists #### GET accounts/:account\_id/do\_not\_reach\_lists[](#get-accounts-account-id-do-not-reach-lists "Permalink to this headline") Retrieve details for some or all Do Not Reach List associated with the current account. **Note**: An `account_id` can only have at most one Do Not Reach List **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists` **Example Response[](#example-response "Permalink to this headline")** ``` { "request": { "params": { "account_id": "18ce54bgxky" } }, "next_cursor": null, "data": [ { "targetable": false, "name": "Do Not Reach List", "description": "test DNRL", "id": "4kzrq", "reasons_not_targetable": [ "TOO_SMALL" ], "created_at": "2021-10-28T22:09:29Z", "list_size": null, "updated_at": "2021-11-04T03:33:06Z", "deleted": false } ] } ``` #### POST accounts/:account\_id/do\_not\_reach\_lists[](#post-accounts-account-id-do-not-reach-lists "Permalink to this headline") Create a new Do Not Reach List associated with the current account. **Note**: An `account_id` can only have at most one Do Not Reach List **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :---------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` | | description
*optional* | A description for this audience.
Type: string
Example: `A list of users to exclude` | **Example Request[](#example-request "Permalink to this headline")** `POST https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists?description=A list of users to exclude` **Example Response[](#example-response "Permalink to this headline")** ``` { "request": { "params": { "description": "A list of users to exclude", "account_id": "18ce54bgxky" } }, "data": { "targetable": false, "name": "Do Not Reach List", "description": "A list of users to exclude", "id": "4ofrq", "reasons_not_targetable": [ "PROCESSING", "TOO_SMALL" ], "created_at": "2022-02-08T23:02:48Z", "list_size": null, "updated_at": "2022-02-08T23:02:48Z", "deleted": false } } ``` #### POST batch/accounts/:account\_id/do\_not\_reach\_lists/:do\_not\_reach\_list\_id/users[](#post-batch-accounts-account-id-do-not-reach-lists-do-not-reach-list-id-users "Permalink to this headline") This endpoint allows users to be added, updated and removed from a given `do_not_reach_list_id`. This endpoint only accepts emails as the valid user identifier type. All data being provided in the `emails` field of the request must be hashed using `SHA256` and [normalized](/x-ads-api/audiences#e-mail-normalization). **Notes** * An `account_id` can only have at most one Do Not Reach List * Users added to this list **must** have an `expires_at` timestamp set to less than 13 months from the current timestamp * Do Not Reach List API does not accept an `effective_at` timestamp and defaults to the current timestamp * Do Not Reach List does not remove users from any or all custom audiences in the account but acts as exclusion targeting for all campaigns served for the account **Batch Requests** * The current maximum batch size is `2500` **for this endpoint**. The batch size is determined by the number of operations (`Update`/`Delete`) per request. For example, over 2500 operation objects (`{"operation_type": "Update/Delete", [..] }`) in one array result in an error. * The max request POST body size this endpoint can accept is `5,000,000` bytes. * The rate limits for this endpoint are 1500 per 1 minute window * 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** The response returned by the Ads API contains two fields, a `success_count` and a `total_count`. These values must always be equal, and they are a count of the number of records in the request that have been processed by the backend. A situation where the number of records sent in the request body is **not** equal the `success_count` and `total_count` should be treated as an error condition, requiring a retry. **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 parameters) are show in the response under the `operation_errors` object. * The index of the error in the `operation_errors` refers to the index in the input item, with the corresponding error message **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :----------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` | | do\_not\_reach\_list\_id
*required* | A reference to the Do Not Reach List you are operating with in the request
Type: string
Example: `2906h` | | operation\_type
*required* | The per `users` group operation type being performed.
Type: enum
Possible values: `Update`, `Delete` | | params
*required* | A JSON object containing the `emails` array and `expires_at` timestamp.
Type: JSON | | users
*required* | An array of JSON objects containing all params for an individual user.
Type: JSON | | expires\_at
*optional* | The UTC time at which the user association(s) should expire. The specified time must be later than the value of the current timestamp. Expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). Defaults to 13 months from current timestamp.
Type: string
Example: `2017-07-05T07:00:00Z` | Given the mutil-key approach to the `users` object, each element of this object is documented below: | Name | Description | | :------------------------------ | :-------------------------------------------------------------- | | email
*optional* | Email address(es) for the user.
Type: Array\[String] | | phone\_number
*optional* | Phone number(s) for the user
Type: Array\[String] | **Example Request[](#example-request "Permalink to this headline")** ``` `POST https://ads-api.x.com/12/batch/accounts/18ce54bgxky/do_not_reach_lists/4kzro/users` [ { "operation_type": "Update", "params": { "expires_at": "2023-01-22T00:00:00Z", "users": [ { "email": [ "FEAD76F6ADF99FFFB997AA4E3C8AD38FF531BC4C956DBD03CD0163F744D8AABC" ], "phone_number": [ "CCABF1B62A202E0FE28BC6C014983C89A65451DD4482BD66A0ADB65366F38A9A" ] }, { "email": [ "FEAD76F6ADF99FFFB997AA4E3C8AD38FF531BC4C956DBD03CD0163F744D8AABA" ], "phone_number": [ "CCABF1B62A202E0FE28BC6C014983C89A65451DD4482BD66A0ADB65366F38A9E" ] } ] } } ] ``` **Example Response[](#example-response "Permalink to this headline")** ``` { "data": [ { "success_count": 2, "total_count": 2 } ], "request": [ { "params": { "do_not_reach_list_id": "4ofrq", "expires_at": "2023-01-22T00:00:00Z", "account_id": "18ce54bgxky" }, "operation_type": "Update" } ] } ``` #### DELETE accounts/:account\_id/do\_not\_reach\_lists/:do\_not\_reach\_list\_id[](#delete-accounts-account-id-do-not-reach-lists-do-not-reach-list-id "Permalink to this headline") Delete the specified Do Not Reach List belonging to the current account. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id` **Parameters[](#parameters "Permalink to this headline")** None **Example Request[](#example-request "Permalink to this headline")** `DELETE https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists/4ofrp` **Example Response[](#example-response "Permalink to this headline")** ``` { "request": { "params": { "do_not_reach_list_id": "4ofrp", "account_id": "18ce54bgxky" } }, "data": { "targetable": false, "name": "Do Not Reach List", "description": null, "id": "4ofrp", "reasons_not_targetable": [ "PROCESSING", "TOO_SMALL" ], "created_at": "2022-02-08T23:02:07Z", "list_size": null, "updated_at": "2022-02-08T23:02:21Z", "deleted": true } } ``` # Campaign Management Source: https://docs.x.com/x-ads-api/campaign-management ## Advertiser API Programatically schedule campaigns and manage ads on X through this suite of APIs. ## What Can You Promote? ### [Promoted Ads](https://business.x.com/help/what-are-promoted-tweets) * 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](/x-api/posts/creation-of-a-post). * **“Promoted-only” Tweets,** created via [POST accounts/:account\_id/tweet](/x-ads-api/creatives#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](/x-ads-api/creatives). ### [Promoted Accounts](https://business.x.com/help/what-are-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](https://github.com/twitter/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/ ``` ```JSON theme={null} { "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](/x-ads-api/campaign-management#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 ``` ```JSON theme={null} { "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 ``` ```JSON theme={null} { "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 ``` ```JSON theme={null} { "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" ``` ```JSON theme={null} { "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 ``` ```JSON theme={null} { "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 ``` ```JSON theme={null} { "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" ``` ```JSON theme={null} { "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 objective | API objective | Media in Tweets | Pricing model | | :----------------- | :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------- | | App re-engagements | `APP_ENGAGEMENTS` | Image or video app download card required. | CPAC | | App installs | `APP_INSTALLS` | Image or video app download card required. | CPAC or CPI (set using `charge_by`) | | Reach | `REACH` | No restrictions. | CPM | | Followers | `FOLLOWERS` | Tweet not required, but recommended. There are no media restrictions on Tweets for Followers campaigns, though we recommend text-only Tweets. [More information](https://business.x.com/en/help/campaign-setup/create-a-followers-campaign.html#serve) | CPF | | Engagements | `ENGAGEMENTS` | No restrictions. | CPE | | Video Views | `VIDEO_VIEWS` | Video conversation card, video, or GIF required. | CPV or cost per 3s/100% view | | Pre-roll views | `PREROLL_VIEWS` | Video required. | CPV or cost per 3s/100% view | | Website Clicks | `WEBSITE_CLICKS` | Website 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](/x-ads-api/campaign-management#get-accounts-account-id-funding-instruments) and [GET accounts/:account\_id/funding\_instruments/:funding\_instrument\_id](/x-ads-api/campaign-management#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 `type`, `description`, 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_at`, `updated_at`, `start_time`, and `end_time` represented by a string, formatted as “%Y-%m-%dT%l:%M:%S%z”. Boolean status: `paused`, `deleted`, and `cancelled` (true or false). Financial: `currency` ([ISO-4217](http://en.wikipedia.org/wiki/ISO_4217) format), `credit_limit_local_micro`, `credit_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). ```json theme={null} 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](/x-ads-api/introduction). ### 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](/x-ads-api/campaign-management#post-accounts-account-id-targeting-criteria) and [PUT accounts/:account\_id/targeting\_criteria](/x-ads-api/campaign-management#get-accounts-account-id-targeting-criteria) to update them. Use [GET accounts/:account\_id/line\_items](/x-ads-api/campaign-management#get-accounts-account-id-line-items) for a list of all line items and [GET accounts/:account\_id/line\_items/:line\_item\_id](/x-ads-api/campaign-management#get-accounts-account-id-line-items-line-item-id) to retrieve a specific line item. #### Targeting options by placement [Promoted Tweets](https://business.x.com/help/what-are-promoted-tweets) and [Promoted Accounts](https://business.x.com/help/what-are-promoted-accounts) products can be made available on a variety of placements. [Promoted Trends (PTr)](https://business.x.com/help/what-are-promoted-trends) are not available via the API. For possible placement combinations, refer to the [GET line\_items/placements](/x-ads-api/campaign-management#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](/x-ads-api/introduction) page. [Events](https://business.x.com/help/event-targeting): Specify an event for targeting. Only one event can be used for targeting (per line item). Use the [GET targeting\_criteria/events](/x-ads-api/campaign-management#get-targeting-criteria-events) endpoint to find events available for targeting. [Gender](https://business.x.com/help/geo-gender-and-language-targeting): Target males (1) or females (2). Leave null to target all. [Installed App Store Categories](https://business.x.com/help/installed-app-category-targeting): 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](/x-ads-api/campaign-management#get-targeting-criteria-app-store-categories). [Interests](https://business.x.com/help/interest-and-username-targeting): Target users by interest. Get the interests list from [GET targeting\_criteria/interests](/x-ads-api/campaign-management#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](/x-ads-api/campaign-management#get-accounts-account-id-promotable-users) to get a list of promotable users. [Similar to Followers Of](https://business.x.com/help/interest-and-username-targeting): Target people with the same interests as followers of specific users. You can use up to 100 [Users](/x-api/fundamentals/data-dictionary#user). [Locations](https://business.x.com/help/geo-gender-and-language-targeting): Specify up to 2,000 locations to target. Get list from [GET targeting\_criteria/locations](/x-ads-api/campaign-management#get-targeting-criteria-locations). There are additional requirements for ads that target certain countries. See [Country Targeting and Display Requirements](/x-ads-api/campaign-management#country-targeting-and-display-requirements) for more information. [Keywords](https://business.x.com/help/keyword-targeting): 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](https://business.x.com/help/geo-gender-and-language-targeting): Target users who understand specific languages. [Mobile Network Operator Targeting](https://business.x.com/help/device-carrier-and-new-mobile-user-targeting): Enables advertisers to target users based on mobile carrier, using the targeting type `NETWORK_OPERATOR` from [GET targeting\_criteria/network\_operators](/x-ads-api/campaign-management#get-targeting-criteria-network-operators). [New Mobile Device Targeting](https://business.x.com/help/device-carrier-and-new-mobile-user-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](/x-ads-api/campaign-management#get-targeting-criteria-platforms), [Platform Versions](/x-ads-api/campaign-management#get-targeting-criteria-platform-versions), [Devices](/x-ads-api/campaign-management#get-targeting-criteria-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](https://support.x.com/articles/20170766-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](/x-ads-api/campaign-management#get-targeting-criteria-tv-markets) and [GET targeting\_criteria/tv\_shows](/x-ads-api/campaign-management#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](https://business.x.com/en/help/campaign-setup/campaign-targeting/keyword-targeting.html) 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](https://x.github.io/twemoji/preview.html) 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](/x-ads-api/campaign-management#get-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” Types | Other Types | | Followers | Locations | | Tailored Audiences | Gender | | Interests | Languages | | Keywords | Devices and platforms | | TV | Age | 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 Audiences** ∪ **Keyword**] ### 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 (**Cars** ∪ **Tailored Audiences for CRM** ∪ **autocross**) ### 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](/x-ads-api/campaign-management#get-accounts-account-id-campaigns)). **Notes** * “Day” is respective to X [advertiser account](/x-ads-api/campaign-management#accounts) 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](https://business.x.com/en/help/troubleshooting/bidding-and-auctions-faqs.html). ### 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](https://devcommunity.x.com/t/ads-api-version-10/158787/1#changed-default-bid_strategy-values-9). As example: | | | | | :--------------------- | :---------------------------------------------------------------------------------------------- | :--------------------------------------------------------- | | **Campaign Objective** | **Legacy** | **Ads API v10+** | | App Installs | `bid_type`= `AUTO`
`bid_unit` = `APP_INSTALLS`
`charge_by` = `APP_CLICKS` | `goal` = `APP_INSTALLS`
`bid_strategy` = `AUTO` | | Website Clicks | `bid_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](https://support.x.com/groups/58-advertising/topics/249-advertiser-policies/articles/20171727-illegal-products-and-services) 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](https://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](/resources/fundamentals/developer-apps) that will be used for Ads API access.** You can view and edit your existing X apps via the [app dashboard](https://developer.x.com/content/developer-twitter/en/apps) 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](/resources/fundamentals/developer-portal). 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](https://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](http://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](https://ads.x.com/link\\_managed\\_account) The redirect URL will be called with the following parameters: | | | | | :------------------- | :---------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Name | Type | Description | | callback\_url | URL encoded string | user 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\_id | integer | X API client app id, used to identify the managing partner | | promotable\_user\_id | integer | X 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\_description | URL 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) | | timezone | String, in Area/Location format | This will be the timezone used to determine the day to which daily budgets apply, and in which charges will be aggregated | | currency | ISO 4217 Currency Code | Currency that will be used to enter bids, and in which charges will be billed | | country | ISO 3166-1 alpha 2 Country Code | Billing Country for the account | | signature | URL encoded, base64 encoded binary code, as explained below | signature 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](https://ads.x.com) are: | | | | | :---------------------- | :---------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Name | Type | Description | | status | string | **OK** 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\_id | URL encoded string | X ads account id of the linked account | | funding\_instrument\_id | URL encoded string | ID of the active partner managed funding instrument | | signature | URL encoded, base64 encoded binary code, as explained below | Base64 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](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](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](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](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](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](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](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](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](/resources/fundamentals/authentication#obtaining-access-tokens-using-3-legged-oauth-flow). ### 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](/x-ads-api/campaign-management#get-accounts-account-id-funding-instruments) 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](/x-ads-api/campaign-management#line-items) using the `placements` parameter. The possible values are: * `ALL_ON_TWITTER` * `PUBLISHER_NETWORK` * `TWITTER_PROFILE` * `TWITTER_SEARCH` * `TWITTER_TIMELINE` * `SPOTLIGHT` * `TREND` The line item’s `product_type` and `objective` determine which placements are allowed. The [GET line\_items/placements](/x-ads-api/campaign-management#line-item-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. | Objective | `ALL_ON_TWITTER` | `TWITTER_PROFILE` | `TWITTER_SEARCH` | `TWITTER_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](/x-ads-api/campaign-management#targeting-options). **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](/x-ads-api/campaign-management#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 * [Chunked media upload](/x-api/media/quickstart/media-upload-chunked) (for video upload) * [POST accounts/:account\_id/media\_library](/x-ads-api/creatives#media-library) (for video association to ads account) * [POST accounts/:account\_id/campaigns](/x-ads-api/campaign-management#post-accounts-account-id-campaigns) (create campaign) * [GET content\_categories](/x-ads-api/campaign-management#content-categories) (to get the mapping of content categories to IAB categories) * [GET accounts/:account\_id/curated\_categories](/x-ads-api/campaign-management#curated-categories-2) * [GET publishers](/x-ads-api/campaign-management#publishers) * [POST accounts/:account\_id/line\_item\_curated\_categories](/x-ads-api/campaign-management#line-item-curated-categories) * [POST accounts/:account\_id/line\_items](/x-ads-api/campaign-management#campaigns) (create ad group) * [POST accounts/:account\_id/media\_creatives](/x-ads-api/campaign-management#post-accounts-account-id-media-creatives) (to associate video with ad group) * [POST accounts/:account\_id/preroll\_call\_to\_action](/x-ads-api/creatives#preroll-call-to-actions) (set CTA and redirect URL) * [POST batch/accounts/:account\_id/targeting\_criteria](/x-ads-api/campaign-management#post-batch-accounts-account-id-targeting-criteria) (targeting) #### Steps #### Upload the video Uploading the video involves 2 steps: #### Upload the video media First, using the [Chunked media upload](/x-api/media/quickstart/media-upload-chunked) 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](/x-ads-api/creatives#promoted-video). #### 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](/x-ads-api/creatives#media-library) endpoint. ```json theme={null} 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](/x-ads-api/campaign-management#post-accounts-account-id-campaigns) and [line item/ad group](/x-ads-api/campaign-management#campaigns). 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](/x-ads-api/campaign-management#advertiser-business-categories). ```json theme={null} 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](/x-ads-api/campaign-management#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, ```json theme={null} 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: ```json theme={null} 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](/x-ads-api/campaign-management#curated-categories-2) 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](/x-ads-api/campaign-management#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](/x-ads-api/campaign-management#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 ```json theme={null} 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](/x-ads-api/campaign-management#get-accounts-account-id-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.
*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](/x-ads-api/introduction) 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](/x-ads-api/fundamentals/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[](#example-request "Permalink to this headline") ```json theme={null} GET https://ads-api.x.com/12/accounts?account_ids=18ce54d4x5t ``` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#get-accounts-account-id "Permalink to this headline") Retrieve a specific account that the authenticating user has access to. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/accounts/18ce54d4x5t` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#post-accounts "Permalink to this headline") Note: **SANDBOX ONLY** Create an ads account in the sandbox environment. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api-sandbox.x.com/12/accounts` **Parameters[](#parameters "Permalink to this headline")** None **Example Request[](#example-request "Permalink to this headline")** `POST https://ads-api-sandbox.x.com/12/accounts` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#put-accounts-account-id "Permalink to this headline") Updates the account name and/or industry type. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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[](#example-request "Permalink to this headline")** `PUT https://ads-api.x.com/12/accounts/18ce54d4x5t?name='API McTestface 2'&industry_type=TECHNOLOGY` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#delete-accounts-account-id "Permalink to this headline") Note: **SANDBOX ONLY** Delete an ads account in the sandbox environment. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api-sandbox.x.com/12/accounts/:account_id` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :---------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#accounts).
The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` | **Example Request[](#example-request "Permalink to this headline")** `DELETE https://ads-api-sandbox.x.com/12/accounts/gq12fh` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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 ❯](https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87) #### GET account\_apps[](#get-account-apps "Permalink to this headline") Retrieve details for all mobile apps that are associated with the specified ad account. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/account_apps` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :----------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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](/x-ads-api/introduction) for more information.
Type: string
Example: `8x7v00oow` | | sort\_by
*optional* | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/fundamentals/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[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_apps` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#get-accounts-account-id-account-history "Permalink to this headline") 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[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/account_history` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :----------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/introduction) 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](https://en.wikipedia.org/wiki/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](https://en.wikipedia.org/wiki/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[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_history?entity_type=CAMPAIGN&entity_id=fc3h5&count=1` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#get-advertiser-business-categories "Permalink to this headline") 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](/x-ads-api/campaign-management#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](/x-ads-api/campaign-management#line-items) endpoint to the set of corresponding `iab_categories` available through this endpoint. Additional details can be found in the [Video Views Preroll Objective Guide](/x-ads-api/campaign-management#video-views-preroll-objective) **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/advertiser_business_categories` **Parameters[](#parameters "Permalink to this headline")** No request parameters **Example Request[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/advertiser_business_categories` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#post-accounts-account-id-audience-estimate "Permalink to this headline") #### 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](/x-ads-api/campaign-management#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](/x-ads-api/campaign-management#targeting). **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/audience_estimate` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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](/x-ads-api/campaign-management#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[](#example-request "Permalink to this headline")** `POST https://ads-api.x.com/12/accounts/18ce54d4x5t/audience_estimate` ```json theme={null} { "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[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#get-accounts-account-id-authenticated-user-access "Permalink to this headline") 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[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/authenticated_user_access` **Parameters[](#parameters "Permalink to this headline")** None **Example Request[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/accounts/18ce54d4x5t/authenticated_user_access` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "data": { "user_id": "2417045708", "permissions": [ "ACCOUNT_ADMIN", "TWEET_COMPOSER" ] }, "request": { "params": { "account_id": "18ce54d4x5t" } } } ``` ### Bidding Rules #### GET bidding\_rules[](#get-bidding-rules "Permalink to this headline") 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[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/bidding_rules` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | currency
*optional* | The type of a currency to filter results by, identified using [ISO-4217](https://en.wikipedia.org/wiki/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[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/bidding_rules?currency=USD` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#get-accounts-account-id-campaigns "Permalink to this headline") Retrieve details for some or all campaigns associated with the current account. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/campaigns` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :----------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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](/x-ads-api/introduction) 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](/x-ads-api/introduction) 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[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns?campaign_ids=8wku2` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#get-accounts-account-id-campaigns-campaign-id "Permalink to this headline") Retrieve a specific campaign associated with the current account. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/campaigns/:campaign_id` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns/8wku2` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#post-accounts-account-id-campaigns "Permalink to this headline") 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[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/campaigns` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :-------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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](/x-ads-api/campaign-management#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[](#example-request "Permalink to this headline")** `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[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#post-batch-accounts-account-id-campaigns "Permalink to this headline") Allows the batch creation of new [campaigns](#post-accounts-account-id-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[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/batch/accounts/:account_id/campaigns` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 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](#post-accounts-account-id-campaigns). | **Example Request[](#example-request "Permalink to this headline")** `POST 'Content-Type: application/json' https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/campaigns` ```json theme={null} [ { "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[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#put-accounts-account-id-campaigns-campaign-id "Permalink to this headline") Update the specified campaign associated with the current account. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/campaigns/:campaign_id` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :---------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 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](/x-ads-api/campaign-management#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](/x-ads-api/campaign-management#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[](#example-request "Permalink to this headline")** `PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns/8wku2?total_budget_amount_local_micro=140000000` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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-accounts-account-id-campaigns-campaign-id "Permalink to this headline") 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[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/campaigns/:campaign_id` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :----------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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[](#example-request "Permalink to this headline")** `DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/campaigns/8yn7m` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#get-content-categories "Permalink to this headline") 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](/x-ads-api/campaign-management#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](/x-ads-api/campaign-management#publishers) endpoint. Additional details can be found in the [Video Views Pre-roll Objective Guide](/x-ads-api/campaign-management#video-views-preroll-objective). **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/content_categories` **Parameters[](#parameters "Permalink to this headline")** No request parameters **Example Request[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/content_categories` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#get-accounts-account-id-curated-categories "Permalink to this headline") 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](/x-ads-api/campaign-management#video-views-preroll-objective). **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/curated_categories` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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](/x-ads-api/introduction) for more information.
Type: string
Example: `8x7v00oow` | **Example Request[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/accounts/18ce54d4x5t/curated_categories?country_codes=US` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#get-accounts-account-id-curated-categories-curated-category-id "Permalink to this headline") 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[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/curated_categories/:curated_category_id` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :-------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/accounts/18ce54d4x5t/curated_categories/9ddrgesiap6o` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#get-accounts-account-id-features "Permalink to this headline") 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[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/features` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 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](/x-ads-api/campaign-management#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[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/accounts/18ce54d4x5t/features` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#post-accounts-account-id-features "Permalink to this headline") **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](#get-accounts-account-id-features) endpoint. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api-sandbox.x.com/12/accounts/:account_id/features` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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[](#example-request "Permalink to this headline")** `POST https://ads-api-sandbox.x.com/12/accounts/gq180y/features?feature_keys=VALIDATED_AGE_TARGETING` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#delete-accounts-account-id-features "Permalink to this headline") **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](#get-accounts-account-id-features) endpoint. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api-sandbox.x.com/12/accounts/:account_id/features` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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[](#example-request "Permalink to this headline")** `DELETE https://ads-api-sandbox.x.com/12/accounts/gq180y/features?feature_keys=PREROLL_VIEWS_OBJECTIVE` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#get-accounts-account-id-funding-instruments "Permalink to this headline") Retrieve details for some or all funding instruments associated with the current account. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/funding_instruments` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :----------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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](/x-ads-api/introduction) 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](/x-ads-api/introduction) 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[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/accounts/18ce54d4x5t/funding_instruments` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#get-accounts-account-id-funding-instruments-funding-instrument-id "Permalink to this headline") Retrieve a specific funding instrument associated with the current account. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/funding_instruments/:id` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :---------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/accounts/18ce54d4x5t/funding_instruments/lygyi` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#post-accounts-account-id-funding-instruments "Permalink to this headline") **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[](#resource-url "Permalink to this headline")** `https://ads-api-sandbox.x.com/12/accounts/:account_id/funding_instruments` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :--------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `gq1844` | | currency
*required* | The currency, expressed in [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217).
Type: string
Example: `USD` | | start\_time
*required* | The date for the funding instrument to become active and usable, expressed in [ISO 8601](https://en.wikipedia.org/wiki/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](https://en.wikipedia.org/wiki/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[](#example-request "Permalink to this headline")** `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[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#delete-accounts-account-id-funding-instruments-funding-instrument-id "Permalink to this headline") **SANDBOX ONLY** Delete a funding instrument in the sandbox environment. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api-sandbox.x.com/12/accounts/:account_id/funding_instruments/:funding_instrument_id` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :---------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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[](#example-request "Permalink to this headline")** `DELETE https://ads-api-sandbox.x.com/12/accounts/gq1844/funding_instruments/hxt82` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#get-iab-categories "Permalink to this headline") Request the valid app `categories` for ad groups (`line_items`). **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/iab_categories` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :----------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/introduction) 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[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/iab_categories?count=2` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#get-accounts-account-id-line-items "Permalink to this headline") Retrieve details for some or all line items associated with the current account. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/line_items` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :----------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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](/x-ads-api/introduction) 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](/x-ads-api/introduction) 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[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items?line_item_ids=itttx` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#get-accounts-account-id-line-items-line-item-id "Permalink to this headline") Retrieve a specific line item associated with the current account. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/line_items/:line_item_id` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items/itttx` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#post-accounts-account-id-line-items "Permalink to this headline") 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](/x-ads-api/campaign-management#targeting-options) for `iOS`. **Note**: There is a limit of 100 line items per campaign and 256 active line items across all campaigns. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/line_items` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :-------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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](https://en.wikipedia.org/wiki/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](https://en.wikipedia.org/wiki/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](/x-ads-api/campaign-management#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](https://business.x.com/en/help/campaign-setup/create-an-app-installs-or-app-engagement-campaign/mobile-app-conversion-tracking.html).
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](/x-ads-api/campaign-management#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[](#example-request "Permalink to this headline")** `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[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#post-batch-accounts-account-id-line-items "Permalink to this headline") Allows the batch creation of new [line items](#post-accounts-account-id-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[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/batch/accounts/:account_id/line_items` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :-------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](#post-accounts-account-id-line-items). | **Example Request[](#example-request "Permalink to this headline")** `POST 'Content-Type: application/json' https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/line_items` ```json theme={null} [ { "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[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#put-accounts-account-id-line-items-line-item-id "Permalink to this headline") Update the specified line item associated with the current account. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/line_items/:line_item_id` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :---------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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](/x-ads-api/campaign-management#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](https://en.wikipedia.org/wiki/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](https://business.x.com/en/help/campaign-setup/create-an-app-installs-or-app-engagement-campaign/mobile-app-conversion-tracking.html).
**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](https://en.wikipedia.org/wiki/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[](#example-request "Permalink to this headline")** `PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items/9cqi0?bid_amount_local_micro=140000` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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-accounts-account-id-line-items-line-item-id "Permalink to this headline") 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[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/line_items/:line_item_id` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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[](#example-request "Permalink to this headline")** `DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/line_items/9f2ix` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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](/x-ads-api/campaign-management#video-views-preroll-objective) #### GET accounts/:account\_id/line\_item\_curated\_categories[](#get-accounts-account-id-line-item-curated-categories "Permalink to this headline") Retrieve details for some or all line item curated categories associated with the current account. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :----------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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](/x-ads-api/introduction) for more information.
Type: string
Example: `8x7v00oow` | | sort\_by
*optional* | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/introduction) 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[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/accounts/abc1/line_item_curated_categories` **Example Response[](#example-response "Permalink to this headline")** ```josn theme={null} { "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[](#get-accounts-account-id-line-item-curated-categories-line-item-curated-category-id "Permalink to this headline") Retrieves details for a specific line item curated category associated with the current account. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :-------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/accounts/abc1/line_item_curated_categories/yav` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#post-accounts-account-id-line-item-curated-categories "Permalink to this headline") Associate a [curated category](/x-ads-api/campaign-management#curated-categories-2) object with the specified line item. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :-------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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[](#example-request "Permalink to this headline")** `POST https://ads-api.x.com/12/accounts/18ce54d4x5t/line_item_curated_categories?line_item_id=iqwka&curated_category_id=9ddrgesiap6o` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#put-accounts-account-id-line-item-curated-categories-line-item-curated-category-id "Permalink to this headline") Update the specified line item curated category. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :-------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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[](#example-request "Permalink to this headline")** `PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/line_item_curated_categories/xq?curated_category_id=8tujl1p3yn0g` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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-accounts-account-id-line-item-curated-categories-line-item-curated-category-id "Permalink to this headline") Delete the specified line item curated category. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/line_item_curated_categories/:line_item_curated_category_id` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :-------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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[](#example-request "Permalink to this headline")** `DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/line_item_curated_categories/xq` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#get-line-items-placements "Permalink to this headline") Retrieve valid `placement` and `product_type` combinations. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/line_items/placements` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/line_items/placements?product_type=PROMOTED_ACCOUNT` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#get-accounts-account-id-media-creatives "Permalink to this headline") Retrieve details for some or all media creatives associated with the current account. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/media_creatives` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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](/x-ads-api/introduction) 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](/x-ads-api/introduction) 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[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives?media_creative_ids=1bzq3` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#get-accounts-account-id-media-creatives-media-creative-id "Permalink to this headline") Retrieves details for a specific media creative associated with the current account. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/media_creatives/:media_creative_id` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives/1bzq3` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#post-accounts-account-id-media-creatives "Permalink to this headline") Associate an [account media](/x-ads-api/creatives#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](/x-ads-api/creatives#account-media) endpoint. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/media_creatives` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :--------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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](/x-ads-api/creatives#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[](#example-request "Permalink to this headline")** `POST https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives?line_item_id=8v7jo&account_media_id=10miy` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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-accounts-account-id-media-creatives-media-creative-id "Permalink to this headline") Delete the specified media creative belonging to the current account. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/media_creatives/:media_creative_id` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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[](#example-request "Permalink to this headline")** `DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/media_creatives/1bzq3` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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 } } ``` ### Promoted Accounts #### GET accounts/:account\_id/promoted\_accounts[](#get-accounts-account-id-promoted-accounts "Permalink to this headline") Retrieve details for some or all promoted accounts associated with one or more line items under the current account. Use [GET users/lookup](https://developer.x.com/en/docs/x-api/v1/accounts-and-users/follow-search-get-users/api-reference/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[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/promoted_accounts` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :--------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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](/x-ads-api/introduction) 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](/x-ads-api/introduction) 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[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts?promoted_account_ids=19pl2` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#get-accounts-account-id-promoted-accounts-promoted-account-id "Permalink to this headline") Retrieve a specific reference to an account associated with a line item under the current account. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/promoted_accounts/:promoted_account_id` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :-------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts/19pl2` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#post-accounts-account-id-promoted-accounts "Permalink to this headline") 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](/x-ads-api/campaign-management#advertiser-api) page. **Note**: It is not possible to update (PUT) promoted accounts entities. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/promoted_accounts` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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](https://developer.x.com/en/docs/x-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-users-lookup) to retrieve a user ID for a screen name.
Type: long
Example: `756201191646691328` | **Example Request[](#example-request "Permalink to this headline")** `POST https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts?line_item_id=9bpb2&user_id=756201191646691328` **Example Response[](#example-response "Permalink to this headline")** ```json theme={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 }, "request": { "params": { "user_id": "756201191646691328", "line_item_id": "9bpb2", "account_id": "18ce54d4x5t" } } } ``` #### DELETE accounts/:account\_id/promoted\_accounts/:promoted\_account\_id[](#delete-accounts-account-id-promoted-accounts-promoted-account-id "Permalink to this headline") Disassociate an account from the specified line item. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/promoted_accounts/:promoted_account_id` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :-------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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[](#example-request "Permalink to this headline")** `DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_accounts/19pl2` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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" } } } ``` ### Promoted Tweets #### GET accounts/:account\_id/promoted\_tweets[](#get-accounts-account-id-promoted-tweets "Permalink to this headline") Retrieve references to Tweets associated with line items under the current account. Use the [GET accounts/:account\_id/tweets](/x-ads-api/creatives#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[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/promoted_tweets` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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](/x-ads-api/introduction) 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](/x-ads-api/introduction) 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[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets?promoted_tweet_ids=1efwlo` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#get-accounts-account-id-promoted-tweets-promoted-tweet-id "Permalink to this headline") 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[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/promoted_tweets/:promoted_tweet_id` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets/1efwlo` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#post-accounts-account-id-promoted-tweets "Permalink to this headline") 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](/x-ads-api/campaign-management#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[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/promoted_tweets` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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[](#example-request "Permalink to this headline")** `POST https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets?line_item_id=8v7jo&tweet_ids=822333526255120384` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#delete-accounts-account-id-promoted-tweets-promoted-tweet-id "Permalink to this headline") 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[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/promoted_tweets/:promoted_tweet_id` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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](#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[](#example-request "Permalink to this headline")** `DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/promoted_tweets/1gp8a5` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#get-accounts-account-id-promotable-users "Permalink to this headline") 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](/x-ads-api/campaign-management#promoted-tweets) endpoint to promote published Tweets and the [POST accounts/:account\_id/scheduled-promoted-tweets](/x-ads-api/campaign-management#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[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/promotable_users` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :-------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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](/x-ads-api/introduction) 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](/x-ads-api/introduction) 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[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promotable_users?promotable_user_ids=l310s` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#get-accounts-account-id-promotable-users-promotable-user-id "Permalink to this headline") 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[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/promotable_users/:promotable_user_id` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/accounts/18ce54d4x5t/promotable_users/l310s` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#get-publishers "Permalink to this headline") Retrieve a list of Content Category publishers' details Additional details can be found in the [Video Views Preroll Objective Guide](/x-ads-api/campaign-management#video-views-preroll-objective) **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/publishers` **Parameters[](#parameters "Permalink to this headline")** No request parameters **Example Request[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/publishers` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "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[](#get-accounts-account-id-recommendations "Permalink to this headline") Status: *Closed Beta* Retrieve campaign recommendations associated with this ads account. Currently there is a limit of 1 recommendation per funding instrument. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/5/accounts/:account_id/recommendations` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :---------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` | **Example Request[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/5/accounts/18ce54d4x5t/recommendations` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} "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[](#get-accounts-account-id-recommendations-recommendation-id "Permalink to this headline") 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[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/5/accounts/:account_id/recommendations/:recommendation_id` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :----------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` | | recommendation\_id
*required* | A reference to the recommendation ID you are operating within the request
Type: string
Example: `62ce8zza1q0w` | **Example Request[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/5/accounts/18ce54d4x5t/recommendations/62ce8zza1q0w` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "request": { "params": { "recommendation_id": "62ce8zza1q0w", "account_id": "18ce54d4x5t" } }, "data_type": "recommendations", "data": { "changes": [ { "entity_type": "campaigns", "params": { "start_time": "2016-11-08T22:00:00Z", "daily_budget_amount_local_micro": 2200000, "end_time": "2016-11-16T07:59:00Z", "total_budget_amount_local_micro": 12000000, "id": "64m0d" }, "operation_type": "Update", "dependent_entities": [ { "entity_type": "line_items", "params": { "name": "Campaign for recommendations", "placements": [ "TWITTER_TIMELINE" ], "bid_amount_local_micro": 1430000, "id": "6f5kq", "include_sentiment": "ALL" }, "operation_type": "Update", "dependent_entities": [ { "entity_type": "targeting_criteria", "params": { "id": "a8po6p" }, "operation_type": null, "dependent_entities": [] }, { "entity_type": "targeting_criteria", "params": { "line_item_id": "6f5kq", "name": "election results", "targeting_value": "election results", "targeting_type": "PHRASE_KEYWORD" }, "operation_type": "Create", "dependent_entities": [] }, { "entity_type": "promoted_tweets", "params": { "id": "101ftp" }, "operation_type": "Delete", "dependent_entities": [] }, { "entity_type": "targeting_criteria", "params": { "line_item_id": "6f5kq", "name": "Male", "targeting_value": 1, "targeting_type": "GENDER" }, "operation_type": "Create", "dependent_entities": [] }, { "entity_type": "targeting_criteria", "params": { "line_item_id": "6f5kq", "name": "San Francisco-Oakland-San Jose CA, US", "targeting_value": "", "targeting_type": "LOCATION" }, "operation_type": "Create", "dependent_entities": [] }, { "entity_type": "promoted_tweets", "params": { "id": "101fto" }, "operation_type": "Delete", "dependent_entities": [] }, { "entity_type": "promoted_tweets", "params": { "line_item_id": "6f5kq", "display_properties": [], "paused": false, "approval_status": "ACCEPTED", "tweet_id": "91125952589766656" }, "operation_type": "Create", "dependent_entities": [] }, { "entity_type": "targeting_criteria", "params": { "line_item_id": "6f5kq", "name": "Partner audience targeting", "targeting_value": "v2cx", "targeting_type": "NEGATIVE_BEHAVIOR" }, "operation_type": "Create", "dependent_entities": [] }, { "entity_type": "targeting_criteria", "params": { "line_item_id": "6f5kq", "name": "AGE_21_TO_34", "targeting_value": "AGE_21_TO_34", "targeting_type": "AGE" }, "operation_type": "Create", "dependent_entities": [] }, { "entity_type": "targeting_criteria", "params": { "id": "a8po6o" }, "operation_type": "Delete", "dependent_entities": [] }, { "entity_type": "promoted_tweets", "params": { "line_item_id": "6f5kq", "display_properties": [], "paused": false, "approval_status": "ACCEPTED", "tweet_id": "991101965843460096" }, "operation_type": "Create", "dependent_entities": [] }, { "entity_type": "promoted_tweets", "params": { "line_item_id": "6f5kq", "display_properties": [], "paused": false, "approval_status": "ACCEPTED", "tweet_id": "991127212156096516" }, "operation_type": "Create", "dependent_entities": [] }, { "entity_type": "targeting_criteria", "params": { "line_item_id": "6f5kq", "name": "debate", "targeting_value": "debate", "targeting_type": "NEGATIVE_PHRASE_KEYWORD" }, "operation_type": "Create", "dependent_entities": [] }, { "entity_type": "targeting_criteria", "params": { "line_item_id": "6f5kq", "name": "60004, IL, US", "targeting_value": "", "targeting_type": "LOCATION" }, "operation_type": "Create", "dependent_entities": [] }, { "entity_type": "targeting_criteria", "params": { "id": "a8po6n" }, "operation_type": null, "dependent_entities": [] }, { "entity_type": "promoted_tweets", "params": { "id": "101ftn" }, "operation_type": null, "dependent_entities": [] } ] } ] } ], "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" } } ``` ### Scheduled Promoted Tweets #### GET accounts/:account\_id/scheduled\_promoted\_tweets[](#get-accounts-account-id-scheduled-promoted-tweets "Permalink to this headline") Retrieve details for some or all scheduled promoted Tweets associated with the current account. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/scheduled_promoted_tweets` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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](/x-ads-api/introduction) for more information.
Type: string
Example: `8x7v00oow` | | line\_item\_ids
*optional* | Scope the response to just the scheduled Tweets associated with specific line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
Type: string
Example: `8xdpe` | | scheduled\_promoted\_tweet\_ids
*optional* | Scope the response to just the desired scheduled promoted Tweets by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
Type: string
Example: `1xboq` | | sort\_by
*optional* | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/introduction) 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[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets?scheduled_promoted_tweet_ids=1xboq` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "request": { "params": { "scheduled_promoted_tweet_ids": [ "1xboq" ], "account_id": "18ce54d4x5t" } }, "next_cursor": null, "data": [ { "line_item_id": "8xdpe", "id": "1xboq", "created_at": "2017-06-01T19:53:32Z", "updated_at": "2017-06-01T20:00:06Z", "scheduled_tweet_id": "870366669373194240", "tweet_id": "870369382207070208", "deleted": false } ] } ``` #### GET accounts/:account\_id/scheduled\_promoted\_tweets/:scheduled\_promoted\_tweet\_id[](#get-accounts-account-id-scheduled-promoted-tweets-scheduled-promoted-tweet-id "Permalink to this headline") Retrieve a specific scheduled promoted Tweet associated with the current account. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/scheduled_promoted_tweets/:scheduled_promoted_tweet_id` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :----------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` | | scheduled\_promoted\_tweet\_id
*required* | A reference to the scheduled promoted Tweet you are operating with in the request.
Type: string
Example: `1xboq` | | with\_deleted
*optional* | Include deleted results in your request.
Type: boolean
Default: `false`
Possible values: `true`, `false` | **Example Request[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets/1xboq` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "request": { "params": { "scheduled_promoted_tweet_id": "1xboq", "account_id": "18ce54d4x5t" } }, "data": { "line_item_id": "8xdpe", "id": "1xboq", "created_at": "2017-06-01T19:53:32Z", "updated_at": "2017-06-01T20:00:06Z", "scheduled_tweet_id": "870366669373194240", "tweet_id": "870369382207070208", "deleted": false } } ``` #### POST accounts/:account\_id/scheduled\_promoted\_tweets[](#post-accounts-account-id-scheduled-promoted-tweets "Permalink to this headline") Associate a scheduled Tweet with the specified line item. **Note**: It is not possible to update (PUT) scheduled promoted Tweet entities. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/scheduled_promoted_tweets` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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: `8xdpe` | | scheduled\_tweet\_id
*required* | A reference to the scheduled Tweet you are operating with in the request.
Type: long
Example: `870358555227860992` | **Example Request[](#example-request "Permalink to this headline")** `POST https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets?line_item_id=8xdpe&scheduled_tweet_id=870358555227860992` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "data": { "line_item_id": "8xdpe", "id": "1xtfl", "created_at": "2017-06-08T07:25:26Z", "updated_at": "2017-06-08T07:25:26Z", "scheduled_tweet_id": "870358555227860992", "tweet_id": null, "deleted": false }, "request": { "params": { "line_item_id": "8xdpe", "scheduled_tweet_id": 870358555227860992, "account_id": "18ce54d4x5t" } } } ``` #### DELETE accounts/:account\_id/scheduled\_promoted\_tweets/:scheduled\_promoted\_tweet\_id[](#delete-accounts-account-id-scheduled-promoted-tweets-scheduled-promoted-tweet-id "Permalink to this headline") Disassociate a scheduled Tweet from the specified line item. **Note**: `scheduled_promoted_tweets` can only be deleted *before* the scheduled Tweet's `scheduled_at` time. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :----------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` | | scheduled\_promoted\_tweet\_id
*required* | A reference to the scheduled promoted Tweet you are operating with in the request. This is the `id` attribute from a [GET accounts/:account\_id/scheduled\_promoted\_tweets](#get-accounts-account-id-scheduled-promoted-tweets) response object.
Type: string
Example: `1xtfl` | **Example Request[](#example-request "Permalink to this headline")** `DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_promoted_tweets/1xtfl` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "data": { "line_item_id": "8xdpe", "id": "1xtfl", "created_at": "2017-06-08T07:25:26Z", "updated_at": "2017-06-15T05:14:12Z", "scheduled_tweet_id": "870358555227860992", "tweet_id": null, "deleted": true }, "request": { "params": { "scheduled_promoted_tweet_id": "1xtfl", "account_id": "18ce54d4x5t" } } } ``` ### Targeting Criteria #### GET accounts/:account\_id/targeting\_criteria[](#get-accounts-account-id-targeting-criteria "Permalink to this headline") Retrieve details for some or all of the targeting criteria associated with line items under the current account. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/targeting_criteria` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` | | line\_item\_ids
*required* | Scope the response to just the targeting criteria under the specified line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
Type: string
Example: `8u94t` | | 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](/x-ads-api/introduction) for more information.
Type: string
Example: `8x7v00oow` | | lang
*optional* | An [ISO-639-1](https://en.wikipedia.org/wiki/ISO_639-1) language code. When passed, an additional `localized_name` attribute will be returned in the response for objects where a localized name is available.
Type: string
Example: `fr` | | sort\_by
*optional* | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/introduction) for more information.
Type: string
Example: `created_at-asc` | | targeting\_criterion\_ids
*optional* | Scope the response to just the desired targeting criteria by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
Type: string
Example: `dpl3a6` | | 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[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria?line_item_ids=8u94t` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "request": { "params": { "account_id": "18ce54d4x5t", "line_item_ids": [ "8u94t" ] } }, "next_cursor": null, "data": [ { "line_item_id": "8u94t", "name": "Custom audience targeting", "id": "dpl3a6", "operator_type": "EQ", "created_at": "2017-05-26T03:29:35Z", "targeting_value": "249yj", "updated_at": "2017-05-26T03:29:35Z", "deleted": false, "targeting_type": "CUSTOM_AUDIENCE" } ] } ``` #### GET accounts/:account\_id/targeting\_criteria/:targeting\_criterion\_id[](#get-accounts-account-id-targeting-criteria-targeting-criterion-id "Permalink to this headline") Retrieve a specific targeting criterion associated with the current account. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/targeting_criteria/:targeting_criterion_id` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :----------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` | | targeting\_criterion\_id
*required* | A reference to the targeting criterion you are operating with in the request.
Type: string
Example: `eijd4y` | | lang
*optional* | An [ISO-639-1](https://en.wikipedia.org/wiki/ISO_639-1) language code. When passed, an additional `localized_name` attribute will be returned in the response for objects where a localized name is available.
Type: string
Example: `fr` | | with\_deleted
*optional* | Include deleted results in your request.
Type: boolean
Default: `false`
Possible values: `true`, `false` | **Example Request[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria/eijd4y` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "request": { "params": { "targeting_criterion_id": "eijd4y", "account_id": "18ce54d4x5t" } }, "data": { "line_item_id": "619jl", "name": "🤖", "id": "eijd4y", "created_at": "2017-07-06T16:51:04Z", "targeting_value": "🤖", "updated_at": "2017-07-06T16:51:04Z", "deleted": false, "targeting_type": "BROAD_KEYWORD" } } ``` #### POST accounts/:account\_id/targeting\_criteria[](#post-accounts-account-id-targeting-criteria "Permalink to this headline") See the [Targeting Options](/x-ads-api/campaign-management#targeting-options) page to find `targeting_value`s for specific targeting types. We recommend that you refresh all data weekly, to ensure that you are working with the latest set of targeting type values. We change values and available targeting criteria from time to time; while the majority of these don't change often, some do. There is no guarantee that these values will not change. Use the `BROAD_KEYWORD`, `EXACT_KEYWORD`, `PHRASE_KEYWORD`, or `UNORDERED_KEYWORD` targeting types with the keywords specified in the `targeting_value`. Exclude keywords by using the `operator_type` request parameter set to `NE`. See [targeting keyword types](/x-ads-api/campaign-management#targeting) for a detailed description of each type. **Note**: It is only possible to target a single age bucket per line item. **Note**: To target a Custom Audience, that audience must be targetable. i.e., `targerable` *must* equal `true`. **Note**: When using targeting type `TV_SHOW`, there must be at least one `LOCATION` targeting criterion on the line item prior to setting the `TV_SHOW` targeting and all `LOCATION` must be within the same locale as the `TV_SHOW` being targeted. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/targeting_criteria` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :--------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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: `69ob` | | operator\_type
*required* | Specify the relationship that the targeting criterion should have. For example, to exclude keywords, use `operator_type=NE`.
Type: enum
Possible values: `EQ`, `NE`, `GTE`, `LT` | | targeting\_type
*required* | The type of targeting that will be applied to this line item.
Possible non-keyword-based values include: `AGE`, `DEVICE`, `EVENT`, `CAMPAIGN_ENGAGEMENT`, `CAMPAIGN_ENGAGEMENT_LOOKALIKE`, `CONVERSATION`, `ENGAGEMENT_TYPE`, `FOLLOWERS_OF_USER`, `GENDER`, `INTEREST`, `LANGUAGE`, `LIVE_TV_EVENT`, `LOCATION`, `NETWORK_ACTIVATION_DURATION`, `NETWORK_OPERATOR`, `PLATFORM`, `PLATFORM_VERSION`, `SIMILAR_TO_FOLLOWERS_OF_USER`, `TV_SHOW`, `USER_ENGAGEMENT`, `USER_ENGAGEMENT_LOOKALIKE`, `WIFI_ONLY`
**Note**: It is only possible to target a single `AGE` bucket per line item.
Possible keyword-based values include: `BROAD_KEYWORD`, `EXACT_KEYWORD`, `PHRASE_KEYWORD`, `UNORDERED_KEYWORD`
Possible custom audience values include: `CUSTOM_AUDIENCE`, `CUSTOM_AUDIENCE_EXPANDED`
Possible installed app store category values: `APP_STORE_CATEGORY`, `APP_STORE_CATEGORY_LOOKALIKE`
Possible Twitter Audience Platform (TAP) app exclusion: `APP_LIST` (may only be used with `operator_type=NE`) | | targeting\_value
*required* | Specify which user, which interest, which location, which event, which platform, which platform version, which device, which keyword or phrase, which gender, which custom audience, which app store category, or which exclusion of an app list this targeting will be applied to, depending on the selected targeting\_type.
Type: string
Example: `174958347` | **Example Request[](#example-request "Permalink to this headline")** `POST https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria?line_item_id=619jl&targeting_type=BROAD_KEYWORD&targeting_value=technology` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "data": { "line_item_id": "619jl", "name": "technology", "id": "fbyjlr", "created_at": "2017-09-06T07:31:21Z", "targeting_value": "technology", "updated_at": "2017-09-06T07:31:21Z", "deleted": false, "targeting_type": "BROAD_KEYWORD" }, "request": { "params": { "line_item_id": "619jl", "targeting_type": "BROAD_KEYWORD", "targeting_value": "technology", "account_id": "18ce54d4x5t" } } } ``` #### POST batch/accounts/:account\_id/targeting\_criteria[](#post-batch-accounts-account-id-targeting-criteria "Permalink to this headline") Allows the batch creation of new Targeting Criteria with a single request. **Batch Requests** * The current maximum batch size is 500. * 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 Targeting Criteria parameter) are shown in the response under the `operation_errors` object. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/batch/accounts/:account_id/targeting_criteria` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :-------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | operation\_type
*required* | The per item operation type being performed.
Type: enum
Possible values: `Create`, `Delete` | | params
*required* | A JSON object containing all the parameters for the targeting criteria objects. For a list of required and optional targeting criteria parameters, see [here](#post-accounts-account-id-targeting-criteria).
In addition, this endpoint supports an `operator_type` parameter that works in conjunction with certain `targeting_type` values. The possible values for this parameter are `EQ` for equal to, `GTE` for greater than or equal to, `LT` for less than, and `NE` for not equal to. | **Example Request[](#example-request "Permalink to this headline")** `POST https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/targeting_criteria` ```json theme={null} [ { "operation_type":"Create", "params":{ "line_item_id":"6f9an", "targeting_type":"LOCATION", "targeting_value":"5122804691e5fecc" } }, { "operation_type":"Delete", "params":{ "targeting_criterion_id":"al2rua" } } ] ``` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "data_type": "targeting_criterion", "data": [ { "line_item_id": "6f9an", "name": "San Francisco-Oakland-San Jose CA, US", "id": "al7vt2", "location_type": "CITY", "operator_type": "EQ", "created_at": "2016-11-11T22:59:50Z", "targeting_value": "5122804691e5fecc", "updated_at": "2016-11-11T22:59:50Z", "deleted": false, "targeting_type": "LOCATION" }, { "line_item_id": "6keuo", "name": "accounts", "id": "al2rua", "operator_type": "EQ", "created_at": "2016-11-11T17:50:19Z", "targeting_value": "accounts", "updated_at": "2016-11-11T22:59:50Z", "deleted": true, "targeting_type": "BROAD_KEYWORD" } ], "request": [ { "params": { "line_item_id": "6f9an", "targeting_type": "LOCATION", "targeting_value": "5122804691e5fecc", "account_id": "18ce54d4x5t" }, "operation_type": "Create" }, { "params": { "targeting_criterion_id": "al2rua", "account_id": "18ce54d4x5t" }, "operation_type": "Delete" } ] } ``` #### DELETE accounts/:account\_id/targeting\_criteria/:targeting\_criterion\_id[](#delete-accounts-account-id-targeting-criteria-targeting-criterion-id "Permalink to this headline") Delete the specified targeting criterion belonging to the current account. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/targeting_criteria/:targeting_criterion_id` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :----------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` | | targeting\_criterion\_id
*required* | A reference to the targeting criterion you are operating with in the request.
Type: string
Example: `dpl3a6` | **Example Request[](#example-request "Permalink to this headline")** `DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_criteria/dpl3a6` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "data": { "line_item_id": "8u94t", "name": "Custom audience targeting", "id": "dpl3a6", "created_at": "2017-05-26T03:29:35Z", "targeting_value": "249yj", "updated_at": "2017-08-30T18:38:58Z", "deleted": true, "targeting_type": "CUSTOM_AUDIENCE" }, "request": { "params": { "targeting_criterion_id": "dpl3a6", "account_id": "18ce54d4x5t" } } } ``` ### Targeting Options * [App Store Categories](#get-targeting-criteria-app-store-categories) * [Conversation](#get-targeting-criteria-conversations) * [Devices](#get-targeting-criteria-devices) * [Events](#get-targeting-criteria-events) * [Interests](#get-targeting-criteria-interests) * [Languages](#get-targeting-criteria-languages) * [Locations](#get-targeting-criteria-locations) * [Network Operators](#get-targeting-criteria-network-operators) * [Platform Versions](#get-targeting-criteria-platform-versions) * [Platforms](#get-targeting-criteria-platforms) * [TV Markets](#get-targeting-criteria-tv-markets) * [TV Shows](#get-targeting-criteria-tv-shows) #### GET targeting\_criteria/app\_store\_categories[](#get-targeting-criteria-app-store-categories "Permalink to this headline") Discover available app store category-based targeting criteria for Promoted Products. App store categories are available for the iOS App Store and the Google Play store only. Installed app category targeting allows targeting of users based on the categories of apps they have installed or have indicated interest in. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/targeting_criteria/app_store_categories` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- | | q
*optional* | An optional query to scope a targeting criteria. Omit this parameter to retrive all.
Type: string
Example: `music` | | os\_type
*optional* | Scope the results by a specific app store.
Type: enum
Possible values: `ANDROID`, `IOS` | **Example Request[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/targeting_criteria/app_store_categories?q=music&os_type=IOS` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "data": [ { "name": "Games: Music", "targeting_type": "APP_STORE_CATEGORY", "targeting_value": "qouq", "os_type": "IOS" }, { "name": "Music", "targeting_type": "APP_STORE_CATEGORY", "targeting_value": "qov2", "os_type": "IOS" } ], "request": { "params": { "q": "music", "os_type": "IOS" } } } ``` #### GET targeting\_criteria/conversations[](#get-targeting-criteria-conversations "Permalink to this headline") Discover available conversation-based targeting criteria for Promoted Products. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/targeting_criteria/conversations` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :----------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | conversation\_type
*optional* | An optional query to scope to a certain conversation type.
Type: enum
Possible values: `ACTORS`, `ATHLETES`, `BOOK_GENRES`, `BOOKS`, `BRAND_CATEGORIES`, `BRANDS`, `CELEBRITIES`, `COACHES`, `DIGITAL_CREATORS`, `ENTERTAINMENT_BRANDS`, `ENTERTAINMENT_PERSONALITIES`, `FICTIONAL_CHARACTERS`, `JOURNALISTS`, `LIFESTYLES`, `MOVIE_GENRES`, `MOVIES`, `MUSIC_GENRES`, `MUSICIANS`, `NEWS_STORIES`, `NEWS`, `PERSONS`, `PLACES`, `PODCASTS`, `POLITICAL_AFFILIATIONS`, `POLITICIANS`, `PRODUCTS`, `RADIO_STATIONS`, `SPORTS_LEAGUES`, `SPORTS_PERSONALITIES`, `SPORTS_TEAMS`, `SPORTS`, `TRENDS`, `TV_SHOWS`, `VIDEO_GAME_PLATFORMS`, `VIDEO_GAME_PUBLISHERS`, `VIDEO_GAMES` | | 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](/x-ads-api/introduction) for more information.
Type: string
Example: `8x7v00oow` | **Example Request[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/targeting_criteria/conversations?count=2` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "request": { "params": { "count": 2 } }, "next_cursor": "1f7m7", "data": [ { "targeting_type": "CONVERSATION", "targeting_value": "a1", "name": "NFL", "conversation_type": "SPORTS" }, { "targeting_type": "CONVERSATION", "targeting_value": "a2", "name": "NBA", "conversation_type": "SPORTS" } ] } ``` #### GET targeting\_criteria/devices[](#get-targeting-criteria-devices "Permalink to this headline") Discover available device-based targeting criteria for Promoted Products. Device targeting is available for Promoted Tweets. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/targeting_criteria/devices` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- | | count
*optional* | Specifies the number of records to try and retrieve per distinct request.
Type: int
Default: `200`
Min, Max: `1`, `1000` | | q
*optional* | An optional query to scope a targeting criteria. Omit this parameter to retrive all.
Type: string
Example: `apple` | **Example Request[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/targeting_criteria/devices?count=2&q=iphone` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "data": [ { "name": "iPhone 3GS", "manufacturer": "Apple", "os_type": "iOS", "targeting_value": "1q", "targeting_type": "DEVICE" }, { "name": "iPhone 4", "manufacturer": "Apple", "os_type": "iOS", "targeting_value": "1r", "targeting_type": "DEVICE" } ], "request": { "params": { "q": "iphone", "count": 2 } } } ``` #### GET targeting\_criteria/events[](#get-targeting-criteria-events "Permalink to this headline") Discover available event-based targeting criteria for Promoted Products. Only one event can be targeted per line item. **Note**: Events often exist across timezones, leading to complications when considering event times from cross-timezone perspectives. To simplify this, all event `start_time` and `end_time` values on this endpoint are represented in UTC±00:00, irrespective of the event's locale and timezone. This design should be kept in mind when querying and interacting with event `start_time` and `end_time` values. For example, Independence Day for the US is represented as `start_time=2017-07-04T00:00:00Z` and `end_time=2017-07-05T00:00:00Z` in UTC±00:00, and thus avoids the issue of this holiday existing across multiple timezones within the US. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/targeting_criteria/events` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | event\_types
*required* | An optional query to scope to certain event types.
Type: enum
Possible values: `CONFERENCE`, `HOLIDAY`, `MUSIC_AND_ENTERTAINMENT`, `OTHER`, `POLITICS`, `RECURRING`, `SPORTS` | | count
*optional* | Specifies the number of records to try and retrieve per distinct request.
Type: int
Default: `200`
Min, Max: `1`, `1000` | | country\_codes
*optional* | An optional query to scope a targeting criteria search to particular countries with the 2 letter ISO country code. If this parameter is not specified, all events are returned.
Type: string | | cursor
*optional* | Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/introduction) for more information.
Type: string
Example: `8x7v00oow` | | end\_time
*optional* | The time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), that the campaign will end.
Type: string
Example: `2017-10-05T00:00:00Z` | | start\_time
*optional* | The time, expressed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601), that the line item will begin serving.
**Note**: Defaults to the current time.
Type: string
Example: `2017-07-05T00:00:00Z` | **Example Request[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/targeting_criteria/events?count=1` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "request": { "params": { "count": 1 } }, "data_type": "events", "data": [ { "reach": { "total_reach": null }, "name": "New Year's", "start_time": "2017-12-31T00:00:00Z", "top_users": [], "top_tweets": [], "top_hashtags": [], "gender_breakdown_percentage": {}, "end_time": "2018-01-02T00:00:00Z", "country_code": null, "device_breakdown_percentage": {}, "targeting_value": "1ex", "is_global": true, "event_type": "HOLIDAY", "country_breakdown_percentage": {} } ], "next_cursor": "uww0" } ``` #### GET targeting\_criteria/interests[](#get-targeting-criteria-interests "Permalink to this headline") Discover available interest-based targeting criteria for Promoted Products. Interests change infrequently, however we suggest you refresh this list at least once weekly. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/targeting_criteria/interests` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :----------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/introduction) for more information.
Type: string
Example: `8x7v00oow` | | q
*optional* | An optional query to scope a targeting criteria. Omit this parameter to retrive all.
Type: string
Example: `books` | **Example Request[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/targeting_criteria/interests?q=books` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "data": [ { "name": "Books and literature/Biographies and memoirs", "targeting_type": "INTEREST", "targeting_value": "1001" } ], "request": { "params": { "q": "books", "count": 1 } }, "next_cursor": "6by4n4" } ``` #### GET targeting\_criteria/languages[](#get-targeting-criteria-languages "Permalink to this headline") Discover languages available for targeting. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/targeting_criteria/languages` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :----------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/introduction) for more information.
Type: string
Example: `8x7v00oow` | | q
*optional* | An optional query to scope a targeting criteria. Omit this parameter to retrive all.
Type: string
Example: `english` | **Example Request[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/targeting_criteria/languages?q=english` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "data": [ { "name": "English", "targeting_type": "LANGUAGE", "targeting_value": "en" } ], "request": { "params": { "q": "english" } }, "next_cursor": null } ``` #### GET targeting\_criteria/locations[](#get-targeting-criteria-locations "Permalink to this headline") Discover available location-based targeting criteria for Promoted Products. Geo-targeting is available for Promoted Accounts and Promoted Tweets at the country level, state/region level, city level, and postal code level. Postal code targeting must be used if you wish to retrieve analytics at the postal code level. **Note**: To retrieve specific targetable cities, such as San Francisco or New York, use the `CITIES` enum with the `location_type` request parameter. To target Designated Market Areas (DMAs), use the `METROS` enum. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/targeting_criteria/locations` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | count
*optional* | Specifies the number of records to try and retrieve per distinct request.
Type: int
Default: `200`
Min, Max: `1`, `1000` | | country\_code
*optional* | An optional query to scope a targeting criteria search to a specific country with the 2 letter ISO country code. Omit this parameter to retrieve results for all countries.
Type: string
Example: `JP` | | cursor
*optional* | Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/introduction) for more information.
Type: string
Example: `8x7v00oow` | | location\_type
*optional* | Scope the results by a specific kind of location. More granular targeting than `COUNTRIES` may not be available in all locations.
Type: enum
Possible values: `COUNTRIES`, `REGIONS`, `METROS`, `CITIES`, `POSTAL_CODES` | | q
*optional* | An optional query to scope a targeting criteria search. Omit this parameter to retrieve all results.
Type: string
Example: `New York` | **Example Request[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/targeting_criteria/locations?location_type=CITIES&q=los angeles` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "data": [ { "name": "Los Angeles, Los Angeles CA, CA, USA", "country_code": "US", "location_type": "CITIES", "targeting_value": "3b77caf94bfc81fe", "targeting_type": "LOCATION" }, { "name": "East Los Angeles, Los Angeles CA, CA, USA", "country_code": "US", "location_type": "CITIES", "targeting_value": "67571a7baaa5906b", "targeting_type": "LOCATION" }, { "name": "Lake Los Angeles, Los Angeles CA, CA, USA", "country_code": "US", "location_type": "CITIES", "targeting_value": "ea9bfbd43c93400f", "targeting_type": "LOCATION" }, { "name": "Los Gatos, San Francisco-Oakland-San Jose CA, CA, USA", "country_code": "US", "location_type": "CITIES", "targeting_value": "a2de7c70b82b0ca0", "targeting_type": "LOCATION" }, { "name": "Los Altos, Monterey-Salinas CA, CA, USA", "country_code": "US", "location_type": "CITIES", "targeting_value": "6a4364ea6f987c10", "targeting_type": "LOCATION" }, { "name": "Los Banos, CA, USA", "country_code": "US", "location_type": "CITIES", "targeting_value": "b1b6fc646de75904", "targeting_type": "LOCATION" }, { "name": "Los Alamitos, Los Angeles CA, CA, USA", "country_code": "US", "location_type": "CITIES", "targeting_value": "0799ff0a3c1006e9", "targeting_type": "LOCATION" }, { "name": "Los Angeles, US", "country_code": "US", "location_type": "CITIES", "targeting_value": "019940ae78c7b3bc", "targeting_type": "LOCATION" } ], "request": { "params": { "location_type": "CITIES", "q": "los angeles" } }, "next_cursor": null } ``` #### GET targeting\_criteria/network\_operators[](#get-targeting-criteria-network-operators "Permalink to this headline") Discover available network operator-based targeting criteria for Promoted Products. This endpoint enables you to lookup targetingable carriers, such as AT\&T, Verizon, Sprint, T-Mobile, etc., in multiple countries. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/targeting_criteria/network_operators` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | count
*optional* | Specifies the number of records to try and retrieve per distinct request.
Type: int
Default: `200`
Min, Max: `1`, `1000` | | country\_code
*optional* | An optional query to scope a targeting criteria search to a specific country with the 2 letter ISO country code. If this parameter is not specified only partner audiences for the United States are returned.
Type: string
Default: `US` | | cursor
*optional* | Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/introduction) for more information.
Type: string
Example: `8x7v00oow` | | q
*optional* | An optional query to scope a targeting criteria search. Omit this parameter to this parameter to retrieve all results.
Type: string
Examples: `Airpeak` | **Example Request[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/targeting_criteria/network_operators?count=5&country_code=US` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "data": [ { "country_code": "US", "targeting_type": "NETWORK_OPERATOR", "name": "Advantage", "targeting_value": "2l" }, { "country_code": "US", "targeting_type": "NETWORK_OPERATOR", "name": "Aeris", "targeting_value": "1b" }, { "country_code": "US", "targeting_type": "NETWORK_OPERATOR", "name": "Airadigm", "targeting_value": "2t" }, { "country_code": "US", "targeting_type": "NETWORK_OPERATOR", "name": "Airlink PCS", "targeting_value": "14" }, { "country_code": "US", "targeting_type": "NETWORK_OPERATOR", "name": "Airpeak", "targeting_value": "1i" } ], "request": { "params": { "country_code": "US", "count": 5 } }, "next_cursor": "o7x9iet1a5u608olj4" } ``` #### GET targeting\_criteria/platform\_versions[](#get-targeting-criteria-platform-versions "Permalink to this headline") Discover available mobile OS version-based targeting criteria for Promoted Products. Platform version targeting is available for Promoted Accounts and Promoted Tweets. This allows targeting down to the point release of a mobile operating system version, such as Android 8.0 or iOS 10.0. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/targeting_criteria/platform_versions` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | q
*optional* | An optional query to scope a targeting criteria search. Omit this parameter to this parameter to retrieve all results.
Type: string
Examples: `jelly bean` | **Example Request[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/targeting_criteria/platform_versions` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "data": [ {...}, { "name": "Ice Cream Sandwich", "number": "4.0", "os_type": "Android", "targeting_type": "PLATFORM_VERSION", "targeting_value": "17" }, { "name": "Jelly Bean", "number": "4.1", "os_type": "Android", "targeting_type": "PLATFORM_VERSION", "targeting_value": "18" }, {...} ], "data_type": "targeting_criterion", "request": { "params": {} } } ``` #### GET targeting\_criteria/platforms[](#get-targeting-criteria-platforms "Permalink to this headline") Discover available platform-based targeting criteria for Promoted Products. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/targeting_criteria/platforms` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :---------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | count
*optional* | Specifies the number of records to try and retrieve per distinct request.
Type: int
Default: `200`
Min, Max: `1`, `1000` | | q
*optional* | An optional query to scope a targeting criteria search. Omit this parameter to this parameter to retrieve all results.
Type: string
Examples: `ios`, `blackberry` | | lang
*optional* | Using a [ISO-639-1](https://en.wikipedia.org/wiki/ISO_639-1) language code. When passed, an additional localized\_name attribute will be returned in the response.
Type: int, string
Example: `fr` | **Example Request[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/targeting_criteria/platforms` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "data": [ { "name": "iOS", "targeting_type": "PLATFORM", "targeting_value": "0" }, { "name": "Android", "targeting_type": "PLATFORM", "targeting_value": "1" }, { "name": "BlackBerry phones and tablets", "targeting_type": "PLATFORM", "targeting_value": "2" }, { "name": "Mobile web on other devices", "targeting_type": "PLATFORM", "targeting_value": "3" }, { "name": "Desktop and laptop computers", "targeting_type": "PLATFORM", "targeting_value": "4" } ], "request": { "params": {} } } ``` #### GET targeting\_criteria/tv\_markets[](#get-targeting-criteria-tv-markets "Permalink to this headline") Discover available TV markets where TV shows can be targeted. Returns markets by locale that can used to query the [GET targeting\_criteria/tv\_shows](/x-ads-api/campaign-management#get-targeting-criteria-tv-shows) endpoint. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/targeting_criteria/tv_markets` **Parameters[](#parameters "Permalink to this headline")** None **Example Request[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/targeting_criteria/tv_markets` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "data": [ { "name": "France", "country_code": "FR", "locale": "fr-FR" }, { "name": "Chile", "country_code": "CL", "locale": "es-CL" }, { "name": "Germany", "country_code": "DE", "locale": "de-DE" }, { "name": "Netherlands", "country_code": "NL", "locale": "nl-NL" }, { "name": "United States", "country_code": "US", "locale": "en-US" }, { "name": "Venezuela", "country_code": "VE", "locale": "es-VE" }, { "name": "Brazil", "country_code": "BR", "locale": "pt-BR" }, { "name": "Mexico", "country_code": "MX", "locale": "es-MX" }, { "name": "Colombia", "country_code": "CO", "locale": "es-CO" }, { "name": "United Kingdom", "country_code": "GB", "locale": "en-GB" }, { "name": "Argentina", "country_code": "AR", "locale": "es-AR" }, { "name": "Japan", "country_code": "JP", "locale": "ja-JP" }, { "name": "Canada", "country_code": "CA", "locale": "en-CA" }, { "name": "Spain", "country_code": "ES", "locale": "es-ES" }, { "name": "Italy", "country_code": "IT", "locale": "it-IT" }, { "name": "United States - Hispanic", "country_code": "US", "locale": "es-US" }, { "name": "Ireland", "country_code": "IE", "locale": "en-IE" } ], "request": { "params": {} } } ``` #### GET targeting\_criteria/tv\_shows[](#get-targeting-criteria-tv-shows "Permalink to this headline") Discover available TV show-based targeting criteria for Promoted Products. TV show targeting is available for Promoted Tweets in certain markets. See the [GET targeting\_criteria/tv\_markets](/x-ads-api/campaign-management#get-targeting-criteria-tv-markets) endpoint for available markets. **Note**: Any audience that contains fewer than 1,000 users will appear with an `estimated_users` value of `1000`. **Note**: TV channel and genre targeting options are no longer supported. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/targeting_criteria/tv_shows` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :----------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | locale
*required* | A required parameter that specifies the tv\_market\_locale to query for available TV shows. TV markets are queried based on `locale` returned from the [GET targeting\_criteria/tv\_markets](/x-ads-api/campaign-management#get-accounts-account-id-targeting-criteria).
Type: string
Example: `en-US` | | count
*optional* | Specifies the number of records to try and retrieve per distinct request.
Type: int
Default: `50`
Min, Max: `1`, `50` | | cursor
*optional* | Specifies a cursor to get the next page of results. See [Pagination](/x-ads-api/introduction) for more information.
Type: string
Example: `8x7v00oow` | | q
*optional* | An optional query to scope a targeting criteria search. Omit this parameter to this parameter to retrieve all results.
Type: string
Examples: `ios`, `blackberry` | **Example Request[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/targeting_criteria/tv_shows?locale=en-US&q=news&count=1` **Example Response[](#example-response "Permalink to this headline")** ```jdon theme={null} { "data": [ { "name": "NewsWatch", "targeting_value": 10027243420, "genre": "PAID", "locales": [ { "language": "en", "country": "US" } ] } ], "next_cursor": "c-22838-zdQDJrTxSvOYfQOhb2IlGQ", "request": { "params": { "locale": { "countryCode": "US", "languageCode": "en" }, "count": 1, "q": "news" } } } ``` ### Targeting Suggestions #### GET accounts/:account\_id/targeting\_suggestions[](#get-accounts-account-id-targeting-suggestions "Permalink to this headline") Get up to 50 keyword or user targeting suggestions to complement your initial selection. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/targeting_suggestions` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :---------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#accounts). The specified account must be associated with the authenticating user.
Type: string
Example: `18ce54d4x5t` | | suggestion\_type
*required* | Specify the type of suggestions to return.
Type: enum
Possible values: `KEYWORD`, `USER_ID` | | targeting\_values
*required* | Comma separated collection of either keywords or user IDs used to seed the suggestions.
**Note**: These two types of suggestions cannot be mixed.
Example: `756201191646691328` | | count
*optional* | Specifies the number of records to try and retrieve per distinct request.
Type: int
Default: `30`
Min, Max: `1`, `50` | **Example Request[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/accounts/18ce54d4x5t/targeting_suggestions?suggestion_type=KEYWORD&targeting_values=developers&count=2"` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "data": [ { "suggestion_type": "KEYWORD", "suggestion_value": "devs" }, { "suggestion_type": "KEYWORD", "suggestion_value": "software" } ], "request": { "params": { "suggestion_type": "KEYWORD", "targeting_values": [ "developers" ], "count": 2, "account_id": "18ce54d4x5t" } } } ``` ### Tax Settings #### GET accounts/:account\_id/tax\_settings[](#get-accounts-account-id-tax-settings "Permalink to this headline") Retrieve tax setting details associated with the current account. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/tax_settings` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :---------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` | **Example Request[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tax_settings` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "request": { "params": { "account_id": "18ce54d4x5t" } }, "data": { "tax_id": "GB896391250", "address_city": "London", "business_relationship": "SELF", "address_street1": "21 March St", "address_last_name": null, "address_company": "ABC, Inc.", "tax_category": "BUSINESS_WITH_VAT", "address_postal_code": "SW1A 1AA", "bill_to": "NOT_SET", "address_region": "London", "address_country": "GB", "address_first_name": null, "invoice_jurisdiction": "NOT_SET", "address_street2": null, "address_email": null } } ``` #### PUT accounts/:account\_id/tax\_settings[](#put-accounts-account-id-tax-settings "Permalink to this headline") Update the tax settings for the current account. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/tax_settings` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :---------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` | | address\_city
*optional* | The city for the account owner's address.
Type: string
Example: `San Francisco` | | address\_country
*optional* | The two-letter country code for the account owner's address.
Type: string
Example: `US` | | address\_email
*optional* | The email associated with the account owner's address.
Type: string
Example: `api@mctestface.com` | | address\_first\_name
*optional* | The first name for the account owner's address.
Type: string
Example: `API` | | address\_last\_name
*optional* | The last name for the account owner's address.
Type: string
Example: `McTestface` | | address\_name
*optional* | The company name for the account owner's address.
Type: string
Example: `ABC, Co.` | | address\_postal\_code
*optional* | The postal code for the account owner's address.
Type: string
Example: `94102` | | address\_region
*optional* | The region for the account owner's address.
Type: string
Example: `California` | | address\_street1
*optional* | The street line for the account owner's address.
Type: string
Example: `21 March St` | | address\_street2
*optional* | The second street line for the account owner's address.
Type: string
Example: `Suite 99` | | bill\_to
*optional* | The entity that is billed.
Type: enum
Possible values: `ADVERTISER`, `AGENCY` | | business\_relationship
*optional* | Whether the account is owned by the advertiser or by the agency.
Type: enum
Possible values: `AGENCY`, `SELF` | | client\_address\_city
*optional* | The city for the advertiser's address.
Set this when the ads account is owned by an agency.
Type: string
Example: `Toronto` | | client\_address\_country
*optional* | The two-letter country code for the advertiser's address.
Set this when the ads account is owned by an agency.
Type: string
Example: `CA` | | client\_address\_email
*optional* | The email associated with the advertiser's address.
Set this when the ads account is owned by an agency.
Type: string
Example: `ads@brand.com` | | client\_address\_first\_name
*optional* | The first name for the advertiser's address.
Set this when the ads account is owned by an agency.
Type: string
Example: `Brand` | | client\_address\_last\_name
*optional* | The last name for the advertiser's address.
Set this when the ads account is owned by an agency.
Type: string
Example: `Advertiser` | | client\_address\_name
*optional* | The company name for the advertiser's address.
Set this when the ads account is owned by an agency.
Type: string
Example: `Brand, Inc.` | | client\_address\_postal\_code
*optional* | The postal code for the advertiser's address.
Set this when the ads account is owned by an agency.
Type: string
Example: `M5H 2N2` | | client\_address\_region
*optional* | The region for the advertiser's address.
Set this when the ads account is owned by an agency.
Type: string
Example: `Ontario` | | client\_address\_street1
*optional* | The street line for the advertiser's address.
Set this when the ads account is owned by an agency.
Type: string
Example: `280 Queen St W` | | client\_address\_street2
*optional* | The second street line for the advertiser's address.
Set this when the ads account is owned by an agency.
Type: string
Example: `The 6` | | invoice\_jurisdiction
*optional* | Invoice jurisdiction.
Type: enum
Possible values: `LOI_SAPIN`, `NONE`, `NOT_SET` | | tax\_category
*optional* | Whether the taxation should be individual or business.
Type: enum
Possible values: `BUSINESS_NO_VAT`, `BUSINESS_WITH_VAT`, `INDIVIDUAL` | | tax\_exemption\_id
*optional* | VAT exemption ID.
Type: sting
Example: `12345` | | tax\_id
*optional* | VAT registration ID.
Type: string
Possible values: `67890` | **Example Request[](#example-request "Permalink to this headline")** `PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/tax_settings?address_name=ABC, Co.` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "request": { "params": { "account_id": "18ce54d4x5t", "address_name": "ABC Co." } }, "data": { "tax_id": "GB896391250", "address_city": "London", "business_relationship": "SELF", "address_street1": "21 March St", "address_last_name": null, "address_company": "ABC, Co.", "tax_category": "BUSINESS_WITH_VAT", "address_postal_code": "SW1A 1AA", "bill_to": "NOT_SET", "address_region": "London", "address_country": "GB", "address_first_name": null, "invoice_jurisdiction": "NOT_SET", "address_street2": null, "address_email": null } } ``` ### Tracking Tags #### GET accounts/:account\_id/tracking\_tags[](#get-accounts-account-id-tracking-tags "Permalink to this headline") Retrieve details for some or all tracking tags associated with the current account. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/tracking_tags` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :----------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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](/x-ads-api/introduction) for more information.
Type: string
Example: `8x7v00oow` | | line\_item\_ids
*optional* | Scope the response to just the tracking tags associated with specific line items by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
Type: string
Example: `96uzp` | | sort\_by
*optional* | Sorts by supported attribute in ascending or descending order. See [Sorting](/x-ads-api/introduction) for more information.
Type: string
Example: `created_at-asc` | | tracking\_tag\_ids
*optional* | Scope the response to just the desired tracking tags by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.
Type: string
Example: `3m82` | | 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[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags?tracking_tag_ids=3m82` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "request": { "params": { "tracking_tag_ids": [ "3m82" ], "account_id": "18ce54d4x5t" } }, "next_cursor": null, "data": [ { "line_item_id": "fdwcl", "tracking_tag_url": "https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309", "tracking_tag_type": "IMPRESSION_TAG", "id": "3m82", "created_at": "2019-06-26T17:04:26Z", "updated_at": "2019-06-26T17:04:26Z", "deleted": false } ] } ``` #### GET accounts/:account\_id/tracking\_tags/:tracking\_tag\_id[](#get-accounts-account-id-tracking-tags-tracking-tag-id "Permalink to this headline") Retrieve a specific tracking tag associated with the current account. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/tracking_tags/:tracking_tag_id` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :---------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` | | tracking\_tag\_id
*required* | A reference to the tracking tag you are operating with in the request.
Type: string
Example: `555j` | | with\_deleted
*optional* | Include deleted results in your request.
Type: boolean
Default: `false`
Possible values: `true`, `false` | **Example Request[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags/555j` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "request": { "params": { "with_deleted": true, "tracking_tag_id": "555j", "account_id": "18ce54d4x5t" } }, "data": { "line_item_id": "72v2x", "tracking_tag_url": "https://ad.doubleclick.net/ddm/trackimp/N6344.2061500TWITTER-OFFICIAL/B23028778.279118262;dc_trk_aid=473354132;dc_trk_cid=119658253", "tracking_tag_type": "IMPRESSION_TAG", "id": "555j", "created_at": "2020-08-13T23:02:03Z", "updated_at": "2020-08-13T23:02:03Z", "deleted": false } } ``` #### POST accounts/:account\_id/tracking\_tags[](#post-accounts-account-id-tracking-tags "Permalink to this headline") Associate a tracking tag with the specified line item. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/tracking_tags` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#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` | | tracking\_tag\_type
*required* | The type of tracking tag.
Type: enum
Possible value: `IMPRESSION_TAG`, `CLICK_TRACKER` | | tracking\_tag\_url
*required* | The tracking tag url provided by the tracking partner.
Type: string
Example: `https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309` | **Example Request[](#example-request "Permalink to this headline")** `POST https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags?line_item_id=fdwcl&tracking_tag_type=IMPRESSION_TAG&tracking_tag_url=https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "request": { "params": { "line_item_id": "fdwcl", "tracking_tag_type": "IMPRESSION_TAG", "tracking_tag_url": "https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309", "account_id": "18ce54d4x5t" } }, "data": { "line_item_id": "fdwcl", "tracking_tag_url": "https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309", "tracking_tag_type": "IMPRESSION_TAG", "id": "3m82", "created_at": "2019-06-26T17:04:26Z", "updated_at": "2019-06-26T17:04:26Z", "deleted": false } } ``` #### PUT accounts/:account\_id/tracking\_tags/:tracking\_tag\_id[](#put-accounts-account-id-tracking-tags-tracking-tag-id "Permalink to this headline") Associate a tracking tag with the specified line item. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/tracking_tags/:tracking_tag_id` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :----------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` | | tracking\_tag\_url
*required* | The tracking tag url provided by the tracking partner.
Type: string
Example: `https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309` | **Example Request[](#example-request "Permalink to this headline")** `PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags/3m82?tracking_tag_url=https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "request": { "params": { "tracking_tag_id": "3m82", "tracking_tag_url": "https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309", "account_id": "18ce54d4x5t" } }, "data": { "line_item_id": "fdwcl", "tracking_tag_url": "https://ad.doubleclick.net/ddm/trackimp/N1234.2061500TWITTER-OFFICIAL/B9156151.125630439;dc_trk_aid=1355;dc_trk_cid=8675309", "tracking_tag_type": "IMPRESSION_TAG", "id": "3m82", "created_at": "2019-06-26T17:04:26Z", "updated_at": "2022-01-26T17:04:26Z", "deleted": false } } ``` #### DELETE accounts/:account\_id/tracking\_tags/:tracking\_tag\_id[](#delete-accounts-account-id-tracking-tags-tracking-tag-id "Permalink to this headline") Disassociate a tracking tag from the specified line item. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/tracking_tags/:tracking_tag_id` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :---------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#get-accounts). The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` | | tracking\_tag\_id
*required* | A reference to the tracking tag you are operating with in the request.
Type: string
Example: `555j` | **Example Request[](#example-request "Permalink to this headline")** `DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/tracking_tags/555j` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "request": { "params": { "tracking_tag_id": "555j", "account_id": "18ce54d4x5t" } }, "data": { "line_item_id": "72v2x", "tracking_tag_url": "https://ad.doubleclick.net/ddm/trackimp/N6344.2061500TWITTER-OFFICIAL/B23028778.279118262;dc_trk_aid=473354132;dc_trk_cid=119658253", "tracking_tag_type": "IMPRESSION_TAG", "id": "555j", "created_at": "2020-08-13T23:02:03Z", "updated_at": "2021-08-29T17:12:58Z", "deleted": true } } ``` ### User Settings ([https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87](https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87)) #### GET accounts/:account\_id/user\_settings/:user\_id[](#get-accounts-account-id-user-settings-user-id "Permalink to this headline") Retrieves user settings. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/user_settings/:user_id` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :---------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](/x-ads-api/campaign-management#get-accounts).
The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` | | 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[](#example-request "Permalink to this headline")** `GET https://ads-api.x.com/12/accounts/18ce54d4x5t/user_settings/756201191646691328` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "request": { "params": { "account_id": "18ce54d4x5t", "user_id": "756201191646691328" } }, "data": { "notification_email": "user@domain.com", "contact_phone": "", "contact_phone_extension": "" } } ``` #### PUT accounts/:account\_id/user\_settings/:user\_id[](#put-accounts-account-id-user-settings-user-id "Permalink to this headline") Updates user settings. Requires user context. Not accessible by account admins. **Resource URL[](#resource-url "Permalink to this headline")** `https://ads-api.x.com/12/accounts/:account_id/user_settings/:user_id` **Parameters[](#parameters "Permalink to this headline")** | Name | Description | | :------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | account\_id
*required* | The identifier for the leveraged account. Appears within the resource's path and [GET accounts](/x-ads-api/campaign-management#get-accounts).
The specified account must be associated with the authenticated user.
Type: string
Example: `18ce54d4x5t` | | 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` | | notification\_email
*optional* | Email to use for account notifications.
Type: string
Example: `user@domain.com` | | contact\_phone
*optional* | Contact phone number.
Type: string
Example: `202-555-0128` | | contact\_phone\_extension
*optional* | Extension for contact `contact_phone`.
Type: string
Example: `1234` | **Example Request[](#example-request "Permalink to this headline")** `PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/user_settings/756201191646691328?notification_email='user@domain.com'&subscribe_email_types=ACCOUNT_PERFORMANCE,PERFORMANCE_IMPROVEMENT"` **Example Response[](#example-response "Permalink to this headline")** ```json theme={null} { "request": { "params": { "account_id": "18ce54d4x5t", "user_id": "756201191646691328" "notification_email": "user@domain.com", "subscribed_campaign_events": [ "ACCOUNT_PERFORMANCE", "PERFORMANCE_IMPROVEMENT" ] } }, "data": { "notification_email": "user@domain.com", "contact_phone": "", "Contact_phone_extension": "" } } ``` # Catalog Management Source: https://docs.x.com/x-ads-api/catalog-management ## Overview The Catalog API is a commerce solution that gives advertisers the ability to set up product feeds, group products into sets, and holistically manage catalog products. The Catalog API will be a core tool that enables programmatic catalog management and grants advertisers more control over how their catalogs are ingested and updated. A catalog holds everything regarding the user's product and product set and is associated with the user's handle. Currently, **one user can only create one catalog**. The Catalog API supports 2 ways to ingest products: 1. Scheduled Feed: the user can add a feed url (CSV, TSV, and XML) that will be periodically fetched (X currently supports a file up to 8GB) 2. Batch Products API: the user can view, create, update and delete product attributes with batch (JSON) requests X merchants are able to create product sets based on filter rules. By doing so, they will be able to attach additional metadata to their products, and create special product sets to showcase these products through organic commerce features or dynamic product ads. The Catalog API and X shopping manager supports two types of product sets. 1. Manual: the user can select up to 50 products, and set a name and a description 2. Filter: the user can add up to 30 filters to automatically generate sets with products that satisfy these filters. Types of filters include price, Google product category, product type, inventory, sale price, and custom fields. Catalog API comes with 4 endpoints to manage catalog: * [Product Catalogs](https://developer.x.com/en/docs/x-ads-api/catalog-management/api-reference/product-catalogs) - Creating a container for product information * [Products](https://developer.x.com/en/docs/x-ads-api/catalog-management/api-reference/products) - Synchronously adding, updateing, viewing, and removing products from the catalogs * [Product Sets](https://developer.x.com/en/docs/x-ads-api/catalog-management/api-reference/product-sets) - Sorting products into groups based on product information * [Schedule Feeds](https://developer.x.com/en/docs/twitter-ads-api/catalog-management/api-reference/scheduled-feeds) - Seting up the asynchronous ingestion of file-based product data into the catalogs ### Prerequisites for the Catalog API Catalog API endpoints are currently available via early-access only. To apply for access, please reach out to your X representative. You are required to accept the terms of service via [X Shopping Manager](https://ads.x.com/shopping_manager). For the details on Shopping Manager and product specifications, please refer to [Product specifications guide](https://business.x.com/en/help/shopping-specs.html). ### Rate Limits The following table lists the rate limits for each endpoint. #### Product Catalog | HTTP Method | Rate limit | | :---------------------------------------------- | :------------------- | | GET /product\_catalogs | 1,000 per 15 minutes | | POST /product\_catalogs | 20 per 15 minutes | | PUT /product\_catalogs/:product\_catalog\_id | 20 per 15 minutes | | DELETE /product\_catalogs/:product\_catalog\_id | 20 per 15 minutes | #### Batch Products API | HTTP Method | Rate limit | | :------------------------------------------------------- | :------------------- | | GET /product\_catalogs/:product\_catalog\_id/products | 1,000 per 15 minutes | | PUT /product\_catalogs/:product\_catalog\_id/products | 600 per 15 minutes | | DELETE /product\_catalogs/:product\_catalog\_id/products | 150 per 15 minutes | #### Product Sets | HTTP Method | Rate limit | | :------------------------------------------------------------------------------ | :------------------- | | GET /product\_catalogs/:product\_catalog\_id/product\_sets | 2,000 per 15 minutes | | POST /product\_catalogs/:product\_catalog\_id/product\_sets | 100 per 15 minutes | | PUT /product\_catalogs/:product\_catalog\_id/product\_sets/:product\_set\_id | 500 per 15 minutes | | DELETE /product\_catalogs/:product\_catalog\_id/product\_sets/:product\_set\_id | 100 per 15 minutes | #### Product Feeds | HTTP Method | Rate limit | | :-------------------------------------------------------------------------------- | :------------------- | | GET /product\_catalogs/:product\_catalog\_id/product\_feeds | 1,000 per 15 minutes | | POST /product\_catalogs/:product\_catalog\_id/product\_feeds | 20 per 15 minutes | | PUT /product\_catalogs/:product\_catalog\_id/product\_feeds/:product\_feed\_id | 20 per 15 minutes | | DELETE /product\_catalogs/:product\_catalog\_id/product\_feeds/:product\_feed\_id | 20 per 15 minutes | # Creatives Source: https://docs.x.com/x-ads-api/creatives ## Overview Creatives are any entity that can be promoted in a campaign. Posts can include text, images, GIFs, videos, or cards. Cards can include images or videos. Image, GIF, or video creatives are uploaded using either the [POST media/upload](/x-api/media/upload-media#post-media-upload) — a simple upload endpoint that only supports images — or the POST media/upload (chunked) endpoints. These can be added to cards: * POST accounts/:account\_id/cards Tweets: * POST accounts/:account\_id/tweets - To add cards to Tweets, use the card\_uri parameter. Scheduled Tweets: * POST accounts/:account\_id/scheduled\_tweets For additional details on cards, please see the Cards page. The Promoted Video page provides details on associating videos with cards or Tweets. ### Cards The Ads API supports several card types that can be used in Tweets, which can then be promoted in campaigns. **Note**: once Tweeted, card details are publicly visible. This may include information about the user who owns the card. #### Image The following image specifications apply to assets used in [Cards](/x-ads-api/creatives#cards-2). Images must be 3MB or less and have an a width of at least 800px. In addition, we support the following width:height aspect ratios. * Website: 1:1 and 1.91:1 * Image App Download: 1:1 and 1.91:1 * Poll: 1.91:1 * Image Conversation: 1.91:1 * Image Direct Message: 1.91:1 We support the following image formats: .bmp, .jpeg, and .png. #### Video The following video specifications apply to assets used in [Cards](/x-ads-api/creatives#cards-2). We support the following width:height aspect ratios. * Video Website: 16:9 and 1:1 * Video App Download: 16:9 and 1:1 * Poll: 16:9 * Video Conversation: 16:9 * Video Direct Message: 16:9 ### Promoted Video This document provides a brief overview of the process for uploading and promoting video through the Ads API. The Ads API supports Promoted Video in [Tweets](/x-ads-api/creatives#tweets-2) and in the following cards: * [Video Website](https://devcommunity.x.com/t/ads-api-version-11/168814) * [Video App Download](https://devcommunity.x.com/t/ads-api-version-11/168814) * [Video Conversation](/x-ads-api/creatives#video-conversation-cards) First, upload the video using the [POST media/upload (chunked)](/x-api/media/initialize-media-upload) endpoint. Using the `media_id`, associate the video with an ads account using the POST accounts/:account\_id/videos endpoint. The video's `id`, sometimes referred to as the `media_key`, will be used in subsequent requests. This is a string that begins with an int, is followed by an underscore, and ends with a long value. As an example, see: `13_875943225764098048`. #### Promoted Video in Tweets To create a Tweet, use the [POST accounts/:account\_id/tweet](/x-ads-api/creatives#get-accounts-account-id-tweets) endpoint along with the video's `id`. In this step, you can also provide a video title, description, and call-to-action (CTA). These values are user-facing. #### Promoted Video in Cards Video App Download and Video Conversation cards support the ability to add a poster images. Upload an image to use in these cards using the [POST media/upload](/x-api/media/upload-media) endpoint. Create the card using one of the following endpoints: * [POST accounts/:account\_id/cards/video\_website](https://devcommunity.x.com/t/ads-api-version-11/168814) * [POST accounts/:account\_id/cards/video\_app\_download](https://devcommunity.x.com/t/ads-api-version-11/168814) * [POST accounts/:account\_id/cards/video\_conversation](https://devcommunity.x.com/t/ads-api-version-11/168814) using the video's `id` and, optionally, the image's `media_id` (for the poster image). Finally, create the Tweet using the POST accounts/:account\_id/tweet endpoint. Cards are attached to Tweets using the `card_uri` parameter. #### General Information For detailed guidance on video uploading through the API, please see the [Video Upload Guide](/x-api/media/quickstart/media-upload-chunked). Videos can also be promoted as pre-roll assets. See the [Video Views Pre-roll Objective Guide](/x-ads-api/campaign-management#video-views-preroll-objective) for a detailed explanation. * (As of 2015-10-22) When uploading videos to be used in promoted content, the `media_category` parameter must be set with a value of `amplify_video` for all `INIT` command requests to the [POST media/upload (chunked)](/x-api/media/initialize-media-upload) endpoint. Using this new param ensures that the video is asynchronously pre-processed and prepared for use in promoted content. The `STATUS` command can be used to check completion of asynchronous processing after video upload. * The maximum promoted video length currently allowed is 10 mins with a file size of 500MB or less. * Uploaded video should be either mp4 or mov. * Uploaded video generally processes quickly, but processing times can vary depending on video length and file size. * Uploaded poster images should be in png or jpg format. There are no aspect ratio or size requirements, but the poster image will be adjusted to fit the video player. ## Guides ### Scheduled Tweets #### Introduction Scheduled Tweets allow an advertiser or user to create a Tweet that can be scheduled to go live at a later date. In addition to being able create and manage these Tweets, the API allows the ability to associate these Tweets with a line item, to be promoted once the Tweet goes live. This allows advertisers to stage create native Tweets and plan their campaign creatives in advance of any key initiatives. For example, staging a Tweet creative to live immediately upon a new product announcement. The full set of functionality provided by the Scheduled Tweets API endpoints are listed below: * Create, modify and view newly scheduled Tweets * Associate a Scheduled Tweet with a line item * Query and manage existing scheduled Tweets * Once a Scheduled Tweet goes live, retrieve the live Tweet `id` #### API Endpoints The entire set of endpoints related to the above functionality is listed below: #### Scheduled Tweet Management * [GET accounts/:account\_id/scheduled\_tweets](/x-ads-api/creatives#get-accounts-account-id-scheduled-tweets) (retrieve a list of all Scheduled Tweets) * [GET accounts/:account\_id/scheduled\_tweets/:scheduled\_tweet\_id](/x-ads-api/creatives#get-accounts-account-id-scheduled-tweets) (lookup a specific Scheduled Tweet using its `id`) * [POST accounts/:account\_id/scheduled\_tweets](/x-ads-api/creatives#post-accounts-account-id-scheduled-tweets) (create a new Scheduled Tweet) * [PUT accounts/:account\_id/scheduled\_tweets/:scheduled\_tweet\_id](/x-ads-api/creatives#example-request-39) (modify an existing Scheduled Tweet) * [DELETE accounts/:account\_id/scheduled\_tweets/:scheduled\_tweet\_id](/x-ads-api/creatives#example-request-40) (delete a Scheduled Tweet using its `id`) * [GET accounts/:account\_id/scheduled\_tweets/preview/:scheduled\_tweet\_id](/x-ads-api/creatives#scheduled-tweets-2) (preview an existing Scheduled Tweet) #### Scheduled Promoted Tweets * [GET accounts/:account\_id/scheduled\_promoted\_tweets](/x-ads-api/campaign-management#get-accounts-account-id-scheduled-promoted-tweets) (retreive a list of all Scheduled Promoted Tweets) * [GET accounts/:account\_id/scheduled\_promoted\_tweets/:scheduled\_promoted\_tweet\_id](/x-ads-api/campaign-management#get-accounts-account-id-scheduled-promoted-tweets-scheduled-promoted-tweet-id) (lookup a Promoted Scheduled Tweet using its `id`) * [POST accounts/:account\_id/scheduled\_promoted\_tweets](/x-ads-api/campaign-management#post-accounts-account-id-scheduled-promoted-tweets) (create a new Scheduled Promoted Tweet) * [DELETE accounts/:account\_id/scheduled\_promoted\_tweets/:scheduled\_promoted\_tweet\_id](/x-ads-api/campaign-management#delete-accounts-account-id-scheduled-promoted-tweets-scheduled-promoted-tweet-id) (delete an existing Scheduled Promoted Tweet using its `id`) #### Scheduled Tweet View * [GET accounts/:account\_id/scheduled\_tweets/preview/:scheduled\_tweet\_id](/x-ads-api/creatives#scheduled-tweets-2) (view an existing Scheduled Tweet) Due to the nature of Scheduled Tweets being separate entities from “live” Tweets, there are two different sets of validations run on any creates or edits to these Tweets. The first set of validation rules are run during the Scheduled Tweet creation step, specifically: #### Scheduled Tweet Create: * Validate that the authenticated user has access to create organic Tweets for a given @handle Promoted-Only Tweet create privileges requires authenticated user to be an account user with [Tweet composer permissions](https://developer.x.com/content/developer-twitter/en/docs/ads/campaign-management/api-reference/authenticated-user-access#get-accounts-account-id-authenticated-user-access) * Validate that there are no more than 30 Tweets that are scheduled to be created within a 15 minute window of the scheduled\_at time. A SCHEDULED\_TWEET\_LIMIT\_EXCEEDED error message indicates that too many Scheduled Tweets have been scheduled within the same future, 15 minute time frame. Advertisers will need to remove an existing Scheduled Tweet or move the scheduled\_at time earlier or later. #### Scheduled Tweet goes "live": * These validation rules are run at the scheduled\_at time and are identical to those applied on regular Tweet creation in the API. For example, a Scheduled Tweet will not go live and the scheduled\_status will be set to FAILED if the Scheduled Tweet contains both an image and a gif #### Workflow **Create a new Scheduled Tweet** A new Scheduled Tweet can be created using the [POST accounts/:account\_id/scheduled\_tweets](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/scheduled-tweets#post-accounts-account-id-scheduled-tweets) endpoint. This endpoint has the following required parameters, `scheduled_at` time along with the Tweet `text` if no media entities are included in the Tweet. In addition, this endpoint provides a few additional options that allow you to create a scheduled Tweet on behalf of another @handle via the `as_user_id` param along with the ability to add a card (`card_uri`) and any media (`media_ids`). Note, a Tweet can only contain entities of the same type, i.e., either Video, Gif or Image. The `nullcast` param controls whether the Tweet is a “Promoted-Only” Tweet or not. All newly created Scheduled Tweets are "Promoted-Only" (`nullcast=true`) by default. If `nullcast=false` then an Organic Scheduled Tweet is created Once a Scheduled Tweet is successfully created, the response will contain an `id` field, which refers to the unique identifier of the Scheduled Tweet itself. In addition to this field, another field called `tweet_id` is also returned. This field is `null` initially, however once the Tweet goes live this field is populated with the ID of the “live” Tweet. ``` twurl -H 'ads-api.x.com' -X POST "/6/accounts/:account_id/scheduled_tweets" -d 'scheduled_at=2017-12-24T23:59:00Z&text=Happy Holidays!' ``` This will create the following Scheduled Tweet: ```json theme={null} { "request": { "params": { "text": "Happy Holidays!", "scheduled_at": "2017-12-24T23:59:00Z" } }, "data": { "completed_at": null, "id_str": "917507899668099072", "text": "Happy Holidays!", "user_id": "3271358660", "scheduled_status": "SCHEDULED", "id": 917507899668099100, "nullcast": true, "created_at": "2017-10-09T21:51:44Z", "scheduled_at": "2017-12-24T23:59:00Z", "card_uri": null, "updated_at": "2017-10-09T21:51:44Z", "tweet_id": null, "media_keys": [] } } ``` Once this Scheduled Tweet goes live, the `tweet_id` field will be populated with the "live" Tweet's ID. **View a Scheduled Tweet** The [GET accounts/:account\_id/tweet\_previews](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/tweet-previews#get-accounts-account-id-tweet-previews) endpoint can then be used with the Scheduled Tweet `id` from the previous step to generate a preview of the Tweet. The API response will contain an iframe URL that is ready to be used to render a preview for the Scheduled Tweet. The relevant CSS and images will be served directly via X. ``` twurl -H ads-api.x.com -X GET "/6/accounts/18ce54bgxky/tweet_previews?tweet_type=SCHEDULED&tweet_ids=917507899668099072 ``` ```json theme={null} { "request": { "params": { "tweet_type": "SCHEDULED", "tweet_ids": [ "917507899668099072" ], "account_id": "18ce54bgxky" } }, "data": [ { "tweet_id": "1126633863155871744", "preview": "<\iframe class='tweet-preview' src='https://ton.smf1.x.com/ads-manager/tweet-preview/index.html?data=H4sIAAAAAAAAAK1WTW%2FjNhD9Kyyv9dqSZdmOgALJbhJsCyxaIDkUWBUEJY0lNhSpklRSN%2FV%2F71CyZbm297S%2BWJxPzpt5I71T9wbgaELeaW6AOygYxyN9rlryhW9JcEPmUbKIkuiG%2FBjgj8yD8IZOqChoEobz5TKK1ssojOP1KlwtFl7BrDMY4oIW%2FTatlMzB3z7JZ940W%2FJZS1Hwrf0Btc60Kve3oMmGSwsTWgjbSL7tXJjhqgSafA0mYfzHhIJywgmwNHmnFbeV4yU%2Bf0WN3daZlvtDa8Gw2htrdRCZXrlDU92aHIPStA2CKOekMrD5KaWVc02SztIZps%2Bh0rIAg27TXNcpJQYk2ii90VLqt7R3ht%2B4cQoMeVClUIAPd03Th01nvDfx0ClmoJFYk0aouGst82gqROaKskf03KCr7LLvXnXN02K3QTHFaziovYdH0seL5qswitfLZTBq6FGIRfSe9Lm1FTfkY%2BX%2FFcpPAlNRC7eufdFSY1%2BxASh84oo8YitzYXM9IZ%2FuaNcQ1HjMbQc61l0VXDmYlsJVbTYVGq0KwPCi2cf5tQFFnjR2zyDU6YycwX%2Fr3oRzvfKpwTaSZ8NfQUoU%2FUsetanxAV79VElhHbm1oIrSiILcvvgquqSN0Q7y8Uz2TQdjWa5bhZP8IUShEeh8IvIxkVB7SY%2FyKctaIL%2B0kgQrMp8n0SKJ10eWxZ4t%2FBXHUzg4idu6nOnNxsIQ1Yka2D9aDc0sQTNQPJP%2B2sgqvPUrGLERozL68ToNLRELvBj4VuZaOSOy1mmsdAi2dxaWOeyhlRzVl6TYozMnhHIjJLCM5y%2BlwaweHOn96afg%2FuHhnl60ETUvgR1HpJsQntkptrcuO0bOOhuLg1NBPfyH6Swrpw2W9O24rBu8kwH8DuEdns9Kv1hLc5rsxBaTLcN1HIdhHIVRuFov5wtMXH748vO2%2BP0jUzjFXE7%2FbMa3%2BFZl3z1ZxhWyjv2fwlfy9NaY6LhO0lm4WC3WcRSvlqO4UqiXYT7C%2B7vwcT7SWlFAxg3LtMHNfH2ODnZ4kIPVPRo9jnN1r5eDNup%2BIy2y5GxuDrQqYMNb6dje9or44HOyQYTnWs%2FXXoD7%2Ba8WrGO4hwZuK%2B2Qt%2F32tAPhB%2B4xt238qjVQtpIbuuvIP6wbjfAIhStncO3eZ0f9keMHmYHuo%2BCwFoJ%2BDfktdEF0JPfebbxgct30b%2BdhY%2B51u%2FGm2U2IR7rW%2FbJU%2FdcBfpEchHjwoO52%2FwENmVvErwgAAA%3D%3D'>" } ] } ``` A sample view of the newly created Scheduled Tweet is shown above **Associate a Scheduled Tweet with a line item** While Scheduled Tweets can be used to create Organic Tweets, we also allow partners to create a “Promoted-Only” (`nullcast=true`) Tweet either one of which can be associated with a line item. In order to facilitate this, we provide a [POST accounts/:account\_id/scheduled\_promoted\_tweets](https://developer.x.com/content/developer-twitter/en/docs/ads/campaign-management/api-reference/scheduled-promoted-tweets#post-accounts-account-id-scheduled-promoted-tweets) endpoint as well. This endpoint only allows a single Promoted Scheduled Tweet to be associated with a line item in a single API call. In order to associate multiple Scheduled Tweets to the same line item, multiple API calls are necessary. Please note that it is not possible to modify an existing Scheduled Promoted Tweet. ``` twurl -H 'ads-api.x.com' -X POST "/6/accounts/:account_id/scheduled_promoted_tweets" -d 'line_item_id=a44qc&scheduled_tweet_id=917507899668099072' ``` ```json theme={null} { "data": { "line_item_id": "a44qc", "id": "26576", "created_at": "2017-10-09T22:24:16Z", "updated_at": "2017-10-09T22:24:16Z", "scheduled_tweet_id": "917507899668099072", "tweet_id": null, "deleted": false }, "request": { "params": { "line_item_id": "a44qc", "scheduled_tweet_id": 917507899668099100, "account_id": "aaaaa" } } } ``` This endpoint only creates an association between a given Scheduled Tweet and a line item. Once the campaign/line item flight dates are current, the line item with automatically start serving the corresponding “live” Tweet. While we do validate during this step that the Scheduled Tweet is in the `SCHEDULED` state, and that the given Scheduled Tweet is valid for the given objective, no other validations are run. Any remaining validation rules that apply to the line item and Scheduled Tweet are run when the Tweet goes “live” In order to ensure that there are no issues with campaign serving it is recommend that the Scheduled Tweet be `scheduled_at` a time prior to the campaign/line item flight dates. For example, let's say the Scheduled Tweet is set to go live after the campaign start date (and that there is only a single Tweet associated with a single line item), then the campaign will be `ACTIVE`, however given that the Scheduled Tweet is not live yet, there will be no creatives available for serving. **Scheduled Tweet Management** The remaining sets of endpoints allow API consumers to manage all their Scheduled Tweets and Scheduled Promoted Tweets. These APIs can be used to either return a list of all Scheduled Tweets optionally filtered by a given state as well as lookup a given Scheduled Tweet by its `id`. #### What happens when a Scheduled Tweet goes live? Once a given Scheduled Tweet is about to go live, or in other words at the `scheduled_at` time, the following updates are made: * The “live” Tweet is created however this may have a latency of upto 1 second * The `tweet_id` is added to the following entities: * Scheduled Tweet * Promoted Scheduled Tweet * A new Promoted Tweet entity is created #### Best Practices The following best practices are recommended when creating or promoting Scheduled Tweets: * Ensure that the Tweet is valid when creating the Scheduled Tweet (for example, a Tweet can only have either an Image, Video or Gif and not any combination of the three) * Ensure that the campaign flight dates (i.e., the `start_time` and `end_time`) align with the `scheduled_at` time for the Scheduled Tweet * Scheduled Tweets should not be scheduled for more than one year in the future (365 days) * Tweet preview is currently not supported for Scheduled Tweets (this is ability to preview Scheduled Tweets prior to creation) ### Media Library #### Introduction The Media Library endpoints provide the ability to manage images, GIFs, and videos for X Ads accounts. Media assets in the library can be used in Tweets and to create cards. They can also be reused in multiple [creatives](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/overview), eliminating the need to upload the same asset multiple times. #### API Endpoints * [POST media/upload](/x-api/media/upload-media) or [POST media/upload (chunked)](/x-api/media/initialize-media-upload) (upload media) * [POST accounts/:account\_id/media\_library](https://developer.x.com/x-ads-api/creatives#get-accounts-account-id-media-library#post-accounts-account-id-media-library) (add media to the Media Library) #### Adding to the Library Adding media to the library is a two-step process. First, upload the asset using either the [POST media/upload](/x-api/media/upload-media) endpoint or the [POST media/upload (chunked)](/x-api/media/initialize-media-upload) set of endpoints. (See the [Chunked media upload](/x-api/media/quickstart/media-upload-chunked) guide for details on our multi-part upload process.) ``` twurl -X POST -H upload.x.com "/1.1/media/upload.json?additional_owners=756201191646691328" --file latte.jpeg --file-field "media" ``` ```json theme={null} { "media_id":966947208837742592, "media_id_string":"966947208837742592", "size":74194, "expires_after_secs":86400, "image":{ "image_type":"image/jpeg", "w":800, "h":418 } } ``` Next, using the media ID, add the media to the ads account’s library using the [POST accounts/:account\_id/media\_library](https://developer.x.com/x-ads-api/creatives#get-accounts-account-id-media-library#post-accounts-account-id-media-library) endpoint. ``` twurl -X POST -H ads-api.x.com "/9/accounts/18ce54d4x5t/media_library?file_name=latte.jpeg&media_category=TWEET_IMAGE&media_key=966947208837742592&name=Latte" ``` ```json theme={null} { "request":{ "params":{ "name":"Latte", "file_name":"latte.jpeg", "media_category":"TWEET_IMAGE", "account_id":"18ce54d4x5t", "media_key":966947208837742592 } }, "data":{ "tweeted":false, "name":"Latte", "file_name":"latte.jpeg", "media_url":"https://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg", "media_category":"TWEET_IMAGE", "media_key":"3_966947208837742592", "created_at":"2018-02-23T08:05:54Z", "media_status":"TRANSCODE_COMPLETED", "media_key":"966947208837742592", "media_type":"IMAGE", "updated_at":"2018-02-23T08:06:17Z", "deleted":false } } ``` **Note:** Tweeting images, GIFs, or videos directly after the upload also adds media to the library. #### Request Parameters All Media Library POST requests require a media identifier. This value is returned during the upload step. When using the media\_id, as in the example above, a media\_category must also be specified. There are four possible category values: AMPLIFY\_VIDEO, TWEET\_GIF, TWEET\_IMAGE, and TWEET\_VIDEO. Optionally, name and file\_name values can be set for objects in the Media Library. These attributes help users distinguish between media variants in the library. For videos, it’s also possible to set a title and a description. They values are intended to be passed as the video\_title and video\_description request parameters with the [POST accounts/:account\_id/tweet](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet) endpoint. In the Tweet, this text appears under the video. #### Attributes The Media Library, formally introduces the concept of the media\_key. This is the unique identifier for objects in the library. Media keys are string values in the following format: 13\_875943225764098048. These are fully supported in all of our card endpoints. In addition, the Media Library response includes the media\_id, represented as a string. This is included for resources that do not currently accept a media key: [Tweets](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/tweets#post-accounts-account-id-tweet)\*, [Tweet preview](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/tweets#get-accounts-account-id-tweet-preview)\*, and [Scheduled Tweets](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/scheduled-tweets#post-accounts-account-id-scheduled-tweets). We are working toward supporting media keys everywhere. The aspect\_ratio attribute is returned for GIFs and videos. This can be used to filter media for use in cards that only accept particular aspect ratios. \*These endpoints support the video\_id parameter, which is a media key. #### Usage In this section, the following image will be used in a Tweet and to create a website card. ``` twurl -H ads-api.x.com "/9/accounts/18ce54d4x5t/media_library/3_966947208837742592" ``` ```json theme={null} { "request":{ "params":{ "account_id":"18ce54d4x5t", "media_key":"3_966947208837742592" } }, "data":{ "tweeted":false, "name":"Latte", "file_name":"latte.jpeg", "media_url":"https://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg", "media_category":"TWEET_IMAGE", "media_key":"3_966947208837742592", "created_at":"2018-02-23T08:05:54Z", "media_status":"TRANSCODE_COMPLETED", "media_key":"966947208837742592", "media_type":"IMAGE", "updated_at":"2018-02-23T08:06:17Z", "deleted":false } } ``` **Tweet** We can create the Tweet by referencing the images using media\_keys. ``` twurl -X POST -H ads-api.x.com "/9/accounts/18ce54d4x5t/tweet?text=coffee&media_keys=966947208837742592&as_user_id=756201191646691328&trim_user=true" ``` ```json theme={null} { "data":{ "created_at":"Fri Feb 23 08:20:05 +0000 2018", "id":966950781302665218, "id_str":"966950781302665218", "text":"coffee https://t.co/T772Hx5GNT", "truncated":false, "entities":{ "hashtags":[ ], "symbols":[ ], "user_mentions":[ ], "urls":[ ], "media":[ { "id":966947208837742592, "id_str":"966947208837742592", "indices":[ 7, 30 ], "media_url":"http://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg", "media_url_https":"https://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg", "url":"https://t.co/T772Hx5GNT", "display_url":"pic.x.com/T772Hx5GNT", "expanded_url":"https://x.com/apimctestface/status/966950781302665218/photo/1", "type":"photo", "sizes":{ "thumb":{ "w":150, "h":150, "resize":"crop" }, "large":{ "w":800, "h":418, "resize":"fit" }, "medium":{ "w":800, "h":418, "resize":"fit" }, "small":{ "w":680, "h":355, "resize":"fit" } } } ] }, "source":"Ads API Internal Test App", "in_reply_to_status_id":null, "in_reply_to_status_id_str":null, "in_reply_to_user_id":null, "in_reply_to_user_id_str":null, "in_reply_to_screen_name":null, "user":{ "id":756201191646691328, "id_str":"756201191646691328" }, "geo":null, "coordinates":null, "place":null, "contributors":[ 2417045708 ], "retweet_count":0, "favorite_count":0, "favorited":false, "retweeted":false, "possibly_sensitive":false, "scopes":{ "followers":false }, "lang":"en" }, "request":{ "params":{ "as_user_id":756201191646691328, "text":"coffee", "account_id":"18ce54d4x5t", "media_keys":[ 966947208837742592 ], "trim_user":true } } } ``` **Website Card** All of our cards endpoints support media keys. We will create the [website card](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/website#post-accounts-account-id-cards-website) by referencing the image’s media\_key. ``` twurl -X POST -H ads-api.x.com "/11/accounts/18ce54d4x5t/cards" ``` ```json theme={null} { "name": "components create cards", "components": [ { "type": "MEDIA", "media_key": "3_1323490622599176192" }, { "type": "BUTTON", "label": { "type": "ENUM", "value": "INSTALL" }, "destination": { "type": "APP", "country_code": "US", "googleplay_app_id": "com.twitter.android" } } ] } ``` We then associate this card with a Tweet using its card\_uri. ### Identifying Cards #### Introduction Cards are customizable ad formats that use media and that can be associated with a website, an app, or with calls to action to drive certain user engagements, such as starting a Direct Message. They can be appended to Tweets, Scheduled Tweets, or Draft Tweets. Cards may be referenced in Tweet objects in one of two ways: by the card's card\_uri or by its preview\_url. Example values for each are presented below. | card\_uri | preview\_url | | :------------------------- | :----------------------------------------------------------------------------------------- | | card://1043282691834048513 | [https://cards.x.com/cards/18ce54d4x5t/68w3s](https://cards.x.com/cards/18ce54d4x5t/68w3s) | **Note**: As of Ads API version 3, only the card\_uri is generated and returned in the cards response for newly created cards. **Note**: As of Ads API version 5, the preview\_url in the cards response is no longer returned. The type of reference in the Tweet object response will depend on the way the Tweet was created. In other words, if the Tweet was created using the card\_uri request parameter, the card URI value will appear in the response. If the preview\_url was included as part of the Tweet text, on the other hand, the preview URL will appear in the response. #### Identifying Tweets with card\_uri For Tweets created using the card's URI value, find the reference to the card in the card\_uri response attribute. The example response below uses the [GET accounts/:account\_id/tweets](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/tweets#get-accounts-account-id-tweets) endpoint. ``` $ twurl -H ads-api.x.com "/9/accounts/18ce54d4x5t/tweets?trim_user=true&tweet_type=PUBLISHED&tweet_ids=1043551275923591168" { "request": { "params": { "tweet_ids": [ "1043551275923591168" ], "tweet_type": "PUBLISHED", "trim_user": true, "account_id": "18ce54d4x5t" } }, "next_cursor": null, "data": [ { "coordinates": null, "retweeted": false, "source": "Ads API Internal Test App", "entities": { "hashtags": [], "symbols": [], "user_mentions": [], "urls": [] }, "display_text_range": [ 0, 15 ], "favorite_count": 0, "in_reply_to_status_id_str": null, "geo": null, "id_str": "1043551275923591168", "scopes": { "followers": false }, "in_reply_to_user_id": null, "truncated": false, "retweet_count": 0, "scheduled_status": null, "id": 1043551275923591168, "in_reply_to_status_id": null, "nullcast": true, "created_at": "Sat Sep 22 17:23:07 +0000 2018", "place": null, "scheduled_at": null, "tweet_type": "PUBLISHED", "favorited": false, "card_uri": "card://1043282691834048513", "full_text": "Tracking a card", "lang": "en", "contributors": [ 2417045708 ], "in_reply_to_screen_name": null, "in_reply_to_user_id_str": null, "user": { "id": 756201191646691328, "id_str": "756201191646691328" }, "tweet_id": "1043551275923591168" } ] } ``` If using the Standard API, use include\_card\_uri=true in the request. Regardless of which endpoint is used, the card\_uri response attribute will only be rendered if the Tweet was created using a card URI. For scheduled and draft Tweet objects, the response will always include the card\_uri response attribute. #### Identifying Tweets with preview\_url For Tweets created by including the preview URL as part of the Tweet's text, the URL can be found in entities\["urls"]\[i]\["expanded\_url"] (the text field includes a shortened t.co URL), where i is an array index (a Tweet can contain multiple URLs). For scheduled and draft Tweet objects, the preview URL will always appear in the text field. #### Fetching cards To retrieve additional information about a specific card, we provide two endpoints: [GET accounts/:account\_id/cards/all](https://developer.x.com/en/docs/ads/creatives/api-reference/cards-fetch.html#get-accounts-account-id-cards-all) and [GET accounts/:account\_id/cards/all/:card\_id](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/cards-fetch#get-accounts-account-id-cards-all-card-id). The former allows a card to be fetched by card\_uri and the latter by the card's ID. The card's ID is found at the end of the preview\_url. In the example above, the ID is 68w3s. ### Identifying Media #### Introduction Media—images, GIFs, and videos—can be added to Tweets and cards. In addition, videos can be used as pre-roll assets and images can be promoted on the [X Audience Platform](https://developer.x.com/en/docs/ads/measurement/overview/twitter-audience-platform). This section describes how to find media references across these entities. There are two types of media identifiers: IDs and keys. Example values for each are presented below. | **Media ID** | **Media key** | | :------------------ | :---------------------- | | 1029825579531807971 | 13\_1029825579531807971 | The media key is the ID plus a numeric prefix and an underscore. #### Images The following table shows the identifier types currently available in each image-related resource's response as well as the corresponding attribute name(s). | **Resource** | **Identifier** | **Attribute(s)** | | :-------------- | :------------- | :-------------------------------------------------------------- | | Image cards | None | | | Tweet | Both | `entities["media"]["id_str"]` `entities["media"]["media_key"]` | | Scheduled Tweet | Both | `media_ids` and `media_keys` | | Draft Tweet | Both | `media_ids` and `media_keys` | | Account Media | None | | | Media Library | Both | `media_id` and `media_key` | Image cards and Account Media images do not include a reference any media identifier. Tweets only include media IDs. Scheduled and Draft Tweets include both the media ID and media key. The Media Library returns both, too. For Tweets, the id and id\_str fields in the object within the entities\["media"] array correspond to the media ID. In cases where a Tweet includes multiple images, the references to each media entity can only found in extended\_entities\["media"]. In addition to references to identifiers, it's often important to have access to the image's URL. | **Resource** | **Attribute(s)** | **Format** | | :-------------- | :---------------------------------------------------------------------------------- | :--------- | | Image cards | `image` | .jpg | | Tweet\* | `entities["media"][0]["media_url"]` or `extended_entities["media"][i]["media_url"]` | .jpg | | Scheduled Tweet | None | | | Draft Tweet | None | | | Account Media | `media_url` | .jpg | | Media Library | `media_url` | .jpg | \* This URL locations depend on whether the Tweet contains a single image or multiple images. All image cards include an image response attribute that contains the X image URL. (For image app download cards, the name is wide\_app\_image.) For Tweets, the media URL location depends on both the type of media and the endpoint being used. For Tweets with a single image, the URL can be found in entities\["media"]\[0]\["media\_url"]. This is true for both the Ads API and the Standard API. When Tweets contain multiple images, however, the URLs can only be found extended\_entities\["media"]\[i]\["media\_url"]. This is only available in the Standard API. #### Videos The following table shows the identifier types currently available in each video-related resource's response as well as the corresponding attribute name(s). | **Resource** | **Identifier** | **Attribute(s)** | | :--------------- | :------------- | :-------------------------------------------------------------- | | Video cards | May be either | `video_content_id` | | Video poll cards | None | | | Tweet | Both | `entities["media"]["id_str"]` `entities["media"]["media_key"]` | | Scheduled Tweet | Both | `media_ids` and `media_keys` | | Draft Tweet | Both | `media_ids` and `media_keys` | | Account Media | Media key | `video_id` | | Media Library | Both | `media_id` and `media_key` | While video cards (with the exception of poll cards with video) include a video\_content\_id response attribute, there is inconsistency in the type of value returned. In some cases, it's a media ID; in others, it's a media key. Information about how to access the video's URL is shown below. | **Resource** | **Attribute(s)** | **Format** | | :--------------- | :------------------------------------------------------------------ | :----------- | | Video cards | `video_url` and `video_hls_url` | .vmap .m3u8 | | Tweet with video | `extended_entities["media"][i]["video_info"]["variants"][j]["url"]` | .mp4 | | Scheduled Tweet | None | | | Draft Tweet | None | | | Account Media | None | | | Media Library | `media_url` | .mp4 | Video cards include video\_url and video\_hls\_url response attributes with .vmap and .m3u8 URLs, respectively. #### Media Library It's sometimes necessary to retrieve additional information about a media asset. One use case, for video cards, is retrieving the mp4 URL instead of the vmap one. This is available in the Media Library. For details on the available information, see our [Media Library Guide](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/guides/media-library). Most assets belonging to the ads account's FULL promotable user can be found in the library. There are some exceptions, though. **Fetching media** As stated above, image cards do not contain references to either media IDs or media keys. As a result, it's not possible to fetch their assets through the Media Library. This is also true for [Account Media](https://developer.x.com/content/developer-twitter/en/docs/ads/creatives/api-reference/account-media#account-media) images. Video cards require that the video asset be part of the Media Library (or the Videos resource before it) prior to creating it. As a result, these assets will always be retrievable in the Media Library. This is also true for Account Media PREROLL assets. Finally, media in Tweets are always guaranteed to be in the Media Library. The following table summarizes which assets are retrievable in the Media Library, taking into account whether the resource response includes an identifier to use in the lookup. | **Resource** | **In the Media Library** | | :------------------------------- | :----------------------- | | Image cards | No | | Video cards | Yes\* | | Tweets (any media)\*\* | Yes | | Scheduled Tweets | Yes | | Draft Tweets | Yes | | Account media images | No | | Account media videos (`PREROLL`) | Yes | \* For cards where the `video_content_id` is a media key. When the value is a media ID, the asset still exists in the Media Library, but retrieving it involves appending a numeric prefix and underscore to it. \*\* Tweets only return media IDs. While the asset is guaranteed to exist in the Media Library, fetching it involves appending a numeric prefix and underscore to it. **Interactions with Account Media** There are two cases where media assets added to the library are automatically added to the Account Media resource. * When an AMPLIFY\_VIDEO asset is added to the Media Library, it is automatically added as an Account Media asset as a PREROLL creative type. * When images that have specific dimensions (see "Creative Types" in our [enumerations page](https://developer.x.com/content/developer-twitter/en/docs/ads/general/overview/enums)) are added to the Media Library, they are automatically added as Account Media assets. The creative type (e.g., INTERSTITIAL) depends on the image dimensions. ### Tweets #### Introduction The X Ads API supports three types of Tweets: published, scheduled, and draft. #### Nullcasted Tweets Tweets may either be nullcasted (a.k.a. "Promoted-only") or organic. Nullcasted Tweets, once published, do not appear in the user's public timeline, though they are public. Organic Tweets, on the other hand, are served to the user's followers and do appear in the user's public timeline. **Creating Tweets** Each of the three Tweet create endpoints supports a Boolean nullcast parameter that gives the API user the option to create nullcasted or organic Tweets. Nullcasted Tweets can be created by the user or by anyone who has permission to create Tweets on the user's behalf. Organic Tweets can only be created by the [full promotable user](https://developer.x.com/content/developer-twitter/en/docs/tutorials/ads-api-hierarchy-terminology#promotable-users). **Updating Tweets** It is possible to update the nullcast property for scheduled and draft Tweets. For scheduled Tweets, edits can be made until the Tweet's scheduled\_at time. Draft Tweets can be edited indefinitely. Once published, though, it's not possible to change a Tweet from nullcasted to organic or vice versa. #### Promoting Tweets Only published and scheduled Tweets may be promoted. These can either be nullcasted or organic; there's no restriction. An advertiser may promote their own Tweets or another user's Tweets as long as they've obtained permission to do so. (See: [Promoting another user's Tweets](https://developer.x.com/content/developer-twitter/en/docs/tutorials/promoting-another-users-content) for more information.) Multiple Tweets can be promoted in a single campaign. Similarly, a single Tweet may be promoted in one or more campaigns. To promote published Tweets, use the [POST accounts/:account\_id/promoted\_tweets endpoint](https://developer.x.com/content/developer-twitter/en/docs/ads/campaign-management/api-reference/promoted-tweets#post-accounts-account-id-promoted-tweets). This associates published Tweets with a line item. To promote scheduled Tweets, use the [POST accounts/:account\_id/scheduled\_promoted\_tweets](https://developer.x.com/content/developer-twitter/en/docs/ads/campaign-management/api-reference/scheduled-promoted-tweets#post-accounts-account-id-scheduled-promoted-tweets) endpoint. #### Tweet IDs Published, scheduled, and draft Tweet IDs are [numeric](https://developer.x.com/content/developer-twitter/en/docs/basics/twitter-ids)—they are 64-bit unsigned integers. For example, the following published Tweet's ID is 1166476031668015104. When published or scheduled Tweets are promoted, a corresponding promoted Tweet entity is created. These entities have their own IDs, which are alpha-numeric and are represented as base-36-encoded values. For example, promoting the published Tweet above—that is, associating it a line item 6c62d—returns the following API response. ``` $ twurl -X POST -H ads-api.x.com "/9/accounts/18ce54d4x5t/promoted_tweets?line_item_id=6c62d&tweet_ids=1166476031668015104" { "request": { "params": { "tweet_ids": [ 1166476031668015104 ], "line_item_id": "6c62d", "account_id": "18ce54d4x5t" } }, "data": [ { "line_item_id": "6c62d", "id": "3qwlq6", "entity_status": "ACTIVE", "created_at": "2019-09-12T21:39:10Z", "updated_at": "2019-09-12T21:39:10Z", "approval_status": "ACCEPTED", "tweet_id": "1166476031668015104", "deleted": false } ], "total_count": 1 } ``` In addition to the Tweet ID and the line item ID, which were passed into the create request, the response includes an id field with a value of 3qw1q6, which is the promoted Tweet ID. ### Carousels #### Introduction The X Ads API supports creating and retrieving video carousels and image carousels. The carousel is a card type that can contain between 2 and 6 media assets. The carousel card can direct a user to a website or encourage them to install a mobile app. For more information about carousels, their benefits, best practices, and FAQs, see our [Carousel Ads on X](https://business.x.com/en/advertising/carousels.html) page. A carousel, like any other card type, can be used in Tweets and those Tweets can then be promoted. The workflow is the same as what you're already used to: 1. Upload media 2. Create the card 3. Create the Tweet 4. Promote the Tweet The only difference is with how the card is created. While other card create requests accept query parameters, carousel card create requests only accept JSON POST bodies. #### Endpoints The Ads API supports creating and retrieving carousels. To create a carousel—any kind—use the [POST accounts/:account\_id/cards](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/cards#post-accounts-account-id-cards) endpoint. To retrieve carousels, use the [GET accounts/:account\_id/cards](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/cards#get-accounts-account-id-cards) endpoint. #### JSON POST Body Carousels are created using two components. The first specifies the media assets that will be used. The second specifies information about either the website or the app. Specifically, a carousel card is created by using the following components, in order: * One `SWIPEABLE_MEDIA`component, which accepts an array of media keys * *One* of the following: * A `DETAILS` component to specify website information * A `BUTTON` component to specify app information The `SWIPEABLE_MEDIA` component must include a `media_keys` array where you can specify between 2 and 6 images or videos. The order in which the media keys are passed in determine the order in which they will be rendered. ``` { "type": "SWIPEABLE_MEDIA", "media_keys": [ "13_1089771253848666112", "13_1191948012077092867" ] } ``` As a reminder, you can obtain media keys by making a request to the [GET accounts/:account\_id/media\_library](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/media-library#get-accounts-account-id-media-library) endpoint. The composition of the second component object depends on whether you wish to direct a user to a website or encourage them to install an app. The table below summarizes the two options. (**Note**: all of the listed keys are required.) | | **Website** | **App** | | :------------------------- | :----------------------------------------------------------------- | :------------------------------------------------ | | Specify the component type | `"type": "DETAILS"` | `"type": "BUTTON"` | | Title/Label | `"title": "X"` | `"label": { "type": "ENUM", "value": "INSTALL" }` | | Destination | `"destination": { "type": "WEBSITE", "url": "https://www.x.com" }` | `"destination": { "type": "APP", ... }` | Putting this together, an example website carousel JSON POST body is shown below. ``` { "name": "website carousel", "components": [ { "type": "SWIPEABLE_MEDIA", "media_keys": [ "13_1089771253848666112", "13_1191948012077092867" ] }, { "type": "DETAILS", "title": "X", "destination": { "type": "WEBSITE", "url": "https://www.x.com" } } ] } ``` App destination objects within `BUTTON` components require a country code and at least one app identifier. They optionally accept deep links. For a description of these fields, see the [reference documentation](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/cards#app-destination). Putting this together, an example app carousel JSON POST body is shown below. ``` { "name": "app carousel", "components": [ { "type": "SWIPEABLE_MEDIA", "media_keys": [ "13_1089771253848666112", "13_1191948012077092867" ] }, { "type": "BUTTON", "label": { "type": "ENUM", "value": "INSTALL" }, "destination": { "type": "APP", "country_code": "US", "googleplay_app_id": "com.twitter.android", "iphone_app_id": "333903271" } } ] } ``` #### Example This section demonstrates how to create a video website carousel card and how to use it in a Tweet. As mentioned above, the workflow is the same as what you're already used to: upload media, create the card, create the Tweet. The only difference is how the card is created. **Media** To start, either upload new media assets or use existing ones. For details on how to upload new media assets and add them to the Media Library, see our [Media Library Guide](https://developer.x.com/en/docs/twitter-ads-api/creatives/guides/media-library). Once your media assets are in the Media Library, fetch them using the [GET accounts/:account\_id/media\_library](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/media-library#get-accounts-account-id-media-library) endpoint. Use the `media_type` request parameter to scope the results to a particular media type. ``` $ twurl -H ads-api.x.com "/10/accounts/18ce54d4x5t/media_library?media_type=VIDEO" ``` ``` { "request": { "params": { "account_id": "18ce54d4x5t", "media_type": "VIDEO" } }, "next_cursor": null, "data": [ { "tweeted": true, "duration": 5283, "name": "Sunrise", "file_name": "sunrise.mp4", "description": null, "media_url": "https://video.twimg.com/amplify_video/1089771253848666112/vid/1280x720/tyL-pUBP7GgkS9bl.mp4?tag=9", "poster_media_key": "3_1089771253848666112", "media_key": "13_1089771253848666112", "created_at": "2019-01-28T06:24:48Z", "media_status": "TRANSCODE_COMPLETED", "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/1089771253848666112/img/WOYvToSRZFXUSDzd.jpg", "title": null, "media_type": "VIDEO", "aspect_ratio": "16:9", "updated_at": "2019-08-23T19:05:33Z", "deleted": false }, { "tweeted": true, "duration": 15248, "name": "snow", "file_name": "snow.mp4", "description": "Two, three, and to the four", "media_url": "https://video.twimg.com/amplify_video/1191948012077092867/vid/1280x720/2cOvadcctqqea6Hx.mp4?tag=13", "poster_media_key": "3_1191948012077092867", "media_key": "13_1191948012077092867", "created_at": "2019-11-06T05:18:46Z", "media_status": "TRANSCODE_COMPLETED", "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/1191948012077092867/img/IUbhTRd62SEeIVTf.jpg", "title": "One", "media_type": "VIDEO", "aspect_ratio": "16:9", "updated_at": "2020-03-27T22:23:18Z", "deleted": false } ] } ``` **Carousel Creation** Use the [POST accounts/:account\_id/cards](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/cards#post-accounts-account-id-cards) endpoint to create your carousel. Use the media keys from the previous request. Remember, the order in which the media keys are passed in determine the order in which they are rendered. ``` $ twurl -A "Content-Type: application/json" -X POST -H ads-api.x.com "/10/accounts/18ce54d4x5t/cards" -d '{"name":"website carousel","components":[{"type": "SWIPEABLE_MEDIA","media_keys":["13_1089771253848666112","13_1191948012077092867"]},{"type": "DETAILS","title": "X","destination":{"type":"WEBSITE", "url":"https://www.x.com"}}]}' ``` ``` { "request": { "params": { "account_id": "18ce54d4x5t" } }, "data": { "name": "website carousel", "components": [ { "type": "SWIPEABLE_MEDIA", "media_keys": [ "13_1089771253848666112", "13_1191948012077092867" ] }, { "type": "DETAILS", "title": "X", "destination": { "type": "WEBSITE", "url": "https://www.x.com/", "tco_url": "https://t.co/dyTMHWKWZb" } } ], "id": "ars7m", "created_at": "2020-11-11T07:51:47Z", "card_uri": "card://1326432421105995776", "updated_at": "2020-11-11T07:51:47Z", "deleted": false, "card_type": "UNIFIED" } } ``` Notice that like with other cards, the carousel card response includes a `card_uri`, which will be used when creating a Tweet. **Tweet** Use the [POST accounts/:account\_id/tweet](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/tweets#post-accounts-account-id-tweet) endpoint to create your Tweet. Use the `card_uri` from the previous request. (Response truncated for readability.) ``` $ twurl -H ads-api.x.com "/9/accounts/18ce54d4x5t/tweet_previews?tweet_type=PUBLISHED&tweet_ids=1326434098324385792" ``` ``` { "data": { "created_at": "Wed Nov 11 07:58:27 +0000 2020", "id": 1326434098324385792, "id_str": "1326434098324385792", "text": "Swipe", "truncated": false, "entities": { "hashtags": [], "symbols": [], "user_mentions": [], "urls": [] }, "source": "Ads API Internal Test App", "in_reply_to_status_id": null, "in_reply_to_status_id_str": null, "in_reply_to_user_id": null, "in_reply_to_user_id_str": null, "in_reply_to_screen_name": null, "user": { "id": 756201191646691300, "id_str": "756201191646691328", ... }, "geo": null, "coordinates": null, "place": null, "contributors": [ 2417045708 ], "retweet_count": 0, "favorite_count": 0, "favorited": false, "retweeted": false, "possibly_sensitive": false, "scopes": { "followers": false }, "lang": "en" }, "request": { "params": { "text": "Swipe", "as_user_id": 756201191646691300, "card_uri": "card://1326432421105995776", "account_id": "18ce54d4x5t" } } } ``` **Tweet Previews** Use the [GET accounts/:account\_id/tweet\_previews](https://developer.x.com/en/docs/twitter-ads-api/creatives/api-reference/tweet-previews#get-accounts-account-id-tweet-previews) endpoint to see your Tweet. ### creative-metadata-tagging #### Introduction This guide is for creative partners, agencies and creative developers to tag assets used within X campaigns to better understand individual asset value and performance. **Note:** Media assets must only be tagged by the partner or developer creating the media asset. If the user of the media asset did not create the media asset, do not implement metadata tagging. Creative Metadata Tagging provides attribution of images and videos created by Creative Partners wherever the asset is uploaded to X, or whomever the entity that is uploading the asset. To create the connection between the creative asset and the creative partner, the [XMP](https://exiftool.org/TagNames/XMP.html) standard is used. #### Tagging Creative Assets The following table shows the identifier types currently available in each image-related resource's response as well as the corresponding attribute name(s). A tagging tool is needed to tag creative assets. [ExifTool](https://exiftool.org/), a platform-independent Perl library plus a [command-line application](https://exiftool.org/exiftool_pod.html) for reading, writing, and editing meta information, is recommended. See all supported [file types](https://exiftool.org/#supported). Follow the provided [instructions to install ExifTool](https://exiftool.org/install.html). There are also software packages offered by [Homebrew](https://formulae.brew.sh/) to further simplify the installation by providing the [exiftool install command](https://formulae.brew.sh/formula/exiftool) for macOS and Linux. Confirm your tool is properly installed by entering exiftool -ver in the command line to return the tool’s version number. Learn more about ExifTool command parameters in [ExifTool documentation](https://exiftool.org/). Creative partners can assign metadata tags on new or existing creative assets with their X app\_id to the contributor XMP tag, and date tag. The creative assets will follow the existing size restrictions when [Uploading Media](/x-api/media/upload-media). **Note:** X's use of the contributor XMP tag ensures metadata captures values for campaigns on X exclusively. `exiftool -contributor="