Events

Every notification uses the same envelope. Over the WebSocket it arrives inside an op: 0 message as d. A custom webhook receives the same object as the POST body

{
  "op": 0,
  "d": {
    "event_id": "a1b2c3d4",
    "event": "twitter.post.new",
    "task_info": { "id": 1042, "group": "markets", "handle": "elonmusk", "profile_info": {} },
    "data": {}
  }
}

Envelope

string

Stable for a given post, so you can use it to drop duplicates. Not sent on keyword events

string

The event type. See Event types

object

The task that produced the event

Show properties

integer

Task ID. Present when the task has one

string

Task group. Present when the task has one

string

Monitored handle. Account tasks only

object

Profile of the monitored account. Account tasks only

string

Monitored query. Keyword tasks only

object

The event payload. Its shape depends on event. Absent on twitter.task.update

string

Only on twitter.task.update. One of profile_private, profile_suspended, profile_available_back

Event types

`event`	Sent when	`data`
`twitter.post.new`, `truth_social.post.new`	The account posts, reposts, quotes, or replies	Post
`twitter.post.micro`	A post is detected, before the full `twitter.post.new`	Partial post
`twitter.post.subscription`	The account publishes a subscriber-only post	Post
`twitter.post.private`	A protected account posts	`{ "statuses_count": 1200 }`
`twitter.post.deleted`	The account deletes a post	Post
`twitter.post.ocr`, `truth_social.post.ocr`	Text has been read from a posted image	OCR result
`twitter.post.translate`, `truth_social.post.translate`	A post translation is ready	Translation
`twitter.following.new`	The account follows someone	Profile of the followed account
`twitter.following.removed`	The account unfollows someone	Profile of the unfollowed account
`twitter.profile.update`	The account changes its profile	Changed fields
`twitter.task.update`	The account goes private, is suspended, or comes back	None, see `status`
`twitter_keyword.post.new`	A post matches a Twitter Global query	Keyword post

Account events

New posts

Sent for every post type enabled on the task. Check data.type to tell posts, reposts, quotes, and replies apart

{
  "event_id": "a1b2c3d4",
  "event": "twitter.post.new",
  "task_info": { "id": 1042, "group": "markets", "handle": "elonmusk", "profile_info": {} },
  "data": {
    "id": "123",
    "created_at": 1730000000000,
    "type": "quote",
    "text": "Interesting",
    "media": [],
    "mentions": [],
    "tags": [],
    "author": { "id": "44196397", "handle": "elonmusk", "name": "Elon Musk" },
    "quoted": {
      "id": "122",
      "created_at": 1729990000000,
      "type": "post",
      "text": "Original post",
      "media": [{ "type": "photo", "url": "https://pbs.twimg.com/..." }],
      "mentions": [],
      "tags": [],
      "author": { "id": "12", "handle": "jack", "name": "jack" }
    }
  }
}

twitter.post.micro is a Pro feature and is only sent while micro events are enabled. It carries a partial post so you can react faster, followed by the complete twitter.post.new for the same post

Subscriber and protected posts

twitter.post.subscription carries a full post with type set to subscription twitter.post.private is sent when a protected account posts. The content is not visible, so data only holds the account’s new post count:

{
  "event_id": "a1b2c3d4",
  "event": "twitter.post.private",
  "task_info": { "id": 1042, "handle": "someprivateuser", "profile_info": {} },
  "data": { "statuses_count": 1200 }
}

Deleted posts

twitter.post.deleted carries the deleted post as it was last seen

OCR

Sent when text has been read from an image in a post. Requires the ocr option on the task

{
  "event_id": "a1b2c3d4",
  "event": "twitter.post.ocr",
  "task_info": { "id": 1042, "handle": "elonmusk", "profile_info": {} },
  "data": {
    "text": "read from the image",
    "image_url": "https://pbs.twimg.com/...",
    "post_id": "123"
  }
}

Match post_id against the id of an earlier post event to link the result to its post.

Translation

Sent when a post translation is ready. text has one entry for the post and one for each nested post (quoted, reposted, or replied) that was translated

{
  "event_id": "a1b2c3d4",
  "event": "twitter.post.translate",
  "task_info": { "id": 1042, "handle": "elonmusk", "profile_info": {} },
  "data": {
    "post_id": "123",
    "text": [{ "original": "Bonjour", "translatedText": "Hello" }]
  }
}

Following and unfollowing

twitter.following.new and twitter.following.removed carry the profile of the account that was followed or unfollowed. The task’s following filters apply before the event is sent

{
  "event_id": "a1b2c3d4",
  "event": "twitter.following.new",
  "task_info": { "id": 1042, "handle": "elonmusk", "profile_info": {} },
  "data": {
    "id": "12",
    "created_at": 1142974214000,
    "handle": "jack",
    "name": "jack",
    "avatar": "https://pbs.twimg.com/...",
    "description": "",
    "stats": { "followers": 6000000, "following": 4000, "posts": 30000, "media": 2000, "likes": 35000 }
  }
}

