Twitter (X) Ads API: what it does, how to get access, and what it cannot read
This page is about X's advertiser API, the one that runs campaigns and reports ad performance. It is a different product from the X API that reads posts and profiles, which our guides to the official API and to free Twitter analytics cover; here the subject is what the Ads API does, how access is granted today, and where its reach stops.
The most common question about it on developer forums is the plain one: how do I get access? The answer changed when X moved its docs to docs.x.com and its developer sign-up to console.x.com, and older answers still point to retired pages. Everything below was read from X's own documentation this session, and the numbers about how the Ads API is discussed on X come from a small study we ran on public posts, collected in 2026.
What the X Ads API does
X describes the Ads API as the way to connect developers to its advertising platform. The docs group it into five product areas, each with its own reference: campaign management, custom audiences, creatives, lead generation and advertising analytics. A sixth area, catalog management, feeds product catalogs to Dynamic Product Ads, and conversion endpoints (web and mobile app) report events back so campaigns can optimize for them.
The scope is always an ad account. Advertising accounts are registered on business.x.com and appear in almost every Ads API URL as the in-line :account_id. The authenticated X user is the current user, and GET accounts returns only the ad accounts that user has been granted. That is the key to what the API can and cannot see, which the section on limits below spells out.
It is read and write. Both access tiers are described in X's docs as read and write. The API creates and edits campaigns, uploads audience lists, publishes promoted-only posts and cards, and records conversions, and it reads back the configuration and the stats of all of those objects.
How to get access to the Twitter Ads API
X's step-by-step guide lists three steps, and the third is the one that matters. The first two give you basic X API credentials; the Ads API is a separate approval on top.
Step 1: developer account. Sign up at console.x.com. Inside the Developer Console you create a developer App, which issues the credentials every request is signed with.
Step 2: save the App's keys and tokens. The App gives you API keys (consumer keys), access tokens for your own X account and a bearer token. X notes that keys and tokens are shown only once and do not expire unless regenerated, so store them in a secrets manager. Write down the App ID from the App details URL; the access request asks for it.
Step 3: submit the Ads API Access Form for each App. The form is linked from docs.x.com/x-ads-api/introduction, and the introduction says to allow up to 3 business days for review. The form page on docs.x.com/forms/ads-api-access points to help.x.com/en/forms/xdev/conversion-api-request, and it asks for your details, intended use case and App information. In the form you choose the access level.
After approval, regenerate user tokens. The guide warns that once an App is approved you need to regenerate any user access tokens before Ads API calls authenticate properly. Teams that skip this step see authorization errors on calls the approval should have unlocked.
Apps approved before July 2023 may have older, narrower permissions (Analytics read-only, Campaign Management and Creative, Custom Audiences, or Conversion) and may be limited to five OAuth user tokens. X's increasing-access page says those are now folded into Standard Access, and that you ask your X representative to move up or lift the token limit. The same page states that X does not increase Ads API rate limits.
Expect a wait anyway. In our sample of public posts that name the Ads API, the most common topic from 2023 on was getting access: 16 of 61 posts (26.2%). Several posts from 2025 describe waiting longer than the review window they had been promised, and at least one from 2026 asks X staff publicly to approve a pending App. Treat the review time as a minimum when you plan a launch.
Authentication, ad-account roles and the sandbox
OAuth 1.0a on every call. The Ads API is served only over HTTPS at ads-api.x.com, and X's docs state that every HTTP call must carry an OAuth 1.0a Authorization header. X recommends using an existing OAuth 1.0a library rather than writing request signing yourself. The App's own static access token works when you only manage the ad account that owns the App; for anyone else's account you run a 3-legged OAuth flow (or PIN-based OAuth when you have no public web UI) and store the resulting user token. X also says developers should never ask advertisers for their login credentials.
Two ways to reach an advertiser's account. You can act with the advertiser's own token (recommended by X), or the advertiser can add your @username to their ad account at business.x.com, after which your own token reaches it. The second route is how agencies manage many accounts; it can create promoted-only posts only if the advertiser also grants the post composer permission.
Roles decide what a token may call. Each user on an ad account holds one of five account-level roles: Account administrator, Ad manager, Campaign analyst, Organic analyst or Creative Manager. X tells apps to read the current user's permissions from the authenticated user access endpoint before calling anything. Two concrete rules from the docs: web conversion calls need an Account administrator or Ad manager token, and lead exports are restricted to Account administrators because the files contain personal information.
Test in the sandbox first. Pointing your client at ads-api-sandbox.x.com gives you an environment where campaigns are never served. Sandbox-only endpoints create a test ad account (POST accounts), add features and add a test funding instrument, so you can exercise campaign creation without a real card or a real budget.
Versions live in the path. Requests look like https://ads-api.x.com/12/accounts. X's versioning table lists version 12 as introduced on October 27, 2022, with no deprecation date set, and version 11 (March 31, 2022) as still listed without an end-of-life date. Every response carries an x-current-api-version header, and deprecated calls add x-api-warn.
# X's own Ads API (not TwitterAPI.io): list your ad accounts, then pull one day of line-item stats.
# Needs an app approved for Ads API Standard Access and OAuth 1.0a user tokens regenerated after approval.
import os
from datetime import datetime, timedelta, timezone
from requests_oauthlib import OAuth1Session
x = OAuth1Session(
os.environ["X_CONSUMER_KEY"], os.environ["X_CONSUMER_SECRET"],
os.environ["X_ACCESS_TOKEN"], os.environ["X_ACCESS_TOKEN_SECRET"],
)
ADS = "https://ads-api.x.com/12"
accounts = x.get(f"{ADS}/accounts").json()["data"]
account_id = accounts[0]["id"]
# Yesterday, whole hours in UTC (start/end must align with the granularity).
end = datetime.now(timezone.utc).replace(minute=0, second=0, microsecond=0)
start = end - timedelta(days=1)
stats = x.get(
f"{ADS}/stats/accounts/{account_id}",
params={
"entity": "LINE_ITEM",
"entity_ids": "YOUR_LINE_ITEM_ID",
"start_time": start.strftime("%Y-%m-%dT%H:%M:%SZ"),
"end_time": end.strftime("%Y-%m-%dT%H:%M:%SZ"),
"granularity": "HOUR",
"metric_groups": "ENGAGEMENT,BILLING",
"placement": "ALL_ON_TWITTER",
},
)
print(stats.status_code, stats.headers.get("x-rate-limit-remaining"))
print(stats.json())Rate limits and analytics windows
The Ads API reports its limits in response headers rather than in a programmatic index. There are two layers: a user-token limit (x-rate-limit-* headers) and, on a subset of GET endpoints, an ad-account limit (x-account-rate-limit-*), which should take precedence when present. These are the published numbers from X's rate-limit chart.
Analytics comes in two shapes. The synchronous stats endpoint returns metrics in the response and covers a time range of up to 7 days; it suits real-time optimization and user-interface requests. The asynchronous endpoints create a job, then hand you a gzip results file; they cover 90 days non-segmented or 45 days segmented, allow up to 100 concurrent jobs per ad account, and are the only way to get segmented data (metrics broken out by a targeting value). X tells developers to onboard new accounts with the async endpoints only.
Spend settles late. The analytics FAQ says spend metrics are generally final within 3 days, but billing data is processed for up to 14 days after the event, and billed_charge_local_micro is an estimate for up to 3 days. A dashboard that stores yesterday's spend once and never re-reads it will drift from the invoice.
Entities and placements. Analytics accepts CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, PROMOTED_ACCOUNT and PROMOTED_TWEET, and one placement per request: ALL_ON_TWITTER, SPOTLIGHT or TREND. If totals look low next to the Ads Manager UI, the FAQ's first suggestion is to request all three placements.
X Ads MCP: the Ads API for AI agents
X now documents a remote MCP (Model Context Protocol) server built into its API gateway at https://ads-api.x.com/mcp. Any MCP-capable client can connect and discover 74 X Ads tools without a custom Ads API integration: tools such as list_ads_accounts, list_campaigns, get_account_stats, estimate_audience, create_custom_audience and create_card.
Same scope, different auth. The MCP server authenticates with the user's own OAuth 2.0 token, so an agent sees only the ad accounts that user can access, exactly as with the REST API.
Writes start paused. X's page states that campaigns and line items created through the MCP server are always created PAUSED, and nothing spends money until someone activates them explicitly. That is the right default for an agent; keep a human approval step before activation anyway.
It is what people are talking about. In our sample, AI agents and the Ads MCP were the second most common topic of recent posts that name the Ads API (14 of 61, 23.0%), and the single largest topic among the 27 posts from 2026 (10 posts). The MCP server does not change what data the Ads API holds, though: it still has no tool for searching public posts.
If you want an agent that both manages ads and reads the organic conversation, give it two MCP servers: X's Ads MCP for the ad account and a data MCP server for public posts. Our guide to the TwitterAPI.io MCP server covers the second half.
What the Ads API cannot do (and where organic data comes from)
Every Ads API object hangs off an ad account. That makes the boundaries simple to state.
No public search. There is no endpoint that searches all public posts for a keyword, a hashtag or a brand name. Targeting endpoints let you target keywords; they do not return the posts that contain them.
No arbitrary timelines, mentions or followers. You can list posts of the account's promotable users, but not the timeline of a competitor, the mentions of a brand, the replies under a viral post, or a follower list.
Analytics are ad analytics. Stats come back for the entity types above, inside accounts your token can reach. Organic reach of a post that was never promoted, or the conversation that a campaign started among people who never saw the ad, is outside the API.
Access is tied to accounts and approval. You need a developer App, an Ads API approval and an advertiser who grants you a role. That is correct for an API that spends money, and it is overhead you do not need when the goal is reading public data.
Few people expect it to. Only 1 of the 61 recent posts in our sample mixed the Ads API up with organic data or scraping. The likelier trap is the word analytics, which suggests reports on any post; in the Ads API it means ad entities only.
Reading the organic side: X API vs TwitterAPI.io, prices
Campaign teams usually want both halves: spend and conversions from the Ads API, and the public conversation around a launch from a data API. For the data half you have two choices, and the price difference is large.
About 33x per 1,000 posts. $5 on X's pay-per-usage rate card against $0.15 on TwitterAPI.io is a ratio of about 33. X's rate card also gives $20 of credits when you save a first card and buy credits, and matches a first auto-recharge up to $50; it has no Ads API line, and the Ads API pages we read list no per-call fee, because the advertiser pays for the ads themselves.
How TwitterAPI.io bills. Tweet endpoints cost 15 credits per tweet returned, with a minimum of 15 credits per request, so an empty search costs $0.00015 and a full 20-tweet page costs $0.003. $1 buys 100,000 credits and purchased credits never expire. New accounts that pass the automatic bot check get up to $1 of free credits (at most 100,000 credits, no card, one per person or network, expiring after 31 days). Rate limits are 0.2 requests per second before the first payment and 20 once paid; plans and higher limits are on the pricing page.
What the study itself cost. The study on this page made 65 requests and returned 1,090 posts and 4 profiles, about 16,422 credits or $0.16 at the prices above (empty pages bill the 15-credit minimum on top).
The script in the code section below pulls the organic conversation around a campaign with /twitter/tweet/advanced_search (brand name, campaign hashtag and landing-page domain in one query) and sums likes, views and replies per language. Run it next to the Ads API stats call above and you have both halves of a launch report.
What X data says about the Ads API itself
We pulled every public post our search could find that names the API, plus the official accounts that talk about it. The headline: the official @AdsAPI account, with 18,510 followers and 784 posts in total, has not posted since 2022. Its newest post is the version 12 announcement, which matches the October 27, 2022 date in X's versioning table. Version 12 is still the version in X's current examples.
Mentions faded with it. Posts by others that tag @AdsAPI went from 107 in 2019 to 2 in 2024, 13 in 2025 and 2 so far in 2026 in our sample. 46.5% of the mentions tag five or more handles at once, the pattern of a support plea sent to every official account rather than a developer question.
Developer news moved to @XDevelopers, and it is not about ads. Of 140 recent @XDevelopers posts, 0 mention ads, advertising or campaigns, while 19 are about MCP, connectors or Grok. Ads API changes now surface in the docs (the X Ads MCP page, the versioning table) more than on X itself, so watch docs.x.com/x-ads-api rather than a feed.
The topic is small and old. Our search returned 300 unique posts that name the Twitter or X Ads API, from 2013 to 2026; 58.0% of them are from 2013 to 2016, the years around the API's 2013 launch. Recent posts are mostly English (86.3%), with a visible Japanese share (10.3%). The median post got 2 likes.
SDKs are aging too. X's tools page lists two X-maintained SDKs. The Python one, twitter-ads on PyPI, is at version 11.0.0, released May 27, 2022, and its source still pins API_VERSION = '11'; the GitHub repo xdevplatform/twitter-python-ads-sdk has had no push since that release and is not archived. The Ruby SDK's last push was in March 2024. If you use the Python SDK, check that the paths it builds match the version you target, or call ads-api.x.com/12/... through a plain OAuth 1.0a session as in the example above.
How we collected this
Question. How do people on X talk about the X Ads API today, and how active are X's official ads-developer accounts?
Accounts and queries. Profiles of four organization accounts (@AdsAPI, @XDevelopers, @API, @XBusiness) via /twitter/user/info. @AdsAPI's own posts via /twitter/tweet/advanced_search with from:AdsAPI (newest 100 posts; /twitter/user/last_tweets returned an empty page for this account, so we used search). @XDevelopers' recent timeline via /twitter/user/last_tweets with replies (140 posts). Topic posts via advanced_search for the exact phrases twitter ads api, x ads api and the two API host names, Latest pass until the results ran out plus a Top pass, de-duplicated to 300 posts. Mentions via @AdsAPI -from:AdsAPI, newest 400 posts.
Method. Topics are assigned by keyword rules (in analyze.py in our study folder); one post can carry several topics and about 72% of all posts matched none. Keyword rules misfire on some posts, so read the topic shares as a rough split, not a precise one.
Size and cost. 65 requests, 1,090 posts and 4 profiles returned, collected in 2026.
What the sample cannot show. Search returns what X's search index serves, which is not every post ever written; the mention sample stops at the newest 400, so its oldest year is partial. Nothing here measures how many Apps X approves, how long reviews take in general, or how much is spent through the Ads API.
Privacy. Aggregates only. Search authors are private individuals: their raw pages were not kept in the repository, the de-identified rows carry only year, language, engagement counts and topic flags, and no post is quoted or attributed. Only organization accounts are named.
import os
import time
import requests
API_KEY = os.environ["TWITTERAPI_IO_KEY"]
BASE = "https://api.twitterapi.io"
HEADERS = {"X-API-Key": API_KEY}
def search(query, max_pages=10):
"""Yield public posts for an X search query, newest first."""
cursor = ""
for _ in range(max_pages):
r = requests.get(
f"{BASE}/twitter/tweet/advanced_search",
headers=HEADERS,
params={"query": query, "queryType": "Latest", "cursor": cursor},
timeout=30,
)
r.raise_for_status()
page = r.json()
for t in page.get("tweets", []):
yield t
if not page.get("has_next_page"):
break
cursor = page.get("next_cursor", "")
# The organic conversation around a campaign: brand name, campaign hashtag, landing-page domain.
week_ago = int(time.time()) - 7 * 86400
query = f'("Acme" OR #AcmeLaunch OR url:acme.com) -from:acme since_time:{week_ago}'
posts = list(search(query))
likes = sum(t.get("likeCount", 0) for t in posts)
views = sum(t.get("viewCount", 0) for t in posts)
replies = sum(1 for t in posts if t.get("isReply"))
langs = {}
for t in posts:
langs[t.get("lang")] = langs.get(t.get("lang"), 0) + 1
print(f"{len(posts)} organic posts, {likes} likes, {views} views, {replies} replies")
print("languages:", sorted(langs.items(), key=lambda kv: -kv[1])[:5])
# Who is talking: one profile lookup per distinct author you care about (18 credits each).
top = sorted(posts, key=lambda t: t.get("likeCount", 0), reverse=True)[:3]
for t in top:
u = requests.get(
f"{BASE}/twitter/user/info",
headers=HEADERS,
params={"userName": t["author"]["userName"]},
timeout=30,
).json()
if u.get("status") == "success" and u.get("data"):
d = u["data"]
print(d["userName"], d["followers"], "followers |", t["likeCount"], "likes |", t["url"])Questions readers ask
How do I get access to the Twitter Ads API?
Create a developer account at console.x.com, create a developer App and store its keys, then submit the Ads API Access Form for that App, choosing Conversion Only or Standard Access. X's docs say to allow up to 3 business days for review. After approval, regenerate your user access tokens before making Ads API calls.
Is the X Ads API free?
The X API pay-per-usage rate card on docs.x.com has no Ads API line, and the Ads API pages we read list no per-call fee; what advertisers pay for is the ads. You still need an approved developer App, and someone with a role on the ad account you manage.
What is the difference between Standard Access and Conversion Only?
Conversion Only covers the mobile and web conversion endpoints. Standard Access covers analytics, campaign management, creatives, custom audiences and conversion endpoints. Both are read and write. Apps approved before July 2023 may hold older permission sets and a five-token limit; X's increasing-access page says to contact your X representative to move to Standard Access.
Can I get organic tweet analytics from the Ads API?
No. Its analytics cover ad entities such as campaigns, line items, promoted posts and promoted accounts inside ad accounts your token can reach. Organic posts, mentions, replies and other accounts' timelines need a data API, such as the official X API ($0.005 per post read) or TwitterAPI.io ($0.15 per 1,000 tweets returned).
Which authentication does the Twitter Ads API use?
OAuth 1.0a on every REST call to ads-api.x.com, using a user access token for someone with a role on the ad account. X recommends an existing OAuth 1.0a library over hand-written signing. The newer X Ads MCP server authenticates with the user's OAuth 2.0 token.
What is the current X Ads API version?
X's versioning table lists version 12 (path /12/) as introduced on October 27, 2022, with no deprecation date set; version 11 is also listed without an end-of-life date. X's current examples call ads-api.x.com/12/.
Is there a sandbox for the X Ads API?
Yes. Requests to ads-api-sandbox.x.com run in an environment where campaigns are never served, and sandbox-only endpoints create test ad accounts and test funding instruments.
Can an AI agent manage X ads?
X documents a remote X Ads MCP server at ads-api.x.com/mcp with 74 tools for accounts, campaigns, analytics, targeting, audiences and creatives. It uses the user's own OAuth 2.0 token and creates campaigns and line items paused, so nothing spends until someone activates it.
Continue
- X docs: Ads API step-by-step guide (three steps, Conversion Only vs Standard Access, regenerate tokens)
- X docs: Accessing Ads accounts (OAuth 1.0a, advertiser vs developer tokens, account roles)
- X docs: Ads API rate limiting (headers and limit chart)
- X docs: Ads API analytics (sync vs async, time ranges, entities, placements)
- X docs: X Ads MCP (ads-api.x.com/mcp, 74 tools, paused writes)
- X docs: X API pay-per-usage pricing (post and user read prices, 3M cap)
- X API overview: endpoints, pricing and access on TwitterAPI.io
- Free Twitter analytics through an API: what you can measure
- Understanding the official Twitter (X) API
- The X Developer Portal and Console, step by step
- How to get an X API key
- Competitor analysis on X with an API
- TwitterAPI.io MCP server for reading X data in AI agents
- TwitterAPI.io pricing and plans
- 01Twitter (X) Clients in 2026: Which Ones Still Work, by Platform
- 02How to Mass Block on Twitter (X): Tools, Block Lists and Safer Options
- 03Does Twitter (X) Delete Inactive Accounts? The Policy, the Purge, and What Actually Survives
- 04How to View a Suspended Twitter (X) Account, and What Still Survives
- 05Twitter (X) Temporary Label: What "May Impact Its Reach" Means and What to Do
- 06Twillot Twitter (X) Viewer: What It Is, Whether It Works, and Is It Safe?
- 07What Is an MCP Server? How AI Clients Talk to It, With a Live Twitter (X) Example
- 08Twitter (X) User Search: Find Accounts by Name, Keyword or Bio
Stop reading. Start building.
Starter credits cover real testing on real data. Google sign-in, no card, no application queue.
Get an API keyAlready building with TwitterAPI.io? Publish an honest tutorial or build log about it and earn up to $200 a month in API credits.