Support > Twitter Ads API
Twitter Ads API
The Twitter Ads API connects developers to Twitter'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 Tweets, and Tweets. Note that Tweets and targeting are associated with the line_item. Once a Tweet 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 Tweets 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 Tweets. Video Website Cards, for example, is a great creative to drive users to a website with a video.
- Tweets
- You can create Draft Tweets to try out creatives.
- Scheduled Tweets are great for making Tweets ahead of time.
- Create or Pull Tweets.
- Preview Tweets to preview published, scheduled, or draft Tweet 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 Twitter Ads API and highlights ongoing and past incidents.
Accessing the Twitter 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 Twitter 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 Twitter community forum to get support from a global network of developers and Twitter employees.
If you belong to a Twitter 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 Twitter 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 Twitter API status page or the developer community forum in case others are having similar issues, or try again later.
502
Bad Gateway
Twitter is down, or being upgraded.
503
Service Unavailable
The Twitter servers are up, but overloaded with requests. Try again later.
504
Gateway timeout
The Twitter 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 Twitter Labs and other Twitter APIs. For a full list of errors please see the Error Codes and Responses documentation.
We strive to review applications within 14 days of submission. You will receive a confirmation email with your application status within this time. If it has been more than 14 days, you are unable to find an approval or rejection email, and you are unsure about your App status, please reach out via adsapi-program@twitter.com. Please include your App ID in your inquiry.
The UI is in base-10 when the API is in base-36. Read more.
Search the Twitter 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 Twitter Ads Products and Services Agreement, you agree to the Twitter Privacy Policy, Terms of Service, Developer Agreement and Policy, Trademark and Brand Guidelines, and applicable Twitter Master Services Agreement. You also agree to the Twitter Ads policies, including those for Conversion Tracking and Tailored Audiences, and Twitter's Data Processing Addendum.
The Twitter community forum is available for you to ask technical questions about the Twitter 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 Twitter Ads API.
We encourage you to join the conversation by responding to questions and engaging in conversations on our forum. Twitter employees are also there to provide support.
Before posting a new question, please review this guide designed to help you get answers quickly.