Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions changelog.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,18 @@ keywords: ["changelog", "API updates", "release notes", "what's new", "API chang

To subscribe to updates, please [**“Turn on notifications”**](https://help.x.com/en/managing-your-account/notifications-on-mobile-devices#:~:text=In%20the%20top%20menu,%20you,you%20would%20like%20to%20receive) for [**@API**](https://x.com/api). You can also follow this changelog in your feed reader via the [**RSS feed**](https://docs.x.com/changelog/rss.xml).

<Update label="Nov 22, 2026" description="X API">
### X API pricing update: expansions billed per resource

Expansion objects now count toward usage. Objects returned through [expansions](/x-api/fundamentals/expansions) (the `includes` section of a response) are billed at the standard pay-per-usage rate for that resource, the same as a direct lookup. This covers post, user, media, poll, place, and topic expansions.

- New read rates: **Media &dollar;0.005**, **Poll &dollar;0.005**, **Place &dollar;0.005**, and **Topic &dollar;0.005** per resource. Post (&dollar;0.005) and User (&dollar;0.010) rates are unchanged. Each media object counts separately, so a Post with four photos returned with `expansions=attachments.media_keys` is four Media resources.
- On [Owned Reads](/x-api/getting-started/pricing#expansions-on-owned-reads) to `GET /2/users/{id}/tweets`, `/mentions`, and `/liked_tweets`, expansion objects are billed at the Owned Read rate of &dollar;0.001 per resource and deduplicated together with the primary results. Owned Reads still require `{id}` to be the authenticated user who owns the developer app; third-party apps reading their users' data through OAuth are billed at standard rates, including expansions.
- The 24-hour UTC [deduplication](/x-api/getting-started/pricing#deduplication) window applies to every billable resource, including users, media, polls, places, and topics returned through expansions.

See [Pricing](/x-api/getting-started/pricing#expansions) for details and examples.
</Update>

<Update label="Oct 26, 2026" description="X API v2">
### Improved Direct Message refusal error details

Expand Down
10 changes: 7 additions & 3 deletions sliders.js
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,10 @@ function getPricingTypeDisplayName(pricingType) {
// EventTypePricing
'Post': 'Post: Read',
'User': 'User: Read',
'Media': 'Media: Read',
'Poll': 'Poll: Read',
'Place': 'Place: Read',
'Topic': 'Topic: Read',
'List': 'List: Read',
'Space': 'Space: Read',
'Community': 'Community: Read',
Expand Down Expand Up @@ -280,8 +284,8 @@ function buildSlugToPricingTypeMapping() {
mapping['get-historical-post-insights'] = 'CountsRecent'; // Placeholder - may need to verify

// Media lookup endpoints
mapping['get-media-by-media-key'] = 'CountsRecent'; // Placeholder - may need to verify
mapping['get-media-by-media-keys'] = 'CountsRecent'; // Placeholder - may need to verify
mapping['get-media-by-media-key'] = 'Media';
mapping['get-media-by-media-keys'] = 'Media';
mapping['get-media-upload-status'] = 'CountsRecent'; // Placeholder - may need to verify

// News endpoints
Expand Down Expand Up @@ -460,7 +464,7 @@ function createSliderContent(endpointName, unitCost, pricingType, options = {})
const maxUsage = 50000; // 50k

// Determine if this is event type (per resource) or request type (per request)
const eventTypePricing = ['Post', 'User', 'List', 'Space', 'Community', 'DirectMessage', 'ProfileUpdate', 'Like', 'Follow', 'Mute', 'Block', 'News'];
const eventTypePricing = ['Post', 'User', 'Media', 'Poll', 'Place', 'Topic', 'List', 'Space', 'Community', 'DirectMessage', 'ProfileUpdate', 'Like', 'Follow', 'Mute', 'Block', 'News'];
const isEventType = eventTypePricing.includes(pricingType);
const unitLabel = isEventType ? 'per resource' : 'per request';
const usageLabelText = isEventType ? 'resources' : 'requests';
Expand Down
7 changes: 6 additions & 1 deletion x-api/fundamentals/expansions.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: Expansions
description: "Use X API v2 expansions to include related users, media, polls, places, and referenced posts inside the includes section of a single response."
sidebarTitle: Expansions
keywords: ["expansions", "expand objects", "object expansion", "nested objects", "related objects"]
keywords: ["expansions", "expand objects", "object expansion", "nested objects", "related objects", "expansion billing", "expansion pricing"]
---

Expansions let you include related objects in a single API response. Instead of making multiple requests, get a post and its author, media, or referenced posts in one call.
Expand Down Expand Up @@ -39,6 +39,10 @@ Response:

The `author_id` in `data` links to the user object in `includes`.

<Note>
**Billing:** On pay-per-usage plans, objects returned in `includes` are billed at the same per-resource rate as a direct lookup. This covers post, user, media, poll, place, and topic expansions, and each object counts separately: a Post with four photos returns four billable media objects. Request only the expansions you need. See [Expansions](/x-api/getting-started/pricing#expansions) on the pricing page for rates, Owned Read behavior, and deduplication.
</Note>

---

## Post expansions
Expand Down Expand Up @@ -73,6 +77,7 @@ The `author_id` in `data` links to the user object in `includes`.
| `host_ids` | User object(s) | Get Space hosts |
| `speaker_ids` | User object(s) | Get Space speakers |
| `invited_user_ids` | User object(s) | Get invited users |
| `topic_ids` | Topic object(s) | Get Space topics |

---

Expand Down
15 changes: 11 additions & 4 deletions x-api/fundamentals/post-cap.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -42,14 +42,17 @@ Posts retrieved from these endpoints count toward usage:
## Deduplication

<Note>
**Daily deduplication**: If the same post is returned from multiple queries within a day, it only counts once for billing.
**Daily deduplication**: All billable resources are deduplicated within a 24-hour UTC day window. If the same resource is returned from multiple queries within that window, it only counts once for billing. This covers Posts and every other billable resource, including users, media, polls, places, and topics returned through [expansions](/x-api/fundamentals/expansions).
</Note>

This means:

- Retrieving the same post multiple times in one day = 1 charge
- Retrieving a post again the next day = 1 additional charge
- Different posts in the same request = each counts separately
- Retrieving the same post multiple times in one UTC day = 1 charge
- Retrieving the same user, media, poll, place, or topic multiple times in one UTC day, including through expansions = 1 charge
- Retrieving a resource again after the window resets at midnight UTC = 1 additional charge
- Different resources in the same request, including each object in `includes` = each counts separately

See [Pricing](/x-api/getting-started/pricing#deduplication) for details.

---

Expand Down Expand Up @@ -129,6 +132,10 @@ No. Pay only for what you use. You can have months with zero usage and zero cost
Each unique post delivered through filtered stream counts toward usage, subject to daily deduplication.
</Accordion>

<Accordion title="Are objects returned through expansions billed?">
Yes. Posts, users, media, polls, places, and topics returned in `includes` are billed at the same per-resource rate as a direct lookup, and each object counts separately. On [qualifying Owned Read requests](/x-api/getting-started/pricing#expansions-on-owned-reads), they are billed at the Owned Read rate. See [Expansions](/x-api/getting-started/pricing#expansions) on the pricing page.
</Accordion>

<Accordion title="Do failed requests count?">
No. Only successful responses that return data are billed.
</Accordion>
Expand Down
51 changes: 49 additions & 2 deletions x-api/getting-started/pricing.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: X API pay-per-usage pricing and credits
sidebarTitle: Pricing
description: "The X API uses pay-per-usage pricing with no subscriptions. Buy credits, set spending limits, and earn up to 20% back in free xAI API credits."
keywords: ["X API pricing", "API pricing", "pay-per-usage", "API credits", "billing", "deduplication", "API costs", "auto-recharge", "spending limit", "spend cap", "xAI credits", "free credits", "Grok API"]
keywords: ["X API pricing", "API pricing", "pay-per-usage", "API credits", "billing", "deduplication", "expansions", "owned reads", "API costs", "auto-recharge", "spending limit", "spend cap", "xAI credits", "free credits", "Grok API"]
---

import { Button } from '/snippets/button.mdx';
Expand Down Expand Up @@ -52,6 +52,10 @@ Charged per resource returned in the response.
|:---------|:----------|
| **Posts: Read** | &dollar;0.005 per resource |
| **User: Read** | &dollar;0.010 per resource |
| **Media: Read** | &dollar;0.005 per resource |
| **Poll: Read** | &dollar;0.005 per resource |
| **Place: Read** | &dollar;0.005 per resource |
| **Topic: Read** | &dollar;0.005 per resource |
| **DM Event: Read** | &dollar;0.010 per resource |
| **Following/Followers: Read** | &dollar;0.010 per resource |
| **List: Read** | &dollar;0.005 per resource |
Expand All @@ -63,6 +67,8 @@ Charged per resource returned in the response.
| **Block: Read** | &dollar;0.001 per resource |
| **Profile Update: Read** | &dollar;0.005 per resource |

Media, Poll, Place, and Topic reads cost &dollar;0.005 for each media, poll, place, or topic object returned, including objects returned through [expansions](#expansions). **Media: Read** is separate from **Media Metadata** under [Write operations](#write-operations), which is charged per request when you create or delete media metadata such as alt text or subtitles.

<Note>
Pay-per-usage plans are capped at **3 million Post reads per monthly billing cycle**. If you need higher volume, upgrade to an [Enterprise plan](/forms/enterprise-api-interest).
</Note>
Expand Down Expand Up @@ -122,6 +128,29 @@ Webhook events delivered through the [X Activity API](/x-api/activity/introducti

---

## Expansions

Objects returned through [expansions](/x-api/fundamentals/expansions) (the `includes` section of a response) are billed at the same per-resource rate as a direct lookup. This applies to post, user, media, poll, place, and topic expansions.

| Object in `includes` | Returned by expansions such as | Billed as |
|:---------------------|:-------------------------------|:----------|
| Posts | `referenced_tweets.id`, `pinned_tweet_id` | Posts: Read (&dollar;0.005 per resource) |
| Users | `author_id`, `entities.mentions.username` | User: Read (&dollar;0.010 per resource) |
| Media | `attachments.media_keys` | Media: Read (&dollar;0.005 per resource) |
| Polls | `attachments.poll_ids` | Poll: Read (&dollar;0.005 per resource) |
| Places | `geo.place_id` | Place: Read (&dollar;0.005 per resource) |
| Topics | `topic_ids` (Spaces) | Topic: Read (&dollar;0.005 per resource) |

Each object in `includes` counts as one resource. A Post with four photos requested with `expansions=attachments.media_keys` returns four media objects, billed as four Media: Read resources. Expansion objects are [deduplicated](#deduplication) like any other resource, so the same object returned again in the same UTC day is not charged again.

For example, a recent search request with `max_results=100&expansions=author_id,attachments.media_keys` that returns 100 Posts, 60 distinct authors, and 40 media objects, none of them already charged that day, costs 100 × &dollar;0.005 + 60 × &dollar;0.010 + 40 × &dollar;0.005 = **&dollar;1.30**.

<Tip>
Request only the expansions your app uses. Each post, user, media, poll, place, or topic object returned in `includes` is billed.
</Tip>

---

## Owned Reads

Owned Reads are requests made by your own developer app for your own data (posts, bookmarks, followers, likes, lists, and more). These endpoints are priced at **&dollar;0.001 per resource** (1,000 resources for &dollar;1).
Expand All @@ -143,10 +172,28 @@ The following endpoints qualify for Owned Read pricing when `{id}` matches the a
| `GET /2/users/{id}/list_memberships` | Lists you belong to |
| `GET /2/users/{id}/pinned_lists` | Your pinned lists |

<Note>
Third-party apps that read their users' data through OAuth are not making Owned Reads, because the authenticated user does not own the developer app. Those requests, including their expansions, are billed at the standard rates.
</Note>

<Tip>
Owned Reads make it significantly cheaper to build apps that work with a user's own data, such as dashboard apps, personal analytics, or account management tools.
</Tip>

### Expansions on Owned Reads

On Owned Read requests to the following endpoints, which track expansions, objects returned through [expansions](#expansions) are billed at the Owned Read rate of **&dollar;0.001 per resource** instead of their standard rate:

| Endpoint | Description |
|:---------|:------------|
| `GET /2/users/{id}/tweets` | Your own posts |
| `GET /2/users/{id}/mentions` | Your mentions |
| `GET /2/users/{id}/liked_tweets` | Posts you liked |

Expansion objects on these requests are deduplicated together with the primary results, so a resource that appears in both `data` and `includes` is charged once.

For example, requesting 100 of your own Posts with `expansions=author_id,attachments.media_keys` that returns 1 user (you) and 30 media objects, none of them already charged that day, costs 131 × &dollar;0.001 = **&dollar;0.131**.

---

## Deduplication
Expand All @@ -156,7 +203,7 @@ All resources are deduplicated within a **24-hour UTC day window**. If you reque
This means:
- Requesting the same Post multiple times in a day counts as one charge
- The deduplication window resets at midnight UTC
- This applies to all billable resources (Posts, users, etc.)
- This applies to all billable resources, not just Posts, including users, media, polls, places, and topics returned through [expansions](#expansions)

<Note>
Deduplication is a **soft guarantee**. While it occurs in the vast majority of cases, there may be specific edge cases like service outages that result in resources not being deduplicated.
Expand Down