| 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 |
Event envelope
{
"data": {
"event_uuid": "2080761390344937796",
"filter": {
"user_id": "1111111111111111111"
},
"event_type": "post.create",
"tag": "posts",
"payload": {},
"includes": {}
}
}
Post events
post.create
Fired when the filtered user creates a Post. The payload is a Post object; includes may contain related users and tweets.
post.create
{
"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.
post.delete
{
"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 someone @mentions the filtered user in a Post. Private event — requires user-context authentication.
post.mention.create
{
"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"
}
]
}
}
}
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.
like.create
{
"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).
follow.follow
{
"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.
follow.unfollow
{
"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
Allprofile.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.
profile.update.bio
{
"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.
profile.update.profile_picture
{
"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.
profile.update.banner_picture
{
"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.
profile.update.screenname
{
"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.
profile.update.geo
{
"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.
profile.update.url
{
"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
chat.received
{
"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
chat.sent
{
"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.
dm.sent
{
"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.
dm.received
{
"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 |
news.new
{
"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.
spaces.start
{
"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.
spaces.end
{
"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 asource / 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 asource / 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.
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.
oauth.revoke
{
"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
Introduction
Supported event types, privacy, and authentication
Quickstart
Create a subscription and receive events
Activity stream
Connect to the persistent HTTP stream
Webhooks
Deliver activity events to your webhook URL