X Starts Billing API Expansions on Nov 22: What One Request Costs Now

On October 23, 2026 the X Developer Platform team posted an update on how X API expansions are counted on the Pay-Per-Use plan. The short version: objects that come back through expansions are not counted toward usage today. From November 22, 2026, expanded posts, users, media, polls and places bill at the standard PPU rate for that resource, the same as a direct lookup, and the charges show in the Developer Console from that date.

X says this is not a new pricing model. That is true, and it is also the reason it matters: the rate card does not move, but the number of billable objects in a response does. This guide explains what changes, reconciles it with what X staff said earlier in the year, prices the request shapes developers send every day, and shows what to do in the four weeks before the meter switches on.

TL;DR: X will bill every object an API expansion returns from November 22, 2026, at the same rate as a direct lookup: $0.010 per expanded user and $0.005 per expanded post on the pay-per-usage price list. A single-account timeline with author_id barely moves, about 2 percent. A search that expands authors and referenced posts moves a lot: on our measured sample a 100-post page goes from $0.50 to about $1.72, 3.4 times more for the same response. Trim the expansions you do not read, cache users by id, and price your read-heavy jobs before the date.

[Inform] X API PPU - Expansions Update - Announcements - X Developers https://t.co/oGVYZR0hmn Oct 24

@matiere view on X

What did X announce about API expansions?

X announced that, from November 22, 2026, every object returned through an expansion counts toward Pay-Per-Use usage at the standard rate for that resource. Before that date expanded objects are not counted. The notice covers post, user, media, poll and place expansions, and X says the charges appear in the Developer Console on November 22.

The notice is short, and every line of it matters for a budget. It restates what expansions are: a way to pull related objects, such as the author of a post, the post it quotes or the media it carries, into the includes section of a single response so you do not make a second request. It then says that usage on PPU is based on the data objects the API returns, that expansion objects are not counted right now, and that they will be counted "in the same way" from November 22 so every object is treated equally no matter how you request it.

Here is what that looks like on the wire. One request for a post with its author expanded returns the post in data and the author in includes:

# One post lookup with the author expanded into includes.
curl "https://api.x.com/2/tweets/1234567890?expansions=author_id&user.fields=username,public_metrics" \
  -H "Authorization: Bearer $X_BEARER_TOKEN"

{
  "data": { "id": "1234567890", "text": "Hello world!", "author_id": "2244994945" },
  "includes": {
    "users": [ { "id": "2244994945", "username": "xdevelopers", "name": "X Developers" } ]
  }
}

Today that response bills one Posts Read. From November 22 it bills one Posts Read plus one User Read, because the user object in includes counts like a direct user lookup.

The how-to-prepare advice in the notice is two bullets: look at which fields and expansions your requests use and optimize, and review usage in the console. The rest of this guide turns those two bullets into numbers.

The expansion objects that bill from November 22

Object	Typical expansions	Bills as	Source
Users	author_id, in_reply_to_user_id	User Read, $0.010	published
Posts	referenced_tweets.id, pinned_tweet_id	Posts Read, $0.005	published
Media	attachments.media_keys	No published read rate	unknown
Polls	attachments.poll_ids	No published read rate	unknown
Places	geo.place_id	No published read rate	unknown

as of 2026-10-24

Which expansions start to bill?

Five object types start to bill: users, posts, media, polls and places. Users come from author_id, in_reply_to_user_id, mentions and referenced post authors. Posts come from referenced_tweets.id, pinned_tweet_id and edit history. Media, polls and places come from their own attachment and geo expansions.

The user and post objects carry published rates. A user in includes bills as a User Read at $0.010, and a post in includes bills as a Posts Read at $0.005, the same as fetching either one directly. The media, poll and place objects are named in the notice, but the pay-per-usage price list has no separate read line for them as of October 24, 2026. Treat their rate as unknown until it shows in your console, rather than as free.

One structural detail decides most of the cost: X deduplicates objects within a response, the usage and billing page counts a post returned by several queries in one day once, and the price list describes a 24-hour UTC window in which a resource you already paid for is not charged again. So a single author repeated across 100 of their own posts is one user, not 100. A search, where almost every post has a different author, is close to one user per post.

Did expansions already count before November 22?

The forum record conflicts. On August 31 and September 7, 2026, an X staff member answered two billing questions saying expanded objects in includes count: an expanded author is a User Read on top of the post, deduplicated once per response. The October 23 notice from the same team says expansion objects are not counted today and will be from November 22.

