[tcaldwell-x]

Caution

Do not merge until expansion billing is enabled in production (planned Nov 22, 2026).

Reviewer note: Verify the changelog date matches the actual enable date before merging.

Documents pay-per-usage expansion billing: objects returned through expansions (includes) bill at the standard per-resource rate, the same as direct lookups, for post, user, media, poll, and place expansions.

This PR merges on the day billing is enabled, so the pricing, Usage and Billing, and Expansions pages describe it in the present tense as current behavior. The effective date appears only in the changelog entry's Nov 22, 2026 label. If the enable date moves, edit that label at merge time.

Pages changed

• Pricing (x-api/getting-started/pricing.mdx)
  • Read operations table: adds Media: Read, Poll: Read, and Place: Read at $0.005 per resource. A sentence under the table separates Media: Read from the Media Metadata write rate, which is unchanged.
  • New Expansions section: which expansions return which objects, the rate each bills at, one resource per object (4 photos = 4 Media resources), deduplication, and a worked example ($1.30 for 100 posts, 60 authors, and 40 media).
  • Owned Reads: adds a note that third-party OAuth apps are not Owned Reads, and a new Expansions on Owned Reads subsection. On GET /2/users/:id/tweets, /mentions, and /liked_tweets, expansion objects bill at $0.001 and are deduplicated together with the primary results. Includes a worked example.
  • Deduplication: states that it covers all billable resources, including users, media, polls, and places from expansions.
• Usage and Billing (x-api/fundamentals/post-cap.mdx): the deduplication note and bullets now cover all billable resources, including expansion objects, matching Usage. Adds an FAQ: "Are objects returned through expansions billed?"
• Expansions (x-api/fundamentals/expansions.mdx): short billing note linking to Pricing.
• Changelog (changelog.mdx): new Nov 22, 2026 "X API pricing update" entry ("Expansion objects now count toward usage..."), in the same format as the April 2026 Owned Reads entry.
• API reference cost estimator (sliders.js, the "View Pricing" widget on endpoint pages): labels Media, Poll, and Place as per-resource read types, and prices get-media-by-media-key(s) with Media instead of the CountsRecent placeholder.

No other page said expansions were free or uncounted.

For reviewers

• Changelog date: verify the changelog date matches the actual enable date before merging.
• Estimator keys: sliders.js reads live rates from console.x.com/api/credits/pricing. It assumes the new types are keyed Media, Poll, and Place in eventTypePricing, following the existing PascalCase keys. If a key is missing, the widget is hidden on that page rather than showing a wrong price. I couldn't reach that API from the build box to confirm.
• Other Owned Read endpoints: the docs describe Owned Read expansion pricing only for tweets, mentions, and liked_tweets, and say nothing about expansions on the other Owned Read endpoints (for example bookmarks). Please confirm that's the intended wording.
• Public calculator: the developer.x.com pricing calculator lives in xai-org/xai (frontend/apps/x-developer-landing/.../CreditConsumptionTable.tsx). It already lists Media: Read at $0.005 but has no Poll or Place rows. That needs a separate change in that repo.

Testing

• mint broken-links: same 2 broken links as main, both already there (x-api/posts/filtered-stream/migrate/overview.mdx, x-api/posts/lookup/migrate/overview.mdx). None new.
• mint validate: couldn't finish locally because its build step needs internet access the build box doesn't have. All four changed MDX files compile with @mdx-js/mdx + remark-gfm/remark-frontmatter, and node --check sliders.js passes. The Mintlify deployment check on this PR is the full build.
• New anchors used in links: #expansions, #expansions-on-owned-reads, #write-operations, #deduplication.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
x-corp	🟢 Ready	View Preview	Oct 29, 2026, 8:22 PM

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ tcaldwell-x
❌ mintlify[bot]
_{You have signed the CLA already but the status is still pending? Let us recheck it.}