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

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

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