Here is the earlier record in full. In the August 31 thread on billing requests that involve expansions, the accepted answer says Pay Per Use bills reads per resource returned, that expansions=author_id returns the user in includes.users, and that "that user is a User: Read on top of the post." In the September 7 thread about expansions on post lookups, the accepted answer says reads are billed per object returned and objects brought in via expansions count too.

The honest reading is that those answers described the documented rule and the October notice describes what the meter was doing in practice. Two practical consequences follow. If you budgeted from the August and September answers, you already budgeted for the November 22 state, and your forecast is fine. If you budgeted from your console, which has not been charging for includes, your forecast is low, and the gap is exactly the cost of your expansions. Either way, November 22 is the date the charge becomes real on your invoice.

What does the X API charge per object?

The X API charges per resource returned on reads: $0.005 per post and $0.010 per user, with owned reads of your own data at $0.001. Pay-per-use plans cap at 3 million post reads per billing month before Enterprise. From November 22 the same rates apply to each object an expansion adds to the response.

X opened pay-per-use as a pilot in October 2025 and has since moved self-serve developers onto it. The rate card has not changed, which is X's point in calling this "not a new pricing model." What has changed is the count. A response used to bill for the objects in its data array. From November 22 it bills for the objects in data plus the objects in includes. The pricing change timeline covers how the rate card itself got here, from the tier plans to pay-per-use, and the legacy Basic migration notice explains why so many older integrations now meet this change on the meter instead of a flat subscription.

Note the asymmetry inside the price list. A user costs twice what a post costs. That makes author expansion, a very common expansion, the most expensive one on any request where the authors are mostly different people.

How many objects does a real response carry?

On our measured sample, a 20-post search page carried 18.7 distinct authors, 13.3 referenced posts and 3.3 images or videos on average. Scaled to 100 posts that is 88 expanded users, 67 referenced posts and 17 media objects, so a full-expansion response carries more billable objects than posts.

We measured this rather than assume it. We pulled three consecutive pages of a live Latest search for English posts mentioning OpenAI through our own API on October 24, 2026, and counted, for each post, the objects a typical expansions string would pull into includes.

55% of the 60 newest English posts mentioning OpenAI were replies, so each one points at a parent post that a referenced_tweets expansion would pull into the response.

Our data · Dataset: x-search-expansion-load · Source: public X posts, pulled through our API · Query: twitter_advanced_search {"count": 20, "fields": "id,author.id,in_reply_to_status_id,in_reply_to_user_id,quoted_tweet.id,media.type,entities.user_mentions.id_str", "pages": 3, "product": "Latest", "query": "openai lang:en -filter:retweets"} · Pulled: 2026-10-24 · n = 60 · Method: share of items whose in_reply_to_status_id matches /\d/i; frame: 60 unique items from 3 page(s), deduplicated by id

The same 60 posts came from 53 distinct accounts, so an author_id expansion across those three pages bills about 53 User Reads once same-day deduplication folds the repeats.

Our data · Dataset: x-search-expansion-load · Source: public X posts, pulled through our API · Query: twitter_advanced_search {"count": 20, "fields": "id,author.id,in_reply_to_status_id,in_reply_to_user_id,quoted_tweet.id,media.type,entities.user_mentions.id_str", "pages": 3, "product": "Latest", "query": "openai lang:en -filter:retweets"} · Pulled: 2026-10-24 · n = 53 · Method: count of items; frame: 53 unique items from 3 page(s), deduplicated by id; posts deduplicated by author id, so the count is distinct accounts

17% of the 60 posts carried an image or video, the objects an attachments.media_keys expansion adds.

Our data · Dataset: x-search-expansion-load · Source: public X posts, pulled through our API · Query: twitter_advanced_search {"count": 20, "fields": "id,author.id,in_reply_to_status_id,in_reply_to_user_id,quoted_tweet.id,media.type,entities.user_mentions.id_str", "pages": 3, "product": "Latest", "query": "openai lang:en -filter:retweets"} · Pulled: 2026-10-24 · n = 60 · Method: share of items whose media matches /photo|video|gif/i; frame: 60 unique items from 3 page(s), deduplicated by id

Objects per 20-post search page, measured through our API

Page	Posts	Distinct authors	Referenced posts	Media	Source
Page 1	20	18	12	5	measured
Page 2	20	19	12	2	measured
Page 3	20	19	16	3	measured
Three pages, deduplicated	60	53	40	10	measured

as of 2026-10-24

Measured

Objects in one response per 100 posts, full expansions