Profile updates

Only the fields that changed are present in data. Each one holds the previous and new value

{
  "event_id": "a1b2c3d4",
  "event": "twitter.profile.update",
  "task_info": { "id": 1042, "handle": "elonmusk", "profile_info": {} },
  "data": {
    "description": { "prev": "old bio", "updated": "new bio" },
    "verification": { "prev": "", "updated": "Business" }
  }
}

object

One key per changed field: handle, name, avatar, banner, location, description, website, pinned_post, verification

Show properties

string

Value before the change.

string

Value after the change.

object

Only on pinned_post. The new pinned post

Fields turned off in the task’s profile update options are never reported

Task status

Sent when the monitored account becomes unavailable or available again. There is no data. Read status instead

{
  "event_id": "a1b2c3d4",
  "event": "twitter.task.update",
  "task_info": { "id": 1042, "handle": "elonmusk", "profile_info": {} },
  "status": "profile_suspended"
}

`status`	Meaning
`profile_private`	The account became protected
`profile_suspended`	The account was suspended
`profile_available_back`	The account is public again

Keyword posts

Twitter Global tasks send twitter_keyword.post.new. These events have no event_id, and task_info has keyword instead of handle and profile_info. The post has no type or mentions, and author is a lighter profile

{
  "event": "twitter_keyword.post.new",
  "task_info": { "id": 1045, "group": "markets", "keyword": "(bitcoin OR ethereum) NOT (giveaway)" },
  "data": {
    "id": "123",
    "created_at": 1730000000000,
    "text": "text",
    "media": [],
    "tags": ["bitcoin"],
    "author": {
      "id": "12",
      "created_at": 1200000000000,
      "handle": "jack",
      "name": "jack",
      "avatar": "https://pbs.twimg.com/...",
      "verification": { "is_verified": true, "type": "Business" },
      "affiliation": { "label": "Square", "badge": "https://...", "type": "BusinessLabel" }
    }
  }
}

verification.type is Business or Government when present. affiliation is only present when the account has one

Objects

Post

string

Post ID

integer

Post time in milliseconds

string

post, repost, quote, reply, or subscription

string

Post text

object[]

Photos and videos in the post

Show properties

string

photo or video

string

URL of the photo or video

string

Videos only. URL of the first frame

integer

Videos only. Length in milliseconds

string

Truth Social photos only. Full-size image

object[]

Accounts mentioned in the post

Show properties

string

Account ID of the mentioned profile

string

Username of the mentioned profile, without the @

string

Display name of the mentioned profile

string[]

Hashtags without the #

object

Profile of the author

object

Quotes only. The quoted post, with the same shape

object

Reposts only. The original post, with the same shape

object

Replies only. The post being replied to, with the same shape

Profile

{
  "id": "44196397",
  "created_at": 1243979740000,
  "handle": "elonmusk",
  "name": "Elon Musk",
  "avatar": "https://pbs.twimg.com/...",
  "banner": "https://pbs.twimg.com/...",
  "description": "",
  "location": "",
  "website": "",
  "verification": { "is_verified": true, "type": "Business" },
  "affiliation": { "label": "Tesla", "badge": "https://...", "type": "BusinessLabel" },
  "stats": { "followers": 1, "following": 1, "posts": 1, "media": 1, "likes": 1 }
}

string

Account ID. Unlike handle, it never changes

integer

Account creation time in milliseconds

string

Username without the @

string

Display name

string

Profile picture URL. Truth Social can also include avatar_original

string

Banner URL

string

Bio

string

Location set on the profile

string

Website set on the profile

object

Verification badge

Show properties

boolean

Whether the profile has a verified badge

string

Badge type, such as Business or Government. Can be omitted

object

Affiliate label shown next to the name

Show properties

string

Name of the affiliated organization

string

URL of the badge image

string

Label type, such as BusinessLabel

object

Profile counters

Show properties

integer

Number of followers

integer

Number of accounts the profile follows

integer

Number of posts

integer

Number of posts with media

integer

Number of posts the profile has liked

verification, affiliation, and individual stats are omitted when Twitter does not return them

Getting started

Monitor

Pro

Legal

Envelope

Event types

Account events

New posts

Subscriber and protected posts

Deleted posts

OCR

Translation

Following and unfollowing

Profile updates

Task status

Keyword posts

Objects

Post

Profile

​Envelope

​Event types

​Account events

​New posts

​Subscriber and protected posts

​Deleted posts

​OCR

​Translation

​Following and unfollowing

​Profile updates

​Task status

​Keyword posts

​Objects

​Post

​Profile

Envelope

Event types

Account events

New posts

Subscriber and protected posts

Deleted posts

OCR

Translation

Following and unfollowing

Profile updates

Task status

Keyword posts

Objects

Post

Profile