Twitter Ads API

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:

• Hierarchy & Glossary

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

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

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

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