Point	Value
Posts requested	100
Expanded users	88
Referenced posts	67
Media objects	17

Two caveats keep this honest. A sample of 60 posts on one topic is a sample, not a law: a keyword that draws original posts from a few large accounts will carry fewer authors and fewer replies, and a conversational keyword will carry more. And quoted posts were 7 of the 60, which is 12 percent, so a quote-heavy topic will carry more referenced posts than ours. The method, not our ratio, is the thing to copy: pull a few pages of your own query and count.

What does a search request cost before and after?

A 100-post search page with author and referenced-post expansions costs $0.50 today and about $1.72 from November 22 on our sample: $0.50 for the posts, $0.88 for 88 authors and $0.335 for 67 referenced posts. That is 3.4 times more for the same request and the same response.

Here is the arithmetic, so you can swap in your own ratios. The rates are the published ones; the object counts are the measured ones above.

# One 100-post search page with expansions=author_id,referenced_tweets.id
POST_READ = 0.005   # Posts: Read, per resource (docs.x.com, read 2026-10-24)
USER_READ = 0.010   # User: Read, per resource

posts = 100
authors = 88        # measured: 53 distinct authors per 60 posts
referenced = 67     # measured: 40 reply parents plus quoted posts per 60 posts

today = posts * POST_READ
from_nov_22 = posts * POST_READ + authors * USER_READ + referenced * POST_READ
print(round(today, 3), round(from_nov_22, 3), round(from_nov_22 / today, 2))
# 0.5 1.715 3.43

Media is left out of that figure because no media read rate is published. If your expansions string includes attachments.media_keys, add 17 media objects per 100 posts at whatever rate your console shows from November 22. At 1,000 posts the same request shape goes from $5.00 to $17.15, before media.

Our cost by workload breakdown sizes the same search-led jobs, sentiment and lead scoring among them, and the advanced search operators guide is the place to narrow a query so fewer posts, and fewer objects, come back at all.

What does a timeline or lookup request cost?

A single-account timeline barely moves: 100 posts with author_id cost $0.50 today and $0.51 from November 22, because the author is one deduplicated user. User lookups with pinned_tweet_id and post lookups across many authors move more, by the number of distinct objects they add.

The timeline case is the reassuring one. A GET on one user's posts with expansions=author_id returns 100 posts by one author, and includes holds that author once. One User Read at $0.010 on a $0.50 page is a 2 percent increase. If you are reading your own timeline as the app owner, the price list prices owned reads at $0.001 per resource, so check which rate your endpoint qualifies for before you model it. Add referenced_tweets.id to that timeline and the cost tracks how often the account replies or quotes: an account whose timeline is half replies adds up to 50 referenced posts, $0.25, on the same page.

User lookups run the other way. Looking up 100 users costs $1.00 at $0.010 each. Add expansions=pinned_tweet_id and every user with a pinned post brings one post into includes, up to 100 posts and $0.50 more, so up to $1.50. Post lookups by id sit in between: 100 ids from 40 distinct authors cost $0.50 for the posts and $0.40 for the authors once author_id is expanded, so $0.90.

What common request shapes cost before and after November 22

Request shape	Today	From Nov 22	Source
Timeline, 100 posts, author_id	$0.50	$0.51	derived
Search, 100 posts, full expansions	$0.50	$1.72	derived
User lookup, 100 users, pinned post	$1.00	up to $1.50	derived
Post lookup, 100 ids, 40 authors	$0.50	$0.90	derived
1,000 searched posts, full expansions	$5.00	$17.15	derived

as of 2026-10-24

The pattern across all four: the change costs you in proportion to how many distinct objects a response pulls in, not in proportion to how many requests you send. Requests that read one account are almost unaffected. Requests that read many accounts at once, search above all, are where the bill moves.

How should you prepare before November 22?

Inventory every expansions value your code sends, measure how many includes objects each response returns, and price them at the published rates. Then drop the expansions nothing reads, cache user objects by id, expand context only for posts you keep, and set a spending limit before the meter switches on.

Start with the inventory, because most expansion strings were written once and copied. A grep for "expansions=" across a codebase usually finds author_id on almost every read, often next to user.fields that nothing downstream uses. Each of those is now a priced line.

# Find every expansions string your code sends.
grep -rn --include='*.py' --include='*.ts' --include='*.js' "expansions" ./src

Then measure: log the length of includes.users and includes.tweets on a day of real traffic and divide by the posts returned. That gives you your own version of our 0.88 and 0.67, which is the only ratio that matters for your bill.

