> ## Documentation Index
> Fetch the complete documentation index at: https://x-preview-mintlify-58ae8dc1.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# X Activity API event payload examples
> Sample JSON payloads for X Activity API events, including posts, likes, follows, profile updates, chat, DMs, mutes, blocks, Spaces, news, and OAuth revokes.
Events delivered by the X Activity API (via the [persistent HTTP stream](/x-api/activity/activity-stream) or [webhooks](/x-api/webhooks/introduction)) share a common envelope:
| Field | Description |
| ------------ | ------------------------------------------------------------------- |
| `event_uuid` | Unique identifier for this event delivery |
| `filter` | The filter that matched (for example `user_id` or `keyword`) |
| `event_type` | The subscribed event type |
| `tag` | Optional tag from your subscription (when set) |
| `payload` | Event-specific data |
| `includes` | Optional expanded objects (users, tweets, and so on) when available |
```json title="Event envelope" lines wrap icon="https://mintcdn.com/x-preview-mintlify-58ae8dc1/MHeQz9WFqPMHNFqx/icons/xds/icon-brackets.svg?fit=max&auto=format&n=MHeQz9WFqPMHNFqx&q=85&s=d8bafc321dfd8d57423ff90cf84f7c76" theme={null}
{
"data": {
"event_uuid": "2080761390344937796",
"filter": {
"user_id": "1111111111111111111"
},
"event_type": "post.create",
"tag": "posts",
"payload": {},
"includes": {}
}
}
```
The examples below are representative real-world payloads with sample account identifiers and profile fields substituted for documentation. Field availability can vary based on account settings, expansions, and the object state at delivery time. See the [introduction](/x-api/activity/introduction) for the full list of supported event types and authentication requirements.
Payload samples use Mintlify code blocks with titles, line numbers, and wrapping. Longer examples are expandable—click to expand and copy the full delivery body.
***
## Post events
### `post.create`
Fired when the filtered user creates a Post. Fires for standalone Posts, replies, quote Posts, and reposts by the filtered user. Inspect the payload to distinguish the type — for example, `in_reply_to_tweet_id` is present on replies, and `referenced_tweets` indicates quotes and reposts. The `payload` is a Post object; `includes` may contain related users and tweets.
```json title="post.create" expandable lines wrap icon="https://mintcdn.com/x-preview-mintlify-58ae8dc1/MHeQz9WFqPMHNFqx/icons/xds/icon-brackets.svg?fit=max&auto=format&n=MHeQz9WFqPMHNFqx&q=85&s=d8bafc321dfd8d57423ff90cf84f7c76" theme={null}
{
"data": {
"event_uuid": "2080761390344937796",
"filter": {
"user_id": "1111111111111111111"
},
"event_type": "post.create",
"tag": "posts",
"payload": {
"public_metrics": {
"retweet_count": 0,
"retweet_count_str": "0",
"reply_count": 0,
"reply_count_str": "0",
"like_count": 0,
"like_count_str": "0",
"quote_count": 0,
"quote_count_str": "0",
"bookmark_count": 0,
"bookmark_count_str": "0",
"impression_count": 0,
"impression_count_str": "0"
},
"lang": "en",
"created_at": "2026-07-24T21:05:48.000Z",
"author_id": "1111111111111111111",
"reply_settings": "everyone",
"display_text_range": [
0,
34
],
"paid_partnership": false,
"id": "2080761390344937796",
"possibly_sensitive": false,
"edit_history_tweet_ids": [
"2080761390344937796"
],
"conversation_id": "2080761390344937796",
"text": "Hello from the Activity API",
"edit_controls": {
"edits_remaining": 5,
"edits_remaining_str": "5",
"is_edit_eligible": true,
"editable_until": "2026-07-24T22:05:48.000Z"
}
},
"includes": {
"tweets": [
{
"public_metrics": {
"retweet_count": 0,
"retweet_count_str": "0",
"reply_count": 0,
"reply_count_str": "0",
"like_count": 0,
"like_count_str": "0",
"quote_count": 0,
"quote_count_str": "0",
"bookmark_count": 0,
"bookmark_count_str": "0",
"impression_count": 0,
"impression_count_str": "0"
},
"lang": "en",
"created_at": "2026-07-24T21:05:48.000Z",
"author_id": "1111111111111111111",
"reply_settings": "everyone",
"display_text_range": [
0,
34
],
"paid_partnership": false,
"id": "2080761390344937796",
"possibly_sensitive": false,
"edit_history_tweet_ids": [
"2080761390344937796"
],
"conversation_id": "2080761390344937796",
"text": "Hello from the Activity API",
"edit_controls": {
"edits_remaining": 5,
"edits_remaining_str": "5",
"is_edit_eligible": true,
"editable_until": "2026-07-24T22:05:48.000Z"
}
}
],
"users": [
{
"entities": {
"url": {
"urls": [
{
"start": 0,
"start_str": "0",
"end": 23,
"end_str": "23",
"url": "https://t.co/xxxxxxxx",
"expanded_url": "https://example.com",
"display_url": "https://example.com"
}
]
},
"description": {
"mentions": [
{
"start": 49,
"start_str": "49",
"end": 51,
"end_str": "51",
"username": "X"
},
{
"start": 52,
"start_str": "52",
"end": 64,
"end_str": "64",
"username": "XDevelopers"
}
]
}
},
"name": "Example User",
"protected": false,
"verified": true,
"description": "Building with the X AnotherUser @XDevelopers",
"is_identity_verified": true,
"affiliation": {
"badge_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
"url": "https://twitter.com/X",
"user_id": [
"783214"
],
"description": "X"
},
"location": "San Francisco, CA",
"username": "ExampleUser",
"verified_type": "blue",
"pinned_tweet_id": "1968451310203859083",
"created_at": "2023-10-23T13:44:53.000Z",
"id": "1111111111111111111",
"profile_image_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
"url": "https://t.co/xxxxxxxx",
"profile_banner_url": "https://pbs.twimg.com/profile_banners/1111111111111111111/1600000000",
"most_recent_tweet_id": "2080761390344937796",
"public_metrics": {
"followers_count": 5502,
"followers_count_str": "5502",
"following_count": 652,
"following_count_str": "652",
"tweet_count": 790,
"tweet_count_str": "790",
"listed_count": 47,
"listed_count_str": "47",
"like_count": 8011,
"like_count_str": "8011",
"media_count": 79,
"media_count_str": "79"
},
"profile_geo_enrichment": {
"potential_locations": [
{
"geo_entity": {
"entity_id": "5391959",
"display_name": "San Francisco, California, United States",
"country_code": "US",
"region": "California",
"sub_region": "San Francisco County",
"locality": "San Francisco",
"population": 873965,
"population_str": "873965",
"geo_point": {
"latitude": 37.77493,
"longitude": -122.41942
}
}
}
]
}
}
]
}
}
}
```
### `post.delete`
Fired when the filtered user deletes a Post. The `payload` contains the deleted Post ID and author ID.
```json title="post.delete" expandable lines wrap icon="https://mintcdn.com/x-preview-mintlify-58ae8dc1/MHeQz9WFqPMHNFqx/icons/xds/icon-brackets.svg?fit=max&auto=format&n=MHeQz9WFqPMHNFqx&q=85&s=d8bafc321dfd8d57423ff90cf84f7c76" theme={null}
{
"data": {
"event_uuid": "-2781149976877970683",
"filter": {
"user_id": "1111111111111111111"
},
"event_type": "post.delete",
"tag": "post-deletes",
"payload": {
"id": "2080761269309813134",
"author_id": "1111111111111111111"
},
"includes": {
"users": [
{
"data": {
"profile_image_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
"affiliation": {
"badge_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
"url": "https://twitter.com/X",
"description": "X"
},
"protected": false,
"id": "1111111111111111111",
"username": "ExampleUser",
"verified_type": "blue",
"verified": true,
"profile_banner_url": "https://pbs.twimg.com/profile_banners/1111111111111111111/1600000000",
"entities": {
"url": {
"urls": [
{
"start": 0,
"start_str": "0",
"end": 23,
"end_str": "23",
"url": "https://t.co/xxxxxxxx",
"expanded_url": "https://example.com",
"display_url": "https://example.com"
}
]
},
"description": {
"mentions": [
{
"start": 49,
"start_str": "49",
"end": 51,
"end_str": "51",
"username": "X"
},
{
"start": 52,
"start_str": "52",
"end": 64,
"end_str": "64",
"username": "XDevelopers"
}
]
}
},
"public_metrics": {
"followers_count": 5502,
"followers_count_str": "5502",
"following_count": 651,
"following_count_str": "651",
"tweet_count": 789,
"tweet_count_str": "789",
"listed_count": 47,
"listed_count_str": "47",
"like_count": 8010,
"like_count_str": "8010",
"media_count": 79,
"media_count_str": "79"
},
"url": "https://t.co/xxxxxxxx",
"created_at": "2023-10-23T13:44:53.000Z",
"description": "Building with the X AnotherUser @XDevelopers",
"is_identity_verified": true,
"location": "San Francisco, CA",
"name": "Example User"
}
}
]
}
}
}
```
### `post.mention.create`
Fired when another user explicitly @mentions the filtered user in the body of a Post. Does not fire for implicit mentions carried by replies or reposts. Private event — requires user-context authentication with the `tweet.read` scope.
```json title="post.mention.create" expandable lines wrap icon="https://mintcdn.com/x-preview-mintlify-58ae8dc1/MHeQz9WFqPMHNFqx/icons/xds/icon-brackets.svg?fit=max&auto=format&n=MHeQz9WFqPMHNFqx&q=85&s=d8bafc321dfd8d57423ff90cf84f7c76" theme={null}
{
"data": {
"event_uuid": "2080765813578191303",
"filter": {
"user_id": "1111111111111111111"
},
"event_type": "post.mention.create",
"tag": "mentions",
"payload": {
"paid_partnership": false,
"created_at": "2026-07-24T21:23:23.000Z",
"edit_history_tweet_ids": [
"2080765813578191303"
],
"conversation_id": "2080765813578191303",
"display_text_range": [
0,
16
],
"edit_controls": {
"edits_remaining": 5,
"edits_remaining_str": "5",
"is_edit_eligible": true,
"editable_until": "2026-07-24T22:23:23.000Z"
},
"text": "hey @ExampleUser",
"entities": {
"mentions": [
{
"start": 4,
"start_str": "4",
"end": 16,
"end_str": "16",
"username": "ExampleUser",
"id": "1111111111111111111"
}
]
},
"author_id": "2222222222222222222",
"possibly_sensitive": false,
"public_metrics": {
"retweet_count": 0,
"retweet_count_str": "0",
"reply_count": 0,
"reply_count_str": "0",
"like_count": 0,
"like_count_str": "0",
"quote_count": 0,
"quote_count_str": "0",
"bookmark_count": 0,
"bookmark_count_str": "0",
"impression_count": 0,
"impression_count_str": "0"
},
"reply_settings": "everyone",
"id": "2080765813578191303",
"lang": "und"
},
"includes": {
"users": [
{
"public_metrics": {
"followers_count": 97,
"followers_count_str": "97",
"following_count": 1,
"following_count_str": "1",
"tweet_count": 50,
"tweet_count_str": "50",
"listed_count": 4,
"listed_count_str": "4",
"like_count": 26,
"like_count_str": "26",
"media_count": 3,
"media_count_str": "3"
},
"profile_banner_url": "",
"username": "OtherUser",
"protected": false,
"is_identity_verified": false,
"affiliation": {
"badge_url": "https://pbs.twimg.com/semantic_core_img/1428827730364096519/4ZXpTBhS?format=png&name=orig",
"description": "Automated"
},
"most_recent_tweet_id": "2080765813578191303",
"verified_type": "none",
"description": "",
"created_at": "2026-04-20T19:55:59.000Z",
"profile_image_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
"name": "OtherUser",
"verified": false,
"url": "",
"id": "2222222222222222222"
},
{
"public_metrics": {
"followers_count": 5502,
"followers_count_str": "5502",
"following_count": 651,
"following_count_str": "651",
"tweet_count": 789,
"tweet_count_str": "789",
"listed_count": 46,
"listed_count_str": "46",
"like_count": 8010,
"like_count_str": "8010",
"media_count": 79,
"media_count_str": "79"
},
"profile_banner_url": "https://pbs.twimg.com/profile_banners/1111111111111111111/1600000000",
"username": "ExampleUser",
"protected": false,
"is_identity_verified": true,
"affiliation": {
"user_id": [
"783214"
],
"badge_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
"url": "https://twitter.com/X",
"description": "X"
},
"most_recent_tweet_id": "2080761269309813134",
"verified_type": "blue",
"description": "Building with the X AnotherUser @XDevelopers",
"pinned_tweet_id": "1968451310203859083",
"created_at": "2023-10-23T13:44:53.000Z",
"profile_image_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
"name": "Example User",
"verified": true,
"url": "https://t.co/xxxxxxxx",
"location": "San Francisco, CA",
"id": "1111111111111111111",
"entities": {
"url": {
"urls": [
{
"start": 0,
"start_str": "0",
"end": 23,
"end_str": "23",
"url": "https://t.co/xxxxxxxx",
"expanded_url": "https://developer.x.com",
"display_url": "developer.x.com"
}
]
},
"description": {
"mentions": [
{
"start": 48,
"start_str": "48",
"end": 50,
"end_str": "50",
"username": "X"
},
{
"start": 51,
"start_str": "51",
"end": 63,
"end_str": "63",
"username": "XDevelopers"
}
]
}
}
}
],
"tweets": [
{
"paid_partnership": false,
"created_at": "2026-07-24T21:23:23.000Z",
"edit_history_tweet_ids": [
"2080765813578191303"
],
"conversation_id": "2080765813578191303",
"display_text_range": [
0,
16
],
"edit_controls": {
"edits_remaining": 5,
"edits_remaining_str": "5",
"is_edit_eligible": true,
"editable_until": "2026-07-24T22:23:23.000Z"
},
"text": "hey @ExampleUser",
"entities": {
"mentions": [
{
"start": 4,
"start_str": "4",
"end": 16,
"end_str": "16",
"username": "ExampleUser",
"id": "1111111111111111111"
}
]
},
"author_id": "2222222222222222222",
"possibly_sensitive": false,
"public_metrics": {
"retweet_count": 0,
"retweet_count_str": "0",
"reply_count": 0,
"reply_count_str": "0",
"like_count": 0,
"like_count_str": "0",
"quote_count": 0,
"quote_count_str": "0",
"bookmark_count": 0,
"bookmark_count_str": "0",
"impression_count": 0,
"impression_count_str": "0"
},
"reply_settings": "everyone",
"id": "2080765813578191303",
"lang": "und"
}
]
}
}
}
```
### `post.reply.create`
Fired when a user other than the filtered user posts a direct reply to a Post by the filtered user. Direct replies only (does not fire for replies to replies). Private event — requires user-context authentication with the `tweet.read` scope. The `payload` is a Post object for the reply; `includes` may contain related users and tweets (including the Post being replied to).
```json title="post.reply.create" expandable lines wrap icon="https://mintcdn.com/x-preview-mintlify-58ae8dc1/MHeQz9WFqPMHNFqx/icons/xds/icon-brackets.svg?fit=max&auto=format&n=MHeQz9WFqPMHNFqx&q=85&s=d8bafc321dfd8d57423ff90cf84f7c76" theme={null}
{
"data": {
"event_uuid": "3091827364059182736",
"filter": {
"user_id": "1111111111111111111"
},
"event_type": "post.reply.create",
"tag": "replies",
"payload": {
"paid_partnership": false,
"created_at": "2026-08-12T18:00:00.000Z",
"edit_history_tweet_ids": [
"2090000000000000001"
],
"conversation_id": "2080761390344937796",
"in_reply_to_tweet_id": "2080761390344937796",
"in_reply_to_user_id": "1111111111111111111",
"referenced_tweets": [
{
"type": "replied_to",
"id": "2080761390344937796"
}
],
"display_text_range": [
14,
45
],
"text": "@ExampleUser Great post — thanks for sharing!",
"entities": {
"mentions": [
{
"start": 0,
"start_str": "0",
"end": 12,
"end_str": "12",
"username": "ExampleUser",
"id": "1111111111111111111"
}
]
},
"author_id": "2222222222222222222",
"possibly_sensitive": false,
"public_metrics": {
"retweet_count": 0,
"retweet_count_str": "0",
"reply_count": 0,
"reply_count_str": "0",
"like_count": 0,
"like_count_str": "0",
"quote_count": 0,
"quote_count_str": "0",
"bookmark_count": 0,
"bookmark_count_str": "0",
"impression_count": 0,
"impression_count_str": "0"
},
"reply_settings": "everyone",
"id": "2090000000000000001",
"lang": "en"
},
"includes": {}
}
}
```
### `post.quote.create`
Fired when a user other than the filtered user quote Posts a Post by the filtered user. Direct quotes only (does not fire for quotes of quotes). Private event — requires user-context authentication with the `tweet.read` scope. The `payload` is a Post object for the quote; `referenced_tweets` identifies the quoted Post.
```json title="post.quote.create" expandable lines wrap icon="https://mintcdn.com/x-preview-mintlify-58ae8dc1/MHeQz9WFqPMHNFqx/icons/xds/icon-brackets.svg?fit=max&auto=format&n=MHeQz9WFqPMHNFqx&q=85&s=d8bafc321dfd8d57423ff90cf84f7c76" theme={null}
{
"data": {
"event_uuid": "4172938465017283645",
"filter": {
"user_id": "1111111111111111111"
},
"event_type": "post.quote.create",
"tag": "quotes",
"payload": {
"paid_partnership": false,
"created_at": "2026-08-12T18:05:00.000Z",
"edit_history_tweet_ids": [
"2090000000000000002"
],
"conversation_id": "2090000000000000002",
"referenced_tweets": [
{
"type": "quoted",
"id": "2080761390344937796"
}
],
"display_text_range": [
0,
29
],
"text": "Adding some context to this. https://t.co/xxxxxxxx",
"entities": {
"urls": [
{
"start": 29,
"start_str": "29",
"end": 52,
"end_str": "52",
"url": "https://t.co/xxxxxxxx",
"expanded_url": "https://twitter.com/ExampleUser/status/2080761390344937796",
"display_url": "x.com/ExampleUser/st…"
}
]
},
"author_id": "2222222222222222222",
"possibly_sensitive": false,
"public_metrics": {
"retweet_count": 0,
"retweet_count_str": "0",
"reply_count": 0,
"reply_count_str": "0",
"like_count": 0,
"like_count_str": "0",
"quote_count": 0,
"quote_count_str": "0",
"bookmark_count": 0,
"bookmark_count_str": "0",
"impression_count": 0,
"impression_count_str": "0"
},
"reply_settings": "everyone",
"id": "2090000000000000002",
"lang": "en"
},
"includes": {}
}
}
```
### `post.repost.create`
Fired when a user other than the filtered user reposts a Post by the filtered user. Private event — requires user-context authentication with the `tweet.read` scope. The `payload` is a Post object for the repost; `referenced_tweets` with `type: "retweeted"` identifies the original Post.
```json title="post.repost.create" expandable lines wrap icon="https://mintcdn.com/x-preview-mintlify-58ae8dc1/MHeQz9WFqPMHNFqx/icons/xds/icon-brackets.svg?fit=max&auto=format&n=MHeQz9WFqPMHNFqx&q=85&s=d8bafc321dfd8d57423ff90cf84f7c76" theme={null}
{
"data": {
"event_uuid": "5283049576128394756",
"filter": {
"user_id": "1111111111111111111"
},
"event_type": "post.repost.create",
"tag": "reposts",
"payload": {
"paid_partnership": false,
"created_at": "2026-08-12T18:10:00.000Z",
"edit_history_tweet_ids": [
"2090000000000000003"
],
"conversation_id": "2090000000000000003",
"referenced_tweets": [
{
"type": "retweeted",
"id": "2080761390344937796"
}
],
"display_text_range": [
0,
56
],
"text": "RT @ExampleUser: Hello from the Activity API",
"entities": {
"mentions": [
{
"start": 3,
"start_str": "3",
"end": 15,
"end_str": "15",
"username": "ExampleUser",
"id": "1111111111111111111"
}
]
},
"author_id": "2222222222222222222",
"possibly_sensitive": false,
"public_metrics": {
"retweet_count": 0,
"retweet_count_str": "0",
"reply_count": 0,
"reply_count_str": "0",
"like_count": 0,
"like_count_str": "0",
"quote_count": 0,
"quote_count_str": "0",
"bookmark_count": 0,
"bookmark_count_str": "0",
"impression_count": 0,
"impression_count_str": "0"
},
"reply_settings": "everyone",
"id": "2090000000000000003",
"lang": "en"
},
"includes": {}
}
}
```
**Protected accounts:** Posts from protected accounts are not delivered through XAA, even when the subscribing app has user-context authorization for the filtered user.
**Billing:** Each delivered Post event (`post.create`, `post.delete`, `post.mention.create`, `post.reply.create`, `post.quote.create`, `post.repost.create`) is billed as a Post.
***
## Like events
### `like.create`
Fired when the filtered user likes a Post, or when one of their Posts is liked. Private event — requires user-context authentication. Supports an optional `direction` filter (`inbound` or `outbound`).
The `payload` is a like object with the following fields:
| Field | Description |
| ----------------------- | ------------------------------------------------ |
| `id` | Like event ID |
| `liked_tweet_id` | ID of the Post that was liked |
| `liked_tweet_author_id` | Author of the liked Post |
| `created_at` | Creation time of the liked Post (when available) |
| `timestamp_ms` | Event timestamp in milliseconds (when available) |
`includes` may contain the liked Post and related users.
```json title="like.create" expandable lines wrap icon="https://mintcdn.com/x-preview-mintlify-58ae8dc1/MHeQz9WFqPMHNFqx/icons/xds/icon-brackets.svg?fit=max&auto=format&n=MHeQz9WFqPMHNFqx&q=85&s=d8bafc321dfd8d57423ff90cf84f7c76" theme={null}
{
"data": {
"event_uuid": "-3402274206530057851",
"filter": {
"user_id": "1111111111111111111",
"direction": "outbound"
},
"event_type": "like.create",
"tag": "likes",
"payload": {
"id": "87719f50ee17bdfa06a3089098a2b9ed",
"created_at": "2026-07-24T21:12:45.000Z",
"timestamp_ms": "1784927565236",
"liked_tweet_author_id": "3333333333333333333",
"liked_tweet_id": "2079814480427442556"
},
"includes": {
"users": [
{
"description": "𝕏 | @X @AnotherUser @XDevelopers",
"pinned_tweet_id": "2040770361566826685",
"url": "",
"profile_banner_url": "https://pbs.twimg.com/profile_banners/1111111111111111111/1600000000",
"created_at": "2014-05-29T20:24:26.000Z",
"entities": {
"description": {
"mentions": [
{
"start": 4,
"start_str": "4",
"end": 6,
"end_str": "6",
"username": "X"
},
{
"start": 7,
"start_str": "7",
"end": 11,
"end_str": "11",
"username": "AnotherUser"
},
{
"start": 12,
"start_str": "12",
"end": 24,
"end_str": "24",
"username": "XDevelopers"
}
]
}
},
"public_metrics": {
"followers_count": 26972,
"followers_count_str": "26972",
"following_count": 1713,
"following_count_str": "1713",
"tweet_count": 2994,
"tweet_count_str": "2994",
"listed_count": 297,
"listed_count_str": "297",
"like_count": 47468,
"like_count_str": "47468",
"media_count": 265,
"media_count_str": "265"
},
"affiliation": {
"description": "X",
"url": "https://twitter.com/X",
"user_id": [
"783214"
],
"badge_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg"
},
"name": "Public User",
"verified_type": "blue",
"id": "3333333333333333333",
"profile_image_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
"username": "PublicUser",
"protected": false,
"is_identity_verified": false,
"location": "New York, NY",
"verified": true,
"profile_geo_enrichment": {
"potential_locations": [
{
"geo_entity": {
"entity_id": "5391959",
"display_name": "San Francisco, California, United States",
"country_code": "US",
"region": "California",
"sub_region": "San Francisco County",
"locality": "San Francisco",
"population": 873965,
"population_str": "873965",
"geo_point": {
"latitude": 37.77493,
"longitude": -122.41942
}
}
}
]
}
}
],
"tweets": [
{
"possibly_sensitive": false,
"edit_controls": {
"edits_remaining": 5,
"edits_remaining_str": "5",
"is_edit_eligible": true,
"editable_until": "2026-07-22T07:23:07.000Z"
},
"lang": "en",
"text": "Great guide on using the X AnotherUser via our new XMCP and Grok Build to build a structured knowledge system powered by X—unlocking great use cases like agentic research, realtime monitoring the situation, and an audience flywheel to improve as creators on X. https://t.co/5DedenNGo9",
"conversation_id": "2079814480427442556",
"created_at": "2026-07-22T06:23:07.000Z",
"paid_partnership": false,
"author_id": "3333333333333333333",
"entities": {
"urls": [
{
"start": 253,
"start_str": "253",
"end": 276,
"end_str": "276",
"url": "https://t.co/5DedenNGo9",
"expanded_url": "https://twitter.com/xfreeze/status/2079756440722665849",
"display_url": "x.com/xfreeze/status…"
}
]
},
"edit_history_tweet_ids": [
"2079814480427442556"
],
"id": "2079814480427442556",
"public_metrics": {
"retweet_count": 16,
"retweet_count_str": "16",
"reply_count": 8,
"reply_count_str": "8",
"like_count": 131,
"like_count_str": "131",
"quote_count": 2,
"quote_count_str": "2",
"bookmark_count": 90,
"bookmark_count_str": "90",
"impression_count": 21004,
"impression_count_str": "21004"
},
"referenced_tweets": [
{
"type": "quoted",
"id": "2079756440722665849"
}
],
"display_text_range": [
0,
252
],
"reply_settings": "everyone"
}
]
}
}
}
```
***
## Follow events
### `follow.follow`
Fired when the filtered user follows another user, or is followed. The `payload` includes `source` (the follower) and `target` (the user being followed).
```json title="follow.follow" expandable lines wrap icon="https://mintcdn.com/x-preview-mintlify-58ae8dc1/MHeQz9WFqPMHNFqx/icons/xds/icon-brackets.svg?fit=max&auto=format&n=MHeQz9WFqPMHNFqx&q=85&s=d8bafc321dfd8d57423ff90cf84f7c76" theme={null}
{
"data": {
"event_uuid": "-7953119945885597316",
"filter": {
"user_id": "1111111111111111111"
},
"event_type": "follow.follow",
"tag": "follows",
"payload": {
"source": {
"data": {
"affiliation": {
"description": "X",
"badge_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
"url": "https://twitter.com/X"
},
"location": "San Francisco, CA",
"name": "Example User",
"profile_image_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
"created_at": "2023-10-23T13:44:53.000Z",
"protected": false,
"verified": true,
"url": "https://t.co/xxxxxxxx",
"public_metrics": {
"followers_count": 5502,
"followers_count_str": "5502",
"following_count": 652,
"following_count_str": "652",
"tweet_count": 790,
"tweet_count_str": "790",
"listed_count": 47,
"listed_count_str": "47",
"like_count": 8010,
"like_count_str": "8010",
"media_count": 79,
"media_count_str": "79"
},
"is_identity_verified": true,
"description": "Building with the X AnotherUser @XDevelopers",
"verified_type": "blue",
"entities": {
"url": {
"urls": [
{
"start": 0,
"start_str": "0",
"end": 23,
"end_str": "23",
"url": "https://t.co/xxxxxxxx",
"expanded_url": "https://example.com",
"display_url": "https://example.com"
}
]
},
"description": {
"mentions": [
{
"start": 49,
"start_str": "49",
"end": 51,
"end_str": "51",
"username": "X"
},
{
"start": 52,
"start_str": "52",
"end": 64,
"end_str": "64",
"username": "XDevelopers"
}
]
}
},
"profile_banner_url": "https://pbs.twimg.com/profile_banners/1111111111111111111/1600000000",
"username": "ExampleUser",
"id": "1111111111111111111"
}
},
"target": {
"data": {
"affiliation": {
"description": "X",
"badge_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
"url": "https://twitter.com/X"
},
"name": "AnotherUser",
"profile_image_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
"created_at": "2007-05-23T06:01:13.000Z",
"protected": false,
"verified": true,
"url": "https://t.co/YrfsitXdac",
"public_metrics": {
"followers_count": 4934564,
"followers_count_str": "4934564",
"following_count": 12,
"following_count_str": "12",
"tweet_count": 3755,
"tweet_count_str": "3755",
"listed_count": 11603,
"listed_count_str": "11603",
"like_count": 7,
"like_count_str": "7",
"media_count": 9,
"media_count_str": "9"
},
"is_identity_verified": false,
"description": "Updates about X AnotherUser changes and service issues.",
"verified_type": "business",
"entities": {
"url": {
"urls": [
{
"start": 0,
"start_str": "0",
"end": 23,
"end_str": "23",
"url": "https://t.co/YrfsitXdac",
"expanded_url": "https://developer.x.com",
"display_url": "developer.x.com"
}
]
}
},
"profile_banner_url": "https://pbs.twimg.com/profile_banners/1111111111111111111/1600000000",
"username": "AnotherUser",
"id": "4444444444444444444"
}
}
}
}
}
```
### `follow.unfollow`
Fired when the filtered user unfollows another user, or is unfollowed. Same `source` / `target` shape as `follow.follow`.
```json title="follow.unfollow" expandable lines wrap icon="https://mintcdn.com/x-preview-mintlify-58ae8dc1/MHeQz9WFqPMHNFqx/icons/xds/icon-brackets.svg?fit=max&auto=format&n=MHeQz9WFqPMHNFqx&q=85&s=d8bafc321dfd8d57423ff90cf84f7c76" theme={null}
{
"data": {
"event_uuid": "-4233426745281461957",
"filter": {
"user_id": "1111111111111111111"
},
"event_type": "follow.unfollow",
"tag": "unfollows",
"payload": {
"source": {
"data": {
"affiliation": {
"badge_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
"url": "https://twitter.com/X",
"description": "X"
},
"url": "https://t.co/xxxxxxxx",
"description": "Building with the X AnotherUser @XDevelopers",
"verified": true,
"entities": {
"url": {
"urls": [
{
"start": 0,
"start_str": "0",
"end": 23,
"end_str": "23",
"url": "https://t.co/xxxxxxxx",
"expanded_url": "https://example.com",
"display_url": "https://example.com"
}
]
},
"description": {
"mentions": [
{
"start": 49,
"start_str": "49",
"end": 51,
"end_str": "51",
"username": "X"
},
{
"start": 52,
"start_str": "52",
"end": 64,
"end_str": "64",
"username": "XDevelopers"
}
]
}
},
"profile_banner_url": "https://pbs.twimg.com/profile_banners/1111111111111111111/1600000000",
"is_identity_verified": true,
"username": "ExampleUser",
"id": "1111111111111111111",
"name": "Example User",
"profile_image_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
"created_at": "2023-10-23T13:44:53.000Z",
"public_metrics": {
"followers_count": 5502,
"followers_count_str": "5502",
"following_count": 651,
"following_count_str": "651",
"tweet_count": 790,
"tweet_count_str": "790",
"listed_count": 47,
"listed_count_str": "47",
"like_count": 8010,
"like_count_str": "8010",
"media_count": 79,
"media_count_str": "79"
},
"verified_type": "blue",
"location": "San Francisco, CA",
"protected": false
}
},
"target": {
"data": {
"affiliation": {
"badge_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
"url": "https://twitter.com/X",
"description": "X"
},
"url": "https://t.co/YrfsitXdac",
"description": "Updates about X AnotherUser changes and service issues.",
"verified": true,
"entities": {
"url": {
"urls": [
{
"start": 0,
"start_str": "0",
"end": 23,
"end_str": "23",
"url": "https://t.co/YrfsitXdac",
"expanded_url": "https://developer.x.com",
"display_url": "developer.x.com"
}
]
}
},
"profile_banner_url": "https://pbs.twimg.com/profile_banners/1111111111111111111/1600000000",
"is_identity_verified": false,
"username": "AnotherUser",
"id": "4444444444444444444",
"name": "AnotherUser",
"profile_image_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
"created_at": "2007-05-23T06:01:13.000Z",
"public_metrics": {
"followers_count": 4934563,
"followers_count_str": "4934563",
"following_count": 12,
"following_count_str": "12",
"tweet_count": 3755,
"tweet_count_str": "3755",
"listed_count": 11603,
"listed_count_str": "11603",
"like_count": 7,
"like_count_str": "7",
"media_count": 9,
"media_count_str": "9"
},
"verified_type": "business",
"protected": false
}
}
}
}
}
```
***
## Profile events
All `profile.update.*` events share a `before` / `after` payload shape.
Supported types: `profile.update.bio`, `profile.update.profile_picture`, `profile.update.banner_picture`, `profile.update.screenname`, `profile.update.handle`, `profile.update.geo`, `profile.update.url`, `profile.update.verified_badge`, `profile.update.affiliate_badge`.
### `profile.update.bio`
Fired when the filtered user updates their profile bio.
```json title="profile.update.bio" lines wrap icon="https://mintcdn.com/x-preview-mintlify-58ae8dc1/MHeQz9WFqPMHNFqx/icons/xds/icon-brackets.svg?fit=max&auto=format&n=MHeQz9WFqPMHNFqx&q=85&s=d8bafc321dfd8d57423ff90cf84f7c76" theme={null}
{
"data": {
"event_uuid": "-8917909039855612786",
"filter": {
"user_id": "1111111111111111111"
},
"event_type": "profile.update.bio",
"tag": "profile-bio",
"payload": {
"before": "Building with the X API",
"after": "Building with the X API @XDevelopers"
}
}
}
```
### `profile.update.profile_picture`
Fired when the filtered user updates their profile picture.
```json title="profile.update.profile_picture" lines wrap icon="https://mintcdn.com/x-preview-mintlify-58ae8dc1/MHeQz9WFqPMHNFqx/icons/xds/icon-brackets.svg?fit=max&auto=format&n=MHeQz9WFqPMHNFqx&q=85&s=d8bafc321dfd8d57423ff90cf84f7c76" theme={null}
{
"data": {
"event_uuid": "3497989179769309099",
"filter": {
"user_id": "1111111111111111111"
},
"event_type": "profile.update.profile_picture",
"tag": "profile-picture",
"payload": {
"before": "https://pbs.twimg.com/profile_images/0000000000000000001/old_normal.jpg",
"after": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg"
}
}
}
```
### `profile.update.banner_picture`
Fired when the filtered user updates their profile banner.
```json title="profile.update.banner_picture" lines wrap icon="https://mintcdn.com/x-preview-mintlify-58ae8dc1/MHeQz9WFqPMHNFqx/icons/xds/icon-brackets.svg?fit=max&auto=format&n=MHeQz9WFqPMHNFqx&q=85&s=d8bafc321dfd8d57423ff90cf84f7c76" theme={null}
{
"data": {
"event_uuid": "5061407317112342192",
"filter": {
"user_id": "1111111111111111111"
},
"event_type": "profile.update.banner_picture",
"tag": "profile-banner",
"payload": {
"before": "https://pbs.twimg.com/profile_banners/1111111111111111111/1500000000",
"after": "https://pbs.twimg.com/profile_banners/1111111111111111111/1600000000"
}
}
}
```
### `profile.update.screenname`
Fired when the filtered user updates their display name.
```json title="profile.update.screenname" lines wrap icon="https://mintcdn.com/x-preview-mintlify-58ae8dc1/MHeQz9WFqPMHNFqx/icons/xds/icon-brackets.svg?fit=max&auto=format&n=MHeQz9WFqPMHNFqx&q=85&s=d8bafc321dfd8d57423ff90cf84f7c76" theme={null}
{
"data": {
"event_uuid": "4123434298221215973",
"filter": {
"user_id": "1111111111111111111"
},
"event_type": "profile.update.screenname",
"tag": "profile-name",
"payload": {
"before": "Example User",
"after": "Example"
}
}
}
```
### `profile.update.geo`
Fired when the filtered user updates their profile location.
```json title="profile.update.geo" lines wrap icon="https://mintcdn.com/x-preview-mintlify-58ae8dc1/MHeQz9WFqPMHNFqx/icons/xds/icon-brackets.svg?fit=max&auto=format&n=MHeQz9WFqPMHNFqx&q=85&s=d8bafc321dfd8d57423ff90cf84f7c76" theme={null}
{
"data": {
"event_uuid": "8309664692915093892",
"filter": {
"user_id": "1111111111111111111"
},
"event_type": "profile.update.geo",
"tag": "profile-location",
"payload": {
"before": "New York, NY",
"after": "San Francisco, CA"
}
}
}
```
### `profile.update.url`
Fired when the filtered user updates their profile website URL.
```json title="profile.update.url" lines wrap icon="https://mintcdn.com/x-preview-mintlify-58ae8dc1/MHeQz9WFqPMHNFqx/icons/xds/icon-brackets.svg?fit=max&auto=format&n=MHeQz9WFqPMHNFqx&q=85&s=d8bafc321dfd8d57423ff90cf84f7c76" theme={null}
{
"data": {
"event_uuid": "-6055744140117128555",
"filter": {
"user_id": "1111111111111111111"
},
"event_type": "profile.update.url",
"tag": "profile-url",
"payload": {
"before": "https://t.co/oldlinkxx",
"after": "https://t.co/xxxxxxxx"
}
}
}
```
### `profile.update.handle`
Fired when the filtered user updates their @handle. Same `before` / `after` payload shape as other profile events.
### `profile.update.verified_badge`
Fired when the filtered user's verified badge changes. Same `before` / `after` payload shape as other profile events.
### `profile.update.affiliate_badge`
Fired when the filtered user's affiliate badge changes. Same `before` / `after` payload shape as other profile events.
***
## Chat events (XChat)
Encrypted chat payloads include opaque encoded fields used by the XChat client libraries. Private events — require user-context authentication. Encoded crypto fields below are truncated for readability; real deliveries include the full strings.
### `chat.received`
```json title="chat.received" expandable lines wrap icon="https://mintcdn.com/x-preview-mintlify-58ae8dc1/MHeQz9WFqPMHNFqx/icons/xds/icon-brackets.svg?fit=max&auto=format&n=MHeQz9WFqPMHNFqx&q=85&s=d8bafc321dfd8d57423ff90cf84f7c76" theme={null}
{
"data": {
"event_uuid": "8511582263942905822",
"filter": {
"user_id": "1111111111111111111"
},
"event_type": "chat.received",
"tag": "chat-inbound",
"payload": {
"conversation_token": "eyJhbGciOiJIUzI1NiJ9.eyJyZXF1ZXN0aW5nVXN…(truncated)",
"id": "e4f4d3fc-8bbf-4928-92eb-e5058d6bb6f6",
"created_at_msec": "1784841183370",
"sender_id": "2222222222222222222",
"conversation_id": "2222222222222222222:1111111111111111111",
"conversation_key_version": "1768236281331",
"encoded_event": "CwABAAAAEzIwODA0MDA4MjUyMjcxMDAxNjALAAIA…(truncated)",
"conversation_key_change_event": "CwABAAAAEzIwMTA3NTQ4MTkxMTY0NDk5MDULAAIA…(truncated)",
"message_event_signature": {
"public_key_version": "1765382634817",
"signature": "6IK9SZIMXBe5SFcB7vGZJd5A5Eb5MLvnwrhUFfBGv4S5GsSX3WWPGuInXVNfSla36EjXQQ/R/HhsA+2hPAEY7A",
"signature_version": "7",
"signing_public_key": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEJ2c+3BYZs7ZCEY/UPCpmQxJO9v6FJjeusvmSZO/JEay8oF1+oXXlHV55kX4bK6/zFijNKvq1YRb0it0yXqbglA=="
}
}
}
}
```
### `chat.sent`
```json title="chat.sent" expandable lines wrap icon="https://mintcdn.com/x-preview-mintlify-58ae8dc1/MHeQz9WFqPMHNFqx/icons/xds/icon-brackets.svg?fit=max&auto=format&n=MHeQz9WFqPMHNFqx&q=85&s=d8bafc321dfd8d57423ff90cf84f7c76" theme={null}
{
"data": {
"event_uuid": "3723060601307155846",
"filter": {
"user_id": "1111111111111111111"
},
"event_type": "chat.sent",
"tag": "chat-outbound",
"payload": {
"conversation_token": "eyJhbGciOiJIUzI1NiJ9.eyJyZXF1ZXN0aW5nVXN…(truncated)",
"id": "8e75466b-56ec-4e88-bddf-b18f7cc6030e",
"created_at_msec": "1784841233939",
"sender_id": "1111111111111111111",
"conversation_id": "2222222222222222222:1111111111111111111",
"conversation_key_version": "1768236281331",
"encoded_event": "CwABAAAAEzIwODA0MDEwMzczMzMyMzc3NjALAAIA…(truncated)",
"conversation_key_change_event": "CwABAAAAEzIwMTA3NTQ4MTkxMTY0NDk5MDULAAIA…(truncated)",
"message_event_signature": {
"public_key_version": "1736723828667",
"signature": "ManuRvBupip38XzgS733V9xVn/6+4uguMwvMa+YUDQiDIxVhVbaQcN+bKybPRBCj7IPuRi2QQzRvPg7Wq9ZhPw",
"signature_version": "7",
"signing_public_key": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEyxQY+3CI2lwMF5EqRWc6XMRnYmTnaQXhQy1ozchz0IQn7ui5ry1USzScT900WyTPkNmSvG+M8txz+8Y5Wf0gZQ=="
}
}
}
}
```
### `chat.conversation_join`
Fired when a user joins an encrypted chat conversation. The payload shape matches other chat events (conversation identity and encoded crypto material). Private event — requires user-context authentication.
***
## Legacy DM events
Legacy (unencrypted) DM events. Private events — require user-context authentication.
### `dm.sent`
Fired when the filtered user sends an unencrypted DM. The `payload` includes `direct_message_events` and a `users` map.
```json title="dm.sent" expandable lines wrap icon="https://mintcdn.com/x-preview-mintlify-58ae8dc1/MHeQz9WFqPMHNFqx/icons/xds/icon-brackets.svg?fit=max&auto=format&n=MHeQz9WFqPMHNFqx&q=85&s=d8bafc321dfd8d57423ff90cf84f7c76" theme={null}
{
"data": {
"event_uuid": "-3577827201104920132",
"filter": {
"user_id": "1111111111111111111"
},
"event_type": "dm.sent",
"tag": "dm-outbound",
"payload": {
"direct_message_events": [
{
"type": "message_create",
"id": "2080763914820927863",
"created_timestamp": "1784927750704",
"message_create": {
"target": {
"recipient_id": "2244994945"
},
"sender_id": "1111111111111111111",
"message_data": {
"text": "Thanks for the update!",
"entities": {
"hashtags": [],
"symbols": [],
"user_mentions": [],
"urls": []
}
}
}
}
],
"users": {
"1111111111111111111": {
"data": {
"profile_banner_url": "https://pbs.twimg.com/profile_banners/1111111111111111111/1600000000",
"username": "ExampleUser",
"affiliation": {
"description": "X",
"badge_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
"url": "https://twitter.com/X"
},
"name": "Example User",
"verified_type": "blue",
"description": "Building with the X AnotherUser @XDevelopers",
"location": "San Francisco, CA",
"public_metrics": {
"followers_count": 5502,
"followers_count_str": "5502",
"following_count": 651,
"following_count_str": "651",
"tweet_count": 789,
"tweet_count_str": "789",
"listed_count": 47,
"listed_count_str": "47",
"like_count": 8010,
"like_count_str": "8010",
"media_count": 79,
"media_count_str": "79"
},
"id": "1111111111111111111",
"url": "https://t.co/xxxxxxxx",
"protected": false,
"created_at": "2023-10-23T13:44:53.000Z",
"is_identity_verified": true,
"verified": true,
"entities": {
"url": {
"urls": [
{
"start": 0,
"start_str": "0",
"end": 23,
"end_str": "23",
"url": "https://t.co/xxxxxxxx",
"expanded_url": "https://example.com",
"display_url": "https://example.com"
}
]
},
"description": {
"mentions": [
{
"start": 49,
"start_str": "49",
"end": 51,
"end_str": "51",
"username": "X"
},
{
"start": 52,
"start_str": "52",
"end": 64,
"end_str": "64",
"username": "XDevelopers"
}
]
}
},
"profile_image_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg"
}
},
"2244994945": {
"data": {
"profile_banner_url": "https://pbs.twimg.com/profile_banners/2244994945/1690213128",
"username": "XDevelopers",
"affiliation": {
"description": "X",
"badge_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
"url": "https://twitter.com/X"
},
"name": "X Developers",
"verified_type": "business",
"description": "The voice of the X Dev team and your official source for updates, news, and events, related to the X AnotherUser.",
"location": "127.0.0.1",
"public_metrics": {
"followers_count": 694887,
"followers_count_str": "694887",
"following_count": 762,
"following_count_str": "762",
"tweet_count": 4309,
"tweet_count_str": "4309",
"listed_count": 2978,
"listed_count_str": "2978",
"like_count": 2626,
"like_count_str": "2626",
"media_count": 829,
"media_count_str": "829"
},
"id": "2244994945",
"url": "https://t.co/NIwHVIVyrN",
"protected": false,
"created_at": "2013-12-14T04:35:55.000Z",
"is_identity_verified": false,
"verified": true,
"entities": {
"url": {
"urls": [
{
"start": 0,
"start_str": "0",
"end": 23,
"end_str": "23",
"url": "https://t.co/NIwHVIVyrN",
"expanded_url": "https://docs.x.com/",
"display_url": "docs.x.com"
}
]
}
},
"profile_image_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg"
}
}
}
}
}
}
```
### `dm.received`
Fired when the filtered user receives an unencrypted DM. Same payload shape as `dm.sent` (`direct_message_events` plus a `users` map). Private event — requires user-context authentication.
```json title="dm.received" expandable lines wrap icon="https://mintcdn.com/x-preview-mintlify-58ae8dc1/MHeQz9WFqPMHNFqx/icons/xds/icon-brackets.svg?fit=max&auto=format&n=MHeQz9WFqPMHNFqx&q=85&s=d8bafc321dfd8d57423ff90cf84f7c76" theme={null}
{
"data": {
"event_uuid": "-6850472171600526495",
"filter": {
"user_id": "1111111111111111111"
},
"event_type": "dm.received",
"tag": "dm-inbound",
"payload": {
"direct_message_events": [
{
"type": "message_create",
"id": "2080765901528535096",
"created_timestamp": "1784928224372",
"message_create": {
"target": {
"recipient_id": "1111111111111111111"
},
"sender_id": "2222222222222222222",
"message_data": {
"text": "hello!",
"entities": {
"hashtags": [],
"symbols": [],
"user_mentions": [],
"urls": []
}
}
}
}
],
"users": {
"2222222222222222222": {
"data": {
"description": "",
"profile_banner_url": "",
"public_metrics": {
"followers_count": 97,
"followers_count_str": "97",
"following_count": 1,
"following_count_str": "1",
"tweet_count": 50,
"tweet_count_str": "50",
"listed_count": 4,
"listed_count_str": "4",
"like_count": 27,
"like_count_str": "27",
"media_count": 3,
"media_count_str": "3"
},
"protected": false,
"url": "",
"affiliation": {
"description": "Automated",
"badge_url": "https://pbs.twimg.com/semantic_core_img/1428827730364096519/4ZXpTBhS?format=png&name=orig"
},
"is_identity_verified": false,
"id": "2222222222222222222",
"profile_image_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
"verified_type": "none",
"created_at": "2026-04-20T19:55:59.000Z",
"username": "OtherUser",
"verified": false,
"name": "OtherUser"
}
},
"1111111111111111111": {
"data": {
"description": "Building with the X AnotherUser @XDevelopers",
"profile_banner_url": "https://pbs.twimg.com/profile_banners/1111111111111111111/1600000000",
"entities": {
"url": {
"urls": [
{
"start": 0,
"start_str": "0",
"end": 23,
"end_str": "23",
"url": "https://t.co/xxxxxxxx",
"expanded_url": "https://developer.x.com",
"display_url": "developer.x.com"
}
]
},
"description": {
"mentions": [
{
"start": 48,
"start_str": "48",
"end": 50,
"end_str": "50",
"username": "X"
},
{
"start": 51,
"start_str": "51",
"end": 63,
"end_str": "63",
"username": "XDevelopers"
}
]
}
},
"public_metrics": {
"followers_count": 5502,
"followers_count_str": "5502",
"following_count": 651,
"following_count_str": "651",
"tweet_count": 789,
"tweet_count_str": "789",
"listed_count": 46,
"listed_count_str": "46",
"like_count": 8010,
"like_count_str": "8010",
"media_count": 79,
"media_count_str": "79"
},
"location": "San Francisco, CA",
"protected": false,
"url": "https://t.co/xxxxxxxx",
"affiliation": {
"description": "X",
"badge_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
"url": "https://twitter.com/X"
},
"is_identity_verified": true,
"id": "1111111111111111111",
"profile_image_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
"verified_type": "blue",
"created_at": "2023-10-23T13:44:53.000Z",
"username": "ExampleUser",
"verified": true,
"name": "Example User"
}
}
}
}
}
}
```
### `dm.read`
Fired when a participant reads the filtered user's unencrypted DM (read receipt). Private event — requires user-context authentication.
### `dm.indicate_typing`
Fired when a participant is typing a message to the filtered user. Private event — requires user-context authentication.
***
## News events
### `news.new`
Filter by `keyword`. The `payload` includes Grok-curated news fields such as category, name, hook, summary, contexts, and related cluster post results.
| Field | Description |
| ----------------------- | ------------------------------- |
| `id` | News item ID |
| `name` | Headline / topic name |
| `category` | News category |
| `hook` | Short hook / teaser |
| `summary` | Longer summary |
| `contexts` | Related topic / entity contexts |
| `cluster_posts_results` | Related Posts when available |
| `updated_at` | Last update timestamp |
| `disclaimer` | Optional disclaimer text |
```json title="news.new" expandable lines wrap icon="https://mintcdn.com/x-preview-mintlify-58ae8dc1/MHeQz9WFqPMHNFqx/icons/xds/icon-brackets.svg?fit=max&auto=format&n=MHeQz9WFqPMHNFqx&q=85&s=d8bafc321dfd8d57423ff90cf84f7c76" theme={null}
{
"data": {
"event_uuid": "2080756868147019827",
"filter": {
"keyword": "OpenAI"
},
"event_type": "news.new",
"tag": "news-keyword",
"payload": {
"summary": "OpenAI rolled out a new feature in ChatGPT's web version that lets users create virtual pets by describing them, generating fun companions like a fluffy gray cat or a seal in a yellow bow tie. Creators can copy a shareable link from…",
"contexts": {
"entities": {
"events": [],
"organizations": [
"OpenAI"
],
"people": [],
"places": [],
"products": []
},
"topics": [
"Technology"
],
"finance": {
"tickers": []
},
"sports": {
"teams": []
}
},
"id": "2080756868147019827",
"updated_at": "2026-07-24T20:53:37.000Z",
"hook": "Imagine designing a green dinosaur with a bow tie, then sharing it with friends to adopt as their own ChatGPT companion.",
"category": "News",
"disclaimer": "This story is a summary of posts on X and may evolve over time. Grok can make mistakes, verify its outputs.",
"cluster_posts_results": [
{
"post_id": "2080756403493560652"
},
{
"post_id": "2080747505474736162"
},
{
"post_id": "2080750142437880021"
}
],
"name": "ChatGPT Adds Custom Virtual Pets for Sharing"
}
}
}
```
***
## Spaces events
### `spaces.start`
Fired when the filtered user starts a Space. The `payload` includes the host `user`, `broadcast_id`, and an inner `event_type` of `start`.
```json title="spaces.start" expandable lines wrap icon="https://mintcdn.com/x-preview-mintlify-58ae8dc1/MHeQz9WFqPMHNFqx/icons/xds/icon-brackets.svg?fit=max&auto=format&n=MHeQz9WFqPMHNFqx&q=85&s=d8bafc321dfd8d57423ff90cf84f7c76" theme={null}
{
"data": {
"event_uuid": "4093201169289922041",
"filter": {
"user_id": "1111111111111111111"
},
"event_type": "spaces.start",
"tag": "spaces-start",
"payload": {
"user": {
"data": {
"affiliation": {
"description": "X",
"badge_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
"url": "https://twitter.com/X"
},
"location": "San Francisco, CA",
"name": "Example User",
"profile_image_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
"created_at": "2023-10-23T13:44:53.000Z",
"protected": false,
"verified": true,
"url": "https://t.co/xxxxxxxx",
"public_metrics": {
"followers_count": 5502,
"followers_count_str": "5502",
"following_count": 651,
"following_count_str": "651",
"tweet_count": 789,
"tweet_count_str": "789",
"listed_count": 46,
"listed_count_str": "46",
"like_count": 8010,
"like_count_str": "8010",
"media_count": 79,
"media_count_str": "79"
},
"is_identity_verified": true,
"description": "Building with the X AnotherUser @XDevelopers",
"verified_type": "blue",
"entities": {
"url": {
"urls": [
{
"start": 0,
"start_str": "0",
"end": 23,
"end_str": "23",
"url": "https://t.co/xxxxxxxx",
"expanded_url": "https://developer.x.com",
"display_url": "developer.x.com"
}
]
},
"description": {
"mentions": [
{
"start": 48,
"start_str": "48",
"end": 50,
"end_str": "50",
"username": "X"
},
{
"start": 51,
"start_str": "51",
"end": 63,
"end_str": "63",
"username": "XDevelopers"
}
]
}
},
"profile_banner_url": "https://pbs.twimg.com/profile_banners/1111111111111111111/1600000000",
"username": "ExampleUser",
"id": "1111111111111111111"
}
},
"broadcast_id": "1qxvvvyLLdnxB",
"event_type": "spaces_start"
}
}
}
```
### `spaces.end`
Fired when the filtered user ends a Space. Same shape as `spaces.start` with an inner `event_type` of `end`.
```json title="spaces.end" expandable lines wrap icon="https://mintcdn.com/x-preview-mintlify-58ae8dc1/MHeQz9WFqPMHNFqx/icons/xds/icon-brackets.svg?fit=max&auto=format&n=MHeQz9WFqPMHNFqx&q=85&s=d8bafc321dfd8d57423ff90cf84f7c76" theme={null}
{
"data": {
"event_uuid": "-498317022904955631",
"filter": {
"user_id": "1111111111111111111"
},
"event_type": "spaces.end",
"tag": "spaces-end",
"payload": {
"user": {
"data": {
"description": "Building with the X AnotherUser @XDevelopers",
"protected": false,
"is_identity_verified": true,
"affiliation": {
"url": "https://twitter.com/X",
"badge_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
"description": "X"
},
"entities": {
"url": {
"urls": [
{
"start": 0,
"start_str": "0",
"end": 23,
"end_str": "23",
"url": "https://t.co/xxxxxxxx",
"expanded_url": "https://developer.x.com",
"display_url": "developer.x.com"
}
]
},
"description": {
"mentions": [
{
"start": 48,
"start_str": "48",
"end": 50,
"end_str": "50",
"username": "X"
},
{
"start": 51,
"start_str": "51",
"end": 63,
"end_str": "63",
"username": "XDevelopers"
}
]
}
},
"profile_banner_url": "https://pbs.twimg.com/profile_banners/1111111111111111111/1600000000",
"public_metrics": {
"followers_count": 5502,
"followers_count_str": "5502",
"following_count": 651,
"following_count_str": "651",
"tweet_count": 789,
"tweet_count_str": "789",
"listed_count": 46,
"listed_count_str": "46",
"like_count": 8010,
"like_count_str": "8010",
"media_count": 79,
"media_count_str": "79"
},
"id": "1111111111111111111",
"verified_type": "blue",
"profile_image_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
"name": "Example User",
"url": "https://t.co/xxxxxxxx",
"username": "ExampleUser",
"location": "San Francisco, CA",
"verified": true,
"created_at": "2023-10-23T13:44:53.000Z"
}
},
"broadcast_id": "1qxvvvyLLdnxB",
"event_type": "spaces_end"
}
}
}
```
***
## Mute events
Mute events use a `source` / `target` user pair similar to follow events. Private events — require user-context authentication with the `mute.read` scope. The `user_id` filter matches the user **performing** the mute or unmute (not the account being muted).
### `mute.mute`
Fired when the filtered user mutes another user.
### `mute.unmute`
Fired when the filtered user unmutes another user.
***
## Block events
Block events use a `source` / `target` user pair similar to follow events. Private events — require user-context authentication with the `block.read` scope. The `user_id` filter matches the user **performing** the block or unblock (not the account being blocked).
### `block.block`
Fired when the filtered user blocks another user.
### `block.unblock`
Fired when the filtered user unblocks another user.
***
## Broadcast events
### `broadcast.chat`
Fired when the filtered user receives a chat message in a broadcast that they own. Private event — requires user-context authentication with the `broadcast.read` scope. The `payload` includes the `broadcast_id`, the chat `message_id` and `message` text, and an `author` block with the sending user's profile.
```json title="broadcast.chat" expandable lines wrap icon="https://mintcdn.com/x-preview-mintlify-58ae8dc1/MHeQz9WFqPMHNFqx/icons/xds/icon-brackets.svg?fit=max&auto=format&n=MHeQz9WFqPMHNFqx&q=85&s=d8bafc321dfd8d57423ff90cf84f7c76" theme={null}
{
"data": {
"event_uuid": "7365873565827875221",
"filter": {
"user_id": "1111111111111111111"
},
"event_type": "broadcast.chat",
"tag": "my stream chats",
"payload": {
"broadcast_id": "1mGPaZaAdNqJN",
"message_id": "2090000000000000004",
"message": "test",
"author": {
"data": {
"affiliation": {
"url": "https://twitter.com/X",
"badge_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
"description": "X"
},
"created_at": "2024-08-31T23:23:51.000Z",
"is_identity_verified": false,
"id": "1111111111111111111",
"username": "ExampleUser",
"profile_image_url": "https://pbs.twimg.com/profile_images/0000000000000000001/example_normal.jpg",
"verified_type": "blue",
"public_metrics": {
"followers_count": 2774,
"followers_count_str": "2774",
"following_count": 268,
"following_count_str": "268",
"tweet_count": 705,
"tweet_count_str": "705",
"listed_count": 42,
"listed_count_str": "42",
"like_count": 983,
"like_count_str": "983",
"media_count": 93,
"media_count_str": "93"
},
"profile_banner_url": "https://pbs.twimg.com/profile_banners/1111111111111111111/1600000000",
"name": "Example User",
"entities": {
"url": {
"urls": [
{
"start": 0,
"start_str": "0",
"end": 23,
"end_str": "23",
"url": "https://t.co/xxxxxxxx",
"expanded_url": "https://example.com",
"display_url": "example.com"
}
]
},
"description": {
"mentions": [
{
"start": 19,
"start_str": "19",
"end": 21,
"end_str": "21",
"username": "X"
}
]
}
},
"protected": false,
"url": "https://t.co/xxxxxxxx",
"description": "Developer Platform @X",
"verified": true
}
}
}
}
}
```
***
## OAuth events
### `oauth.revoke`
Fired when a user revokes your application's access. The `filter` may be empty. Use this to clean up local state for the revoked user.
```json title="oauth.revoke" lines wrap icon="https://mintcdn.com/x-preview-mintlify-58ae8dc1/MHeQz9WFqPMHNFqx/icons/xds/icon-brackets.svg?fit=max&auto=format&n=MHeQz9WFqPMHNFqx&q=85&s=d8bafc321dfd8d57423ff90cf84f7c76" theme={null}
{
"data": {
"event_uuid": "5934540941047412905",
"filter": {},
"event_type": "oauth.revoke",
"payload": {
"date_time": "2026-07-23T21:44:05+00:00",
"user_id": "1111111111111111111",
"app_id": "29820954"
}
}
}
```
***
## Next steps
Supported event types, privacy, and authentication
Create a subscription and receive events
Connect to the persistent HTTP stream
Deliver activity events to your webhook URL