X Ads API analytics: the placements you cannot buy
X Ads API analytics takes one placement per request, and two of the three cannot be set on a line item. Segmentation is six types, not what the page says.
On this page · 9 sections
- Quick answer
- The namespace, honestly
- Two placements you can read and cannot buy
- Six segmentations, and two that are pure legend
- Four entity lists, no two the same
- The metrics the examples return and the tables do not
- Three clocks for one spend number
- What the rate limit actually buys you
- What to build with it
The short version
- ▸Analytics needs exactly one placement per request and accepts only ALL_ON_TWITTER, SPOTLIGHT and TREND. The POST line_items contract that creates the ads accepts eleven placement values and neither SPOTLIGHT nor TREND is among them. The read enum and the write enum share exactly one value.
- ▸Segmentation is six types as of September 2026: AGE, GENDER, METROS, REGIONS, PLATFORMS and CONVERSION_TAGS. The same page's asynchronous guide still says metrics can be broken out by interest and keyword. INTERESTS appears once in X's entire 4.86 MB documentation corpus, in a line giving it a 12-hour delay. KEYWORDS appears zero times.
- ▸Four different entity lists appear on one page and no two match. The synchronous enum has six values, the metric-group matrix has five rows, Active Entities has five different ones, and the asynchronous prose adds MEDIA_CREATIVE, which arrived with Ads API v5 on 28 February 2019 and is in no enum today.
- ▸The example responses return three metric keys that no table documents: tweets_send, poll_card_vote and unfollows. Each appears twice or less in the whole corpus, only inside those examples. Meanwhile url_clicks is documented in the ENGAGEMENT group and appears in no example response at all.
- ▸Spend settles on three different clocks depending on which paragraph you read: locked after 24 hours, estimated for up to 3 days, and billing data processed for up to 14 days. Only billed_charge_local_micro moves, and it can move down.
- ▸The asynchronous endpoints are the only ones in the namespace with no resource URL and no parameter table. The download URL expires 48 hours after the job finishes, a fact stated nowhere in prose and visible only as the gap between two timestamps in one example.
Quick answer
X Ads API analytics is five endpoints, and the placement parameter is where reporting quietly breaks. It is required, it accepts one value per request, and the only values it takes are ALL_ON_TWITTER, SPOTLIGHT and TREND. The POST line_items contract that creates the ads accepts eleven placement values, and SPOTLIGHT and TREND are not among them. X's own FAQ answer for "why don't the numbers match Ads Manager" is to request all three placements, without ever saying whether they overlap. Segmentation, separately, is down to six types while the same page still advertises interest and keyword breakouts.
Last updated: November 2026
Everything below comes from X (formerly Twitter) developer documentation, read on 15 November 2026 against v12. Occurrence counts come from X's own llms-full.txt, the 4,858,201-byte single-file version of the whole corpus.
The namespace, honestly
Five endpoints, three different ceilings:
| Endpoint | Max range | Segmentation | Limit |
|---|---|---|---|
GET stats/accounts/:account_id | 7 days | No | 250 req / 15 min, category scope |
POST stats/jobs/accounts/:account_id | 90 days, 45 segmented | Yes | 100 jobs processing per account |
GET stats/jobs/accounts/:account_id | n/a | n/a | 200 job_ids per poll |
GET stats/accounts/:account_id/active_entities | 90 days | n/a | 200 filter IDs |
GET stats/accounts/:account_id/reach/{campaigns,funding_instruments} | 7 days | No | 20 IDs |
Both synchronous and asynchronous take the same required set: entity, entity_ids (max 20), start_time, end_time, granularity, metric_groups, placement, all as query parameters, with times on whole hours.
Note which rows have a formal contract. The synchronous endpoint, both reach endpoints and Active Entities each get a resource URL and a parameter table. The two asynchronous endpoints get neither: POST stats/jobs and GET stats/jobs exist on the page only as prose links pointing back at the same page and as two twurl lines. segmentation_type, country, platform and job_ids are never formally specified, which is why the 200-job-ID cap is a sentence rather than a table row.
Two placements you can read and cannot buy
Three placement vocabularies exist in the Ads API documentation and no two agree.
| Source | Values |
|---|---|
| Campaign Management guide, "Placements" | 7: ALL_ON_TWITTER, PUBLISHER_NETWORK, TWITTER_PROFILE, TWITTER_SEARCH, TWITTER_TIMELINE, SPOTLIGHT, TREND |
POST line_items reference, placements | 11: ALL_ON_TWITTER, PUBLISHER_NETWORK, TAP_BANNER, TAP_FULL, TAP_FULL_LANDSCAPE, TAP_NATIVE, TAP_MRECT, TWITTER_PROFILE, TWITTER_REPLIES, TWITTER_SEARCH, TWITTER_TIMELINE |
Analytics, placement | 3: ALL_ON_TWITTER, SPOTLIGHT, TREND |
That union is thirteen values. The intersection of the enum that validates your writes and the enum that validates your reads is one value: ALL_ON_TWITTER. Five of the values you can set on a line item, PUBLISHER_NETWORK and the four TAP_ ones, cannot be passed to analytics at all. Two of the values analytics requires cannot be set on a line item through the documented contract.
Then the note attached to the analytics placement parameter: "For entities with both X and X Audience Platform placement, separate requests are required, one for each placement value." The Audience Platform is the product PUBLISHER_NETWORK and the TAP_ values belong to, and the analytics enum has no value for it. The instruction cannot be followed with the enum printed directly above it.
Residue shows up in the examples too. Active Entities returns a placements array per entity, the prose says it can contain ALL_ON_TWITTER, SPOTLIGHT and TREND, and the example response immediately above that sentence returns ["ALL_ON_TWITTER", "PUBLISHER_NETWORK"] for entity 2r30fn. The documented algorithm then says to split the response into exactly three placement groups. Follow it literally against X's own sample data and one entity lands in no group.
SPOTLIGHT and TREND are never defined anywhere in the corpus, and X never says whether they are subsets of ALL_ON_TWITTER or separate buckets. So the FAQ tells you to fetch all three to match Ads Manager without telling you whether to add them up. If your ads only ran in-feed, one ALL_ON_TWITTER call is the whole picture. If you bought a Trend Takeover, you are guessing.
Six segmentations, and two that are pure legend
Segmentation is dated in the docs: "As of September 2026, only the following segmentation types are enabled."
| Type | country required |
|---|---|
AGE | |
GENDER | |
METROS | yes |
REGIONS | yes |
PLATFORMS | |
CONVERSION_TAGS | yes, WEB_CONVERSION only |
REGIONS is the newest, added 16 September 2026. METROS returns numeric strings, so 819 is Seattle-Tacoma, and country takes a targeting value ID rather than an ISO code, so the US is 96683cc9126741d1. Multi-segmentation is explicitly unsupported: one dimension per job.
Now the same page, in the asynchronous usage section: "Campaign metrics can be broken out by location, gender, interest, keyword, and more." It links to the table above, which has no interest type and no keyword type. Best practices goes further and gives one of them an SLA: "Data segmented by INTERESTS can be delayed for up to 12 hours."
INTERESTS appears exactly once in all 4,858,201 bytes of X's documentation, and that once is the delay warning. KEYWORDS appears zero times. X publishes a latency expectation for a segmentation type that exists nowhere else in its own corpus, and promises a keyword breakout it has never named. If you are planning a reporting product around interest-level performance, that is the whole answer, and it matches what X Ads API targeting now does to interests and keywords in audience estimates.
Four entity lists, no two the same
| Source | Entity values |
|---|---|
GET stats/accounts/:account_id, entity enum | ACCOUNT, CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, PROMOTED_ACCOUNT, PROMOTED_TWEET |
| Metric-group matrix rows | ACCOUNT, FUNDING_INSTRUMENT, CAMPAIGN, LINE_ITEM, PROMOTED_TWEET |
Active Entities, entity enum | CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, PROMOTED_ACCOUNT, PROMOTED_TWEET |
| Asynchronous introduction, prose | accounts, funding instruments, campaigns, line items, promoted posts, media creatives |
PROMOTED_ACCOUNT is accepted by the synchronous endpoint and has no row in the matrix, so nothing tells you which metric groups apply to it. MEDIA_CREATIVE is in no enum at all; it arrived with Ads API v5 on 28 February 2019, in the same release that shipped Active Entities, and the prose promising it is seven years of drift. Active Entities also claims its own list "reflects the entity types that our analytics endpoints support", which its own page disproves twice.
Read the matrix for what it withholds, too. ACCOUNT gets ENGAGEMENT only and BILLING starts at FUNDING_INSTRUMENT, so account-level spend is not a request you can make, it is a sum you compute. And billed_charge_local_micro is micros: divide by 1,000,000 before it reaches a dashboard.
The metrics the examples return and the tables do not
X documents twelve metrics in the ENGAGEMENT group. The two example responses on the page, one synchronous and one from an unzipped async data file, return thirteen and fourteen keys respectively for that same group.
Keys present in the examples and in no metrics table anywhere:
tweets_send: 2 occurrences in the corpus, both in these two examplespoll_card_vote: 2 occurrences, both in these two examplesunfollows: 1 occurrence in an analytics context, in the async example only
And one documented metric absent from every example: url_clicks. It has a row in the ENGAGEMENT table, "Total clicks on the link or Website Card in an ad, including earned", and never appears as a response key.
That absence matters, because of what clicks actually counts. X's own description: "Total number of clicks, including favorites and other engagements." The Metrics by Objective table for WEBSITE_CLICKS then defines Click Rate as clicks/impressions and CPLC, cost per link click, as billed_charge_local_micro/clicks. Both compute a link-click metric from a field that includes likes. In the synchronous example, clicks is 58 and engagements is 58, identical.
The page's separate Derived Metrics section does define link clicks correctly, as promoted_tweet_search_url_clicks + promoted_tweet_timeline_url_clicks + promoted_tweet_profile_url_clicks. None of those three fields is returned by anything. That whole section is written in a pre-v5 vocabulary of promoted_tweet_*_impressions, promoted_account_follows and promoted_video_total_views, which the current metric groups replaced with impressions, follows and video_total_views. So there are two documented routes to cost per link click: one uses the wrong metric, the other uses field names the API does not return. The same dead tables are pasted a second time into the middle of the Active Entities reference entry, including two (a Media Views pair and a Leads and Cost Per Lead pair) that the guide's own Derived Metrics section does not contain.
Three clocks for one spend number
Everything in analytics is final after 24 hours except billed_charge_local_micro. How long that one moves depends which paragraph you read:
- Best practices: an estimate "for up to 3 days", changing "minimally" after 24 hours
- FAQ: "generally final within 3 days of the event"
- FAQ, next line: "we process billing data for up to 14 days from the date of the event (for spam filtering, for example)"
Spend can also decrease after 24 hours, for overspend credits and for billable events judged to be junk. If you reconcile X spend against invoices or a client report, the window you need is 14 days, not 3, and the figure you locked on day two is not the one you will defend on day ten.
One more undocumented number. The async job example shows created_at and updated_at two seconds apart and expires_at at 2026-04-03T23:19:48Z, exactly 48 hours after the job finished. No prose states a retention window. The download URL is also on ton.twimg.com, not ads-api.x.com, so a locked-down egress policy will fail at step three of a four-step flow.
What the rate limit actually buys you
Here the chart row reads "Analytics (synchronous), Category, 250" per 15-minute window. The analytics guide calls the same limit "User-level: 250 requests / 15 minutes". Category scope is defined on the rate-limiting page as one allocated limit shared across every endpoint in the category, which is not a per-user allowance, and the two pages do not reconcile. Nothing says whether Active Entities, also a /stats/ path, draws from that same 250.
Take the limit at face value and stack X's own best practices on it: request at the promoted-post level, use HOUR granularity, send one placement per request, and "group conversion metrics and non-conversion metrics into separate requests." That is 20 entity IDs per request, times 3 placements if your ads served across all of them, times 2 metric-group batches for a conversion campaign: 6 requests per 20 promoted posts, so 250 requests covers about 820 promoted posts per window. Drop to a single placement and one metric batch, the common case, and the same budget covers 5,000. The spread is entirely a function of a placement enum that cannot describe what you bought, and it is the number to settle before you promise anyone a near-real-time dashboard. X Ads API campaigns covers the entity ceilings on the other side of that arithmetic.
What to build with it
Use the sync endpoint for the last 7 days and nothing else. Use the async path for everything older, poll with batched job_ids, and store results permanently, because X asks you not to re-request data older than 30 days and the download URL is gone in 48 hours.
Drive both from Active Entities rather than from your campaign list. That is the one part of this namespace that is well documented and well reasoned: change events in hourly buckets, applied to the hour they belong to rather than the hour they arrived in, which is the mechanism that makes an unchanging campaign's Tuesday numbers move on Thursday.
Then decide what you are measuring before you pick a metric. If you want link clicks, this namespace will not give them to you by either documented route, and the X Conversion API is where on-site outcomes live. If you want organic post performance rather than paid, the separate v2 endpoint covered in X API analytics is a different product with a different metric set. And if you are running experiments, X Ads API A/B testing creates the split but nothing here can report on it, because no segmentation type knows user groups exist.
For scheduling and replying on X rather than buying ads, X-Autopilot runs locally on your Mac in your own browser session, which is a different route with a different risk profile from an API integration: lower detection surface than a cloud tool, not zero. Automating engagement through a browser is a gray area rather than a sanctioned path, and the API is the sanctioned one.
Frequently asked
Answers indexed by Google + AI assistants.
Why do X Ads API analytics numbers not match X Ads Manager?+
Three documented reasons and one undocumented one. End times are exclusive in the API and inclusive in Ads Manager, so a naive range is short by a day. Analytics accepts one placement per request and X tells you to request all three of ALL_ON_TWITTER, SPOTLIGHT and TREND, so a single call is a partial view. Segmented numbers are not expected to roll up to non-segmented numbers, and the API scopes segmented metrics to the entity type you queried while Ads Manager aggregates across entity types. What X never states is whether SPOTLIGHT and TREND are subsets of ALL_ON_TWITTER or separate buckets, so it does not say whether to add the three responses together.
What are the X Ads API analytics endpoints?+
Five. GET stats/accounts/:account_id is the synchronous one, capped at a 7-day range with no segmentation. POST stats/jobs/accounts/:account_id creates an asynchronous job and GET stats/jobs/accounts/:account_id polls it, together covering 90 days unsegmented or 45 days segmented. GET stats/accounts/:account_id/active_entities tells you which entity IDs changed in a window, over a range of up to 90 days. GET stats/accounts/:account_id/reach/campaigns and the funding_instruments variant return total_audience_reach and average_frequency over at most 7 days.
What segmentation types does the X Ads API support?+
Six, and only through the asynchronous endpoints. AGE, GENDER, METROS, REGIONS, PLATFORMS and CONVERSION_TAGS, with the list dated as of September 2026. METROS and REGIONS both require the country parameter, which takes a targeting value ID rather than a country code. CONVERSION_TAGS only works with the WEB_CONVERSION metric group. Multi-segmentation is explicitly not supported, so one dimension per job.
How many requests can I make to the X Ads API analytics endpoint?+
250 per 15 minutes for the synchronous endpoint, which the rate limit chart scopes to the whole analytics category rather than to one endpoint. The asynchronous endpoints are not in the chart at all and are limited instead to 100 jobs in a processing state per ads account. With 20 entity IDs per request, one placement per request, and X's own advice to split conversion and non-conversion metrics into separate calls, the real ceiling for a conversion campaign served across all three placements is roughly 820 promoted posts per window.
What is the Active Entities endpoint for?+
It answers which entity IDs to pull analytics for. X records a change event whenever an entity's metrics change, stores them in hourly buckets, and this endpoint returns the entities whose buckets moved plus the window those changes apply to. The important part is that change events do not always apply to the hour they were recorded in, often because of billing adjustments, so yesterday's numbers can change today and the endpoint is how you learn that. X's documented loop is to split the response by placement, batch IDs into groups of 20, round the minimum activity start down and the maximum activity end up, and request only those.
Can I get spend at the account level from the X Ads API?+
No. The entity and metric-group matrix gives ACCOUNT only the ENGAGEMENT group, and even there some engagement metrics are marked unavailable at the account and funding instrument level. BILLING starts at FUNDING_INSTRUMENT. So account-level spend has to be summed from funding instruments or campaigns yourself, and billed_charge_local_micro is in micros, meaning you divide by 1,000,000 before showing anyone a currency figure.
- X developer docs, 'Analytics': the synchronous versus asynchronous table, the 7-day and 90-day and 45-day ranges, the 250-per-15-minute and 100-concurrent-job limits, the FAQ on placements and exclusive end times, the entity and metric-group matrix, the six enabled segmentation types dated as of September 2026, the ENGAGEMENT and BILLING and VIDEO and conversion metric tables, the Active Entities guide and the asynchronous job example with its expires_at value (accessed 15 November 2026)
- X developer docs, 'Campaign Management': the Placements section listing ALL_ON_TWITTER, PUBLISHER_NETWORK, TWITTER_PROFILE, TWITTER_SEARCH, TWITTER_TIMELINE, SPOTLIGHT and TREND, and the objective-by-placement table with only four placement columns (accessed 15 November 2026)
- X developer docs, 'Campaign Management API Reference': the POST line_items placements enum of eleven values, which includes PUBLISHER_NETWORK and five TAP_ values and excludes SPOTLIGHT and TREND (accessed 15 November 2026)
- X developer docs, Ads API 'Rate limiting': the Analytics (synchronous) row at 250 requests per 15-minute window scoped by Category, the absence of any asynchronous analytics row, and the definition of Category scope as a single allocated limit shared across every endpoint in it (accessed 15 November 2026)
- X developer docs, Ads API 'Versions': the Ads API v5 release of 28 February 2019 that introduced both the Active Entities endpoint and MEDIA_CREATIVE stats, and stated the Active Entities entity list as CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, MEDIA_CREATIVE and PROMOTED_TWEET (accessed 15 November 2026)
- X developer docs, 'llms-full.txt': the complete 4,858,201-byte documentation corpus used to count occurrences of INTERESTS, KEYWORDS, tweets_send, poll_card_vote, unfollows and url_clicks (accessed 15 November 2026)
Product designer and indie hacker. Runs the agent on his own X account every day and writes up what the data shows, including when it's inconvenient.
Follow on X →