# Measure the objects each response adds, then price them at the published rates.
POST_READ, USER_READ = 0.005, 0.010

def expansion_cost(resp: dict) -> dict:
    inc = resp.get("includes", {})
    posts = len(resp.get("data", []))
    users = len(inc.get("users", []))
    refs = len(inc.get("tweets", []))
    media = len(inc.get("media", []))   # no published read rate yet; track the count
    today = posts * POST_READ
    after = today + users * USER_READ + refs * POST_READ
    return {"posts": posts, "users": users, "refs": refs, "media": media,
            "today": round(today, 4), "from_nov_22": round(after, 4)}

Caching is the biggest lever for search-led jobs. An account's name, handle and follower count change slowly compared with how often you see its posts. Keep a local table keyed by user id, refresh it on a schedule you choose, and stop expanding author_id on every search page. Same-day deduplication already folds repeats inside one UTC day; a cache folds them across days too. The per-user cost of goods breakdown shows how that kind of per-object cost compounds across a product's users, and our pagination guide covers capping the pages that feed it.

Expanding on demand is the second lever. If your pipeline filters 1,000 posts down to 50 worth acting on, expand context for the 50, not the 1,000. A replies guide and the full-thread fetch guide cover pulling conversation context only for the posts that earn it.

Finally, watch the console. X says in its notice that the expansion charges show in the Developer Console from November 22, so compare the first full week after the change against the same week before it, per endpoint. A rise much larger than your includes counts predict means an expansion you did not inventory. The rate limit guide covers the separate request ceilings, which this change does not touch.

What do developers say about per-resource billing?

Developers building on pay-per-use already design around per-resource billing, and the expansion change makes that design matter more. One builder writing an X MCP server noted that reads are billed per resource returned rather than per request, so a large result count costs many times a small one for the same question.

That is the r/ClaudeAI post below, which describes pushing a model toward the smallest useful result count and batching lookups because every returned resource is billed. From November 22 the same discipline applies to expansions: every object in includes is a returned resource.

gave a model the X api, then spent two weeks making sure it couldn't spend my money for me from r/ClaudeAI

The cost worry shows up at small scale too. A developer in r/SaasDevelopers who synced bookmarks through the new API put it at about $1 for every 200 posts, which is the $0.005 Posts Read rate showing through, and worried it would pile up on a continuous sync. Expanded authors on top of that would add a User Read for each distinct account.

I tried the new X API - it's nice, but doesn't look so cheap long term from r/SaasDevelopers

On X itself the same calculation keeps pushing builders of free tools away from the official API entirely:

@Xman_base_eth no x API, way too pricey for a free tool it reads the public thread through open endpoints, then a background scraper fills in the deeper replies everything's cached on a cloudflare worker so it stays fast and free 🤝

@amiraphist view on X

If you are still standing up an app on the X API, this tutorial on X API OAuth 2.0 in Python is a useful orientation; the developer app it sets up is also the one whose usage will show the new expansion charges in the Developer Console from November 22:

https://www.youtube.com/watch?v=6n0NQW7EMbU

How does a per-call API price the same response?

A per-call API prices the call, not the objects in it. On twitterapis.com an advanced search call is $0.0008 and returns about 20 posts with each author's profile, any quoted post in full and media URLs inline, so author and quote context adds nothing to the price. A reply's parent is one detail call at $0.0008.

We checked what one call carries rather than describe it from memory. On our own search calls on October 24, 2026, every post came back with its author's profile inline, quoted posts came back in full with their own author profile and media, and media came back as URLs on the post. A reply carried its parent's id, not the parent post, so fetching the parent is a separate detail call. Each of the three sample pages returned 20 posts for one $0.0008 call. The live per-endpoint rates are on the pricing page.

# One per-call search page: about 20 posts, authors and quoted posts inline, one $0.0008 charge.
curl "https://api.twitterapis.com/twitter/tweet/advanced_search?query=openai+lang%3Aen+-filter%3Aretweets&product=Latest" \
  -H "Authorization: Bearer $TWITTERAPIS_KEY"

So the same 1,000 posts cost $0.04 in 50 search calls with authors, quotes and media included. If you also fetch every reply parent, 550 replies per 1,000 posts on our sample, that adds 550 detail calls at $0.0008, $0.44, for $0.48 in all. On the X API from November 22 the same full context is $17.15 before media.

By billing unit

X pay-per-use after Nov 22 against a per-call API

	X API pay-per-use	Per-call API
