Developer Support

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.

  • General
  • Errors
  • FAQ
  • Policy
  • Community

Getting started

Getting started

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:

API status

API status

Our API status page contains up-to-date information about the Twitter Ads API and highlights ongoing and past incidents.

Using your keys and tokens

Using your keys and tokens

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.

API limits and caps

API limits and caps

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.

Get help

Get help

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.

Error codes and responses

Error codes and responses

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.

API status codes

API status codes

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.

Troubleshooting error codes

Troubleshooting error codes

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.

Is my App on the allowlist for the Twitter Ads API?

Is my App on the allowlist for the Twitter Ads API?

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.

Why are campaign IDs different in the ads.twitter.com UI compared to the API?

Why are campaign IDs different in the ads.twitter.com UI compared to the API?

The UI is in base-10 when the API is in base-36. Read more.

 

Question still not answered

Question still not answered

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 AgreementYou 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.