Event types and authentication

This page lists supported event types and explains how they line up with authentication. For XAA, whether an event is public or private is the same question as whether you may use app-only credentials or must use user credentials. The privacy class tells you which OAuth style X expects.

Supported event types

Most filters use user_id (numeric user ID). The exception is news.new, which uses a keyword filter.

The Privacy column is how X classifies the event for XAA: Public (app Bearer is the usual subscription path, subject to tier rules), Private (user OAuth required), or Multi (both shapes exist, for example a path that is public under Enterprise app auth and a path that is private under pay-per-user / user context, per product configuration).

Profile events

Event type	Description	Privacy	Filter
profile.update.bio	User updates their profile bio	Public	user_id
profile.update.profile_picture	User updates their profile picture	Public	user_id
profile.update.banner_picture	User updates their profile banner	Public	user_id
profile.update.screenname	User updates their display name	Public	user_id
profile.update.handle	User updates their handle	Public	user_id
profile.update.geo	User updates their profile location	Public	user_id
profile.update.url	User updates their profile website URL	Public	user_id
profile.update.verified_badge	User updates their verified badge	Public	user_id
profile.update.affiliate_badge	User updates their affiliate badge	Public	user_id

Follow events

Event type	Description	Privacy	Filter
follow.follow	User follows another user	Multi	user_id, optional direction
follow.unfollow	User unfollows another user	Multi	user_id, optional direction

Direction filter: For follow.follow and follow.unfollow, the filter may include direction: "inbound" or "outbound" alongside user_id. See Direction filter.

Multi here means XAA supports more than one auth posture: some trusted packages may subscribe with application-only access, while pay-per-user flows treat the same event as private and require user OAuth. Confirm the matrix for your package on docs.x.com.

Post events

Event type	Description	Privacy	Filter
post.create	User creates a post (including replies, quotes, and reposts)	Public	user_id
post.delete	User deletes one of their posts	Public	user_id
post.mention.create	User is @mentioned in a post	Private	user_id

Scope: These events fire for posts authored by the filtered user_id (mentions are for the mentioned user). For a high-volume, rule-based firehose of public posts across all of X, the Filtered Stream endpoint is still the right tool; XAA post events are best for tracking activity from specific accounts you subscribe to.

Like events

Event type	Description	Privacy	Filter
like.create	User likes a post	Private	user_id, optional direction

Direction filter: like.create accepts an optional direction ("inbound" or "outbound") alongside user_id. See Direction filter.

Likes are private: subscribing requires user OAuth. See Subscribing to private events.

Spaces events

Event type	Description	Privacy	Filter
spaces.start	User starts a Space	Public	user_id
spaces.end	User ends a Space	Public	user_id

Legacy DM events

Unencrypted, legacy direct messages.

Event type	Description	Privacy	Filter
dm.received	User receives an unencrypted DM	Private	user_id
dm.sent	User sends an unencrypted DM	Private	user_id
dm.read	User reads a DM or read receipt for the filtered user	Private	user_id
dm.indicate_typing	User is typing a message to the filtered user	Private	user_id

Chat events (encrypted / XChat)

Event type	Description	Privacy	Filter
chat.received	User receives an encrypted direct message	Private	user_id
chat.sent	User sends an encrypted direct message	Private	user_id
chat.conversation_join	User joins an encrypted chat conversation	Private	user_id
chat.indicate_typing	User is typing in an encrypted chat	Private	user_id
chat.read	User read state in encrypted chat	Private	user_id

The last two rows are in development; availability and payload fields may change—watch X developer docs.

News events

Event type	Description	Privacy	Filter
news.new	New Grok-curated trends and headlines	Public	keyword

news.new is Enterprise and Partner tier only at this time.

XAA continues to add more event types over time; check X developer documentation for the latest list.

Subscription limits

Package tier	Maximum subscriptions
Self-serve	1,000
Enterprise	50,000
Partner	100,000

Public vs private events = app vs user auth

X labels each XAA event type as public or private in line with the main app. That label is not a separate concept from authentication: it tells you whose OAuth grant must back your requests.

Private events are activities that are not universally visible on X (for example DMs and encrypted chat). Accessing them requires explicit user authorization: OAuth 2.0 user context or OAuth 1.0a user access. Use xurl --auth oauth2 or xurl --auth oauth1 after registering the matching profile. See the xurl README for setup.

Public events are activities already visible on the platform. Subscribing uses OAuth 2.0 application-only authentication: a Bearer token for your app. In this book that is xurl auth app --bearer-token … then --auth app (see the xURL chapter).

	Public events	Private events
Relationship to your app	Data X treats as already public; no personal OAuth grant needed	User must explicitly authorize your app before you can subscribe
OAuth model	OAuth 2.0 app-only (Bearer token)	OAuth 2.0 user context or OAuth 1.0a user access
xurl	--auth app	--auth oauth2 or --auth oauth1
Typical subscription rule	Filter by user_id (or keyword for news.new)	Filter only for users who have authorized your app