Skip to content

introduction.mdx

Latest commit

 

History

History
194 lines (135 loc) · 8.68 KB

introduction.mdx

File metadata and controls

194 lines (135 loc) · 8.68 KB
Raw
title X Activity API for streaming user event data
sidebarTitle Introduction
description Overview of the X Activity API for streaming real-time user activity events such as post.create, post.delete, and profile updates from the X Platform.
keywords
activity API
X Activity API
activity events
profile updates
post.create
post.delete
like.create
user activity
real-time events
activity stream

import { Button } from '/snippets/button.mdx';

The X Activity API (XAA) endpoint group allows developers to tap into activity events happening on the X Platform.

A developer can subscribe to events they are interested in such as profile.update.bio, post.create, post.delete 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.

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:

Post events

Post events are triggered when a user creates or deletes a Post.

Event Name Description Filters
post.create Fired when a user creates a Post user_id
post.delete Fired when a user deletes a Post user_id
post.mention.create Fired when someone @mentions the filtered user in a Post user_id
**Post events via XAA vs Filtered Stream:** X Activity API supports `post.create` and `post.delete` events. Subscribe by `user_id` to get real-time notifications when users create or delete Posts.

If you want targeted keyword filtering, boolean logic, geo targeting, language filters, or any of the other operators that the Filtered Stream supports, use the Filtered Stream endpoint instead.

Like events

Like events are triggered when a user likes a Post, or when one of the user's own Posts is liked.

Event Name Description Filters
like.create Fired when a user likes a Post, or one of their Posts is liked user_id, direction
**Direction filter:** The `like.create` event supports an optional `direction` filter set to `outbound` or `inbound`. Use `outbound` for likes the user makes, and `inbound` for likes the user's Posts receive. If no `direction` is specified, both inbound and outbound like events are delivered.

Private event: like.create is a private event and requires user-context (OAuth 2.0) authentication. See Event privacy and authentication below.

Follow events

Follow events are triggered when the filtered user follows another user, or is followed by 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

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.handle Fired when a user updates their handle 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

Chat events

Chat events pertain to the new, encrypted messaging stack, or XChat.

Event Name Description Filters
chat.received Fired when a user receives an encrypted direct message user_id
chat.sent Fired when a user sends an encrypted direct message user_id
chat.conversation_join Fired when a user joins an encrypted chat conversation user_id

Legacy DM events

Legacy DM events pertain to the legacy, unencrypted DM system.

Event Name Description Filters
dm.received Fired when a user receives an unencrypted direct message user_id
dm.sent Fired when a user sends an unencrypted direct message user_id
dm.read Fired when a user reads the filtered users unencrypted DM message, or "read receipt" user_id
dm.indicate_typing Fired when a user is typing a message to the filtered user 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.

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

In future releases, XAA will expand to support additional event types including social interactions, content engagement, monetization features, and more. We will continue to update our docs when new event types become available.

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 performs 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)
  • Post creation (post.create) and deletion (post.delete)

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.

Current private events:

  • Likes (like.create)
  • Encrypted chat received (chat.received)
  • Encrypted chat sent (chat.sent)
  • DM received (dm.received)
  • DM sent (dm.sent)
  • DM read (dm.read)
  • DM typing indicator (dm.indicate_typing)
  • Post mentions (post.mention.create)

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 1,500
Enterprise 75,000
Partner 150,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 setup**

To access these endpoints, you will need:

Learn more about getting access to the X API v2 endpoints in our getting started guide.

Quick start