The X Activity API (XAA) endpoint group allows developers to tap in to activity events happening on the X Platform.
A developer can subscribe to events they are interested in such as profile.update.bio, profile.update.profile_picture etc. and filter for the User ID whose events they want. The matching events for that User ID will be delivered to your app with sub-second latency.
The X Activity API is available as an open beta. While in open beta, please expect potential bugs, breaking changes, or incomplete features.Your feedback is invaluable—report issues via our developer community forums. Delivery Mechanisms
The X Activity API currently supports the following delivery mechanisms to send events to your app:
Supported Event Types
Currently, X Activity API supports the following event types, organized by category:
Profile Events
Profile events are triggered when a user makes changes to their profile information.
| Event Name | Description | Filters |
|---|
profile.update.bio | Fired when a user updates their profile bio | user_id |
profile.update.profile_picture | Fired when a user updates their profile picture | user_id |
profile.update.banner_picture | Fired when a user updates their profile banner | user_id |
profile.update.screenname | Fired when a user updates their display name | user_id |
profile.update.geo | Fired when a user updates their profile location | user_id |
profile.update.url | Fired when a user updates their profile website URL | user_id |
profile.update.verified_badge | Fired when a user updates their verified badge | user_id |
profile.update.affiliate_badge | Fired when a user updates their affiliate badge | user_id |
Follow Events
Follow events are triggered when a user follows or unfollows another user.
| Event Name | Description | Filters |
|---|
follow.follow | Fired when a user follows another user | user_id |
follow.unfollow | Fired when a user unfollows another user | user_id |
Spaces Events
Spaces events are triggered when a user starts or ends a Space.
| Event Name | Description | Filters |
|---|
spaces.start | Fired when a user starts a Space | user_id |
spaces.end | Fired when a user ends a Space | user_id |
Chat Events
Chat events are triggered when a user sends or receives a direct message.
| Event Name | Description | Filters |
|---|
chat.received | Fired when a user receives a direct message | user_id |
chat.sent | Fired when a user sends a direct message | user_id |
News Events
News events provide updates on trending topics and headlines curated by Grok.
| Event Name | Description | Filters |
|---|
news.new | New grok-curated trends and headlines | keyword |
Enterprise Only: The news.new event is only available to Enterprise and Partner tier accounts at this time.
Note: XAA does not deliver posts. For real-time post delivery, see our Filtered Stream endpoint, which allows developers to filter for and stream posts in real-time. Event Privacy and Authentication
The X Activity API distinguishes between public events and private events as at parity with the X app as explained below.
Public Events
Public events are activities that a public user account perform publicly that are visible to all X users. These events are visible to all users on the X platform and don’t require OAuth authentication from the user in order to view.
Current public events:
- Profile updates (bio, picture, banner, location, URL, username changes)
For these public events, you can create subscriptions by specifying the user ID in your filter and receive them via XAA.
Private Events
Private events are activities that require explicit user consent through OAuth authentication. A User has to authenticate via X and give explicit permission to a developer app to access these events.
Authentication requirements for private events:
- The user must authenticate your application via OAuth 2.0
- Your application must obtain appropriate OAuth scopes
- The user must explicitly grant permission for your app to access these events
- Subscriptions for private events can only be created for users who have authorized your application
Subscription Limits
The X Activity API has different subscription limits based on your account tier:
| Package Tier | Maximum Subscriptions |
|---|
| Self-serve | 1000 |
| Enterprise | 50,000 |
| Partner | 100,000 |
Endpoints
| Method | Endpoint | Description |
|---|
| GET | /2/activity/stream | Connect to activity stream |
| POST | /2/activity/subscriptions | Create a subscription |
| GET | /2/activity/subscriptions | List subscriptions |
| PUT | /2/activity/subscriptions/:id | Update a subscription |
| DELETE | /2/activity/subscriptions/:id | Delete a subscription |
Account setupTo access these endpoints, you will need:Learn more about getting access to the X API v2 endpoints in our getting started guide. 
