Support > X Ads API
X Ads API
The X Ads API connects developers to X's advertising platform. Build solutions to meet the needs of advertisers around the world.
Review our Gettings Started documentation to find out what’s possible to build with the different tools that are available on the Ads API platform, and how to get the access and information that you need to get started.
We also have a series of Quick Links to help you get started:
- Campaign Management (API Index)
- Pull campaign metadata and create or manage campaigns, ad groups, and ads.
- Do GETs, POSTs, or PUTS on Campaigns, Line_items, Promoted posts, and posts. Note that posts and targeting are associated with the line_item. Once a post is associated with a line_item, a promoted_tweet ID is generated.
- Analytics (API Index)
- Use our Active Entities guide to determine what data changed within a specific time period.
- Sync endpoint should be used for data within the last 7 Days.
- Async can handle up to 90 day chunks and supports segmentation. Guide here. Use async data to store historical metrics.
- View Metrics and Segmentation for list of all metrics and their associated metric groups.
- Creatives (API Index)
Upload media, create Cards, and create posts for organic or promoted use.- Media
- Use POST media/upload for images or POST media/upload (chunked) for video to upload to an account.
- Associate the media to the Media Library.
- Cards
- We highly recommend you create cards for your posts. Video Website Cards, for example, is a great creative to drive users to a website with a video.
- posts
- You can create Draft posts to try out creatives.
- Scheduled posts are great for making posts ahead of time.
- Create or Pull posts.
- Preview posts to preview published, scheduled, or draft post with an iframe.
- Media
- Tailored Audiences (API Index) - Learn more
- Use our Audience API to make changes to audiences. Guide here.
- Ensure you are normalizing and hashing user data properly.
Our API status page contains up-to-date information about the X Ads API and highlights ongoing and past incidents.
Accessing the X Ads API requires a set of credentials you must pass with each API request. Your credentials consist of a set of keys and tokens that are generated when you first create an App in your developer dashboard. If you don’t yet have a developer account, you can apply for one.
Any users that had authorized your App via 3-legged-oauth prior to Ads API allowlisting will need to reauthorize your App to regenerate user access tokens with the permissions to access advertiser data. Please wait for your Ads API approval email before doing this.
It is important that you store your keys and tokens securely. In January 2020, we stopped showing your access token and access token secret in your X developer App dashboard beyond the first time that these credentials were generated.
If you lose your tokens, or believe that they have been compromised, you can regenerate your keys and tokens via the App dashboard. Note that regenerating your keys and tokens will invalidate any previous keys and tokens and you may need to rewrite and/or redeploy existing code.
Read more about storing your keys and tokens securely and authentication best practice.
Review our documentation for tips on how to avoid being rate limited or how to know where your App is at for a given rate limit.
All endpoints require authentication, so there is no concept of unauthenticated calls and rate limits.
Use the X community forum to get support from a global network of developers and X employees.
If you belong to a X Official Partner organization, please contact your Partner Manager directly for technical support options.
Successful responses are indicated with a 200-series HTTP code and a JSON-based payload containing the object(s) requested, created, modified, or deleted along with an expression of the server’s interpretation of your request.
Error responses are served with a non-200-series HTTP code. Different error codes indicate different reasons for an error.
The X API attempts to return appropriate HTTP status codes for every request.
Code
Text
Description
200
OK
Success!
304
Not Modified
There was no new data to return.
400
Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further. Requests without authentication are considered invalid and will yield this response.
401
Unauthorized
There was a problem authenticating your request. This could be due to missing or incorrect authentication credentials. This may also be returned in other undefined circumstances.
403
Forbidden
The request is understood, but it has been refused or access is not allowed. An accompanying error message will explain why. This code is used when requests are being denied due to update limits.
404
Not Found
The URI requested is invalid or the resource requested, such as a user, does not exist.
406
Not Acceptable
Returned when an invalid format is specified in the request.
410
Gone
This resource is gone. Used to indicate that an API endpoint has been turned off and is no longer available.
422
Unprocessable Entity
Returned when the data is unable to be processed (for example, if an image uploaded to POST account/update_profile_banner is not valid, or the JSON body of a request is badly-formed).
429
Too Many Requests
Returned when a request cannot be served due to the App's rate limit having been exhausted for the resource. See Rate Limiting.
500
Internal Server Error
Something is broken. This is usually a temporary error, for example in a high load situation or if an endpoint is temporarily having issues. Check the X API status page or the developer community forum in case others are having similar issues, or try again later.
502
Bad Gateway
X is down, or being upgraded.
503
Service Unavailable
The X servers are up, but overloaded with requests. Try again later.
504
Gateway timeout
The X servers are up, but the request couldn’t be serviced due to some failure within the internal stack. Try again later.
The Ads API uses error enums vs error codes found in X Labs and other X APIs. For a full list of errors please see the Error Codes and Responses documentation.
The UI is in base-10 when the API is in base-36. Read more.
Search the X community forum to browse answers to other frequently asked questions. Review our guide on how to get your question answered before you post a new question.
Please view the Ads API Agreement.
By agreeing to the X Ads Products and Services Agreement, you agree to the X Privacy Policy, Terms of Service, Developer Agreement and Policy, Trademark and Brand Guidelines, and applicable X Master Services Agreement. You also agree to the X Ads policies, including those for Conversion Tracking and Tailored Audiences, and X's Data Processing Addendum.
The X community forum is available for you to ask technical questions about the X developer platform. This is a discussions forum where you will find questions by other developers and technical information on a variety of topics related to using the X Ads API.
We encourage you to join the conversation by responding to questions and engaging in conversations on our forum. X employees are also there to provide support.
Before posting a new question, please review this guide designed to help you get answers quickly.