X Activity API: real-time events without polling

#Quick answer

The X Activity API (XAA) is X's push system for real-time activity. You create one subscription per event type and user ID, point it at a webhook or open a persistent HTTP stream, and X delivers matching events in under a second. It covers posts, replies, quotes, reposts, @mentions, likes, follows, paid subscriptions, encrypted chat, legacy DMs, Spaces, broadcasts, mutes, blocks and OAuth revocations. Public events run on an app-only bearer token; the rest need the user's OAuth consent. Delivery is billed per event on pay-per-use.

Last updated: October 2026

If you have ever built anything that watches an X account, you have written the polling loop: hit the mentions endpoint every 30 seconds, diff the IDs, hope you did not miss anything between calls. XAA is the end of that loop. It also prices each delivered event, which changes the arithmetic in ways the polling version never exposed.

#The event catalogue is much bigger than the launch post suggests

X announced XAA in open beta on 18 October 2025 with five events, all profile updates. That announcement is still the top non-documentation result for the API, and it describes maybe a tenth of what now exists.

A few of those deserve a flag. post.create fires for standalone posts, replies, quote posts and reposts by the filtered user all at once, so you have to inspect in_reply_to_tweet_id or referenced_tweets in the payload to tell them apart. The reply and quote events only fire for direct interactions: a reply to a reply does not reach you, and neither does a quote of a quote. And post.mention.create fires only on an explicit @mention in the post body, not on the implicit mention that a reply carries.

Posts from protected accounts are never delivered, even for events X classifies as public.

#Public events, private events, and what you cannot watch

This is the part that decides whether your idea is buildable at all. X splits the catalogue in two.

Public events can be subscribed to with an app-only bearer token, the one you copy out of the developer console. That list is short: post creation and deletion, the profile updates, and broadcast start and end. You can watch any public account's posting activity without asking anyone.

Private events need the user to authorise your app over OAuth 2.0 and grant a specific scope. Likes, every messaging event, replies, quotes, reposts, @mentions, paid subscriptions, mutes, blocks and broadcast chats are all private. Mentions, replies, quotes and reposts need tweet.read; subscriptions need follows.read; mutes need mute.read; blocks need block.read; broadcast chats need broadcast.read.

For mutes and blocks there is a second limit worth reading twice: the user_id filter matches the person performing the action. You can be told that your authorising user blocked somebody. You cannot be told that somebody blocked your authorising user. If you were planning a "who blocked me" product on top of this, the API is built specifically to refuse it, which matches what X hides about blocks in the app.

#Every tutorial older than March 2026 uses dead event names

On 13 March 2026 X announced that the PascalCase event type format was deprecated as of 18 March 2026, and that the old values would be neither delivered nor accepted after that date.

Copy a subscription body out of the open-beta announcement and you get a 400. Copy a switch statement out of any blog post from 2025 and it silently never matches. The format is dot-separated lowercase with snake_case inside each segment, and there is no compatibility shim.

#What each event costs

X moved the whole API to metered credits in February 2026, which we broke down in X API pricing. XAA deliveries bill the same way, per event, deduplicated inside a 24-hour UTC window.

Two honest caveats. First, the pricing page's webhook table and the XAA reference disagree about post.delete: the price table lists it as not billed, while the XAA documentation says every delivered post event, post.delete included, is billed as a post. Assume you will be charged and treat the free row as a bonus if it holds. Second, X published a billing correction on 16 September 2026 confirming that webhook-delivered XAA events had been under-billed on pay-per-use. Delivery was unaffected, but any cost model you built from an August invoice is wrong on the low side.

Run the numbers before you subscribe to anything noisy. A single account that gets 2,000 replies a day costs $10 a day to watch at post-event rates, which is more than most people expect from a feature marketed as a webhook.

#Narrowing a subscription to one post

Genuinely useful filtering lives in the filter.qualifiers map, which takes up to eight entries. Three qualifiers exist today: conversation_type (direct or group, for chat events), direction (inbound or outbound, for follows, likes and subscriptions), and post_id.

post_id is the interesting one. Attach it to like.create, post.reply.create, post.quote.create or post.repost.create and you only receive events for that specific post:

{
  "event_type": "post.reply.create",
  "filter": {
    "user_id": "1830023695835787264",
    "qualifiers": { "post_id": "1234567890123456789" }
  },
  "webhook_id": "2090847910112202752",
  "tag": "replies to a specific post"
}

That turns a launch thread or a giveaway post into a cheap, bounded event feed instead of a subscription to everything the account will ever do. It narrows the user_id filter rather than replacing it, so the post has to belong to that user. One gotcha: a broad subscription and a post_id subscription for the same event type and user overlap, and X rejects the second one with a DuplicateSubscription error. Pick one shape per event type.

Subscriptions also accept an optional expires_at timestamp in RFC 3339, after which X deletes them for you. Re-posting the same subscription with a new expires_at refreshes it. The PUT endpoint updates the tag and the webhook ID but will not touch expiry, which is an easy hour to lose.

#The Account Activity API is on its way out

If you are maintaining something on the old Account Activity API, X's own migration guide now opens with a deprecation warning that points at XAA for real-time delivery going forward. The replay endpoint was deprecated separately in March 2026. No shutdown date has been published, but the direction is not ambiguous.

The migration is not a rename. Webhook management moved to the v2 Webhooks API, authentication moved to OAuth 2.0, the base path changed from /1.1/account_activity/ to /2/account_activity/, and the "delete all subscriptions for a webhook" call has no v2 equivalent. If you are rewriting that much anyway, rewrite onto XAA rather than onto AAA v2.

#Is it worth building on

For anything that reacts to one account, yes. Sub-second delivery beats a 30-second poll, you stop paying for empty responses, and events like oauth.revoke and profile.update.handle have no sensible polling equivalent at all.

Three things to settle first. Subscription count is the real ceiling: 1,500 on self-serve sounds generous until you multiply event types by accounts. Private events mean a consent flow, so a product that watches other people's replies is not on the table. And if you are building a bot that acts on these events, it still needs the automated account label and a managing account, and X's Developer Guidelines still govern what it may do with what it hears. The API route is the sanctioned one, which is exactly why its rules are written down.

If you want the account watched and replied to without standing up a webhook server, a credit balance and an OAuth consent screen, that is the problem X-Autopilot solves from your own Mac instead. If you want to wire X into an assistant rather than a server, the X MCP server is the shorter path, and getting an X API key is the first step either way.