Billing unit	Every object returned	One price per call
Author of each post	$0.010 per user	Inline, no extra charge
Quoted post	$0.005 per post	Inline in full
Reply parent post	$0.005 per post	One detail call, $0.0008
1,000 posts, full context	$17.15	$0.04 to $0.48
Monthly ceiling	3M post reads	None

The honest line through that grid: a per-call API does not change what X charges, and the official API remains the right route for the jobs only it serves. What the per-call route changes is the unit. When a response gets richer, the price stays put. Our comparison of the X API v2 with twitterapis.com and the official versus third-party breakdown cover where each route fits, and the cheapest Twitter API ranking prices the market per 1,000 posts.

What does a month of a search job cost?

A job that searches 10,000 posts a day for 30 days costs $1,500 on the X API today, posts only, and up to about $5,145 from November 22 once authors and referenced posts bill, less whatever same-day deduplication folds. The same job is $12 in search calls on a per-call API, or $144 if it also fetches every reply parent.

Worked example

A month of a 10,000-post-a-day search job, priced before Nov 22

Posts searched per day: 10,000 · X API from Nov 22, 30 days: $5,145 · Per-call search, 30 days: $12

☑ 300,000 posts x $0.005 is $1,500 on the X API today (expansions not counted yet) · ☐ Add 264,000 user reads and 201,000 referenced post reads from Nov 22 ($5,145 for the month) · ☑ 15,000 search calls x $0.0008 is $12 on the per-call route · ☑ Fetching every reply parent adds 165,000 detail calls, $132 (only if you need them)

An illustration at a stated volume, not a customer account. Uses our measured ratios of 0.88 authors, 0.67 referenced posts and 0.55 replies per post. X rates from docs.x.com and per-call rates from the live rate card, both read 2026-10-24.

The month is where the change stops being a rounding error. Over 10,000 posts a day more authors and parents repeat, so same-day deduplication will bring the real figure below this ceiling. 300,000 posts at $0.005 is $1,500. From November 22 the same job also returns about 264,000 expanded users and 201,000 referenced posts on our ratios, which adds $2,640 and $1,005. The referenced posts also count toward the 3 million post-read monthly cap, so this job uses about 501,000 post reads a month rather than 300,000.

# One month: 10,000 searched posts a day, full author and referenced-post expansions.
DAYS, PER_DAY = 30, 10_000
posts = DAYS * PER_DAY                       # 300,000
users = round(posts * 0.88)                  # measured: 0.88 distinct authors per post
refs = round(posts * 0.67)                   # measured: 0.67 referenced posts per post
x_today = posts * 0.005
x_nov22 = posts * 0.005 + users * 0.010 + refs * 0.005
per_call = posts / 20 * 0.0008               # about 20 posts per search call
per_call_with_parents = per_call + posts * 0.55 * 0.0008
print(x_today, round(x_nov22), per_call, round(per_call_with_parents))
# 1500.0 5145 12.0 144

The one-million-tweet dataset cost, the cost benchmark and the poll cadence cost guide run the same month-level arithmetic for other jobs, and the cost calculator does it interactively.

Which jobs should move, and which can stay?

Jobs that read one account at a time can stay where they are, because one expanded author per response is close to free. Jobs that search, monitor keywords or read many accounts per response are the ones to price again, because they pull in close to one author per post and often a referenced post too.

A practical sort: own-timeline analytics, single-account backups and dashboards on a handful of accounts barely move. Keyword monitoring, brand listening, lead discovery and research corpora built from search move the most, by roughly the 3.4 times our sample shows. Anything that expands pinned posts on user lookups sits in between. For the jobs that move, the choice is to cut expansions and cache, which keeps you on the official API at a higher but controlled cost, or to route the read-heavy part to a flat per-call price. Our guide to choosing a Twitter API and the Twitter API alternatives page walk that decision, and is the Twitter API free covers the floor.

The short version

X starts billing API expansions on November 22, 2026. Every user, post, media, poll and place object an expansion returns will bill like a direct lookup: $0.010 per user and $0.005 per post on the published rate card, with media, poll and place rates not yet listed.

A single-account timeline barely notices. A search that expands authors and context costs about 3.4 times more on our sample, $17.15 per 1,000 posts instead of $5.00. Inventory your expansions this week, measure includes per response, cache users, and price the read-heavy jobs before the date. If you want to compare against a flat per-call price, sign up for the $0.50 credit, about 625 standard calls, and run your own query against the pricing page; the MCP server and the Python tutorial are the fastest way to try it.