Events

Attachments

Shapes for media, articles, polls, and cashtags carried by post events. Reference these from any event with `media`, `article`, `poll`, or `symbols`.

Events that carry post content (post, reply, quote, repost, and deleted) include four shared shapes for attachments. This page documents each one.

MediaRef

Used in media, replyToMedia, quotedMedia.

Field	Type	Notes
`type`	`"photo" \| "video" \| "gif"`	Media kind
`url`	string	For photos, the image URL. For video and gif, the underlying media URL
`posterUrl`	string \| undefined	Only present for `video` and `gif`. The preview frame the X player uses

Examples

Photo:

{ "type": "photo", "url": "https://pbs.twimg.com/media/HJ_GWp2WEAAHkE2.jpg" }

Video:

{
  "type": "video",
  "url": "https://video.twimg.com/ext_tw_video/.../vid/1280x720/clip.mp4",
  "posterUrl": "https://pbs.twimg.com/ext_tw_video_thumb/.../poster.jpg"
}

GIF:

{
  "type": "gif",
  "url": "https://video.twimg.com/tweet_video/.../animation.mp4",
  "posterUrl": "https://pbs.twimg.com/tweet_video_thumb/.../thumb.jpg"
}

ArticleRef

Used in article, replyToArticle, quotedArticle. Present when the post links to an article card; null otherwise.

Field	Type	Notes
`title`	string	Article title
`previewText`	string	Preview text. Pre-truncated by X to roughly 200 characters; can end mid-sentence
`coverImageUrl`	string \| null	Cover image when the article has one

Example

{
  "title": "Falcon 9's 500th launch",
  "previewText": "SpaceX's Falcon 9 lifted off from Cape Canaveral for the 500th time, deploying...",
  "coverImageUrl": "https://pbs.twimg.com/article-cover/.../cover.jpg"
}

PollRef and PollChoice

Used in poll, replyToPoll, quotedPoll. Present when the post is a poll; null otherwise.

PollRef:

Field	Type	Notes
`choices`	`PollChoice[]`	Poll options in the order shown on X
`endsAtMs`	number	When the poll closes
`final`	boolean	`true` after the poll has closed and final counts are visible
`durationMinutes`	number	The total poll duration. Useful for “24-hour poll” badges

PollChoice:

Field	Type	Notes
`label`	string	Option text
`count`	number	Vote count. Always `0` while the poll is open; the real value appears only after `final` flips to `true`

Example

{
  "choices": [
    { "label": "Falcon", "count": 12340 },
    { "label": "Starship", "count": 89712 }
  ],
  "endsAtMs": 1780100000000,
  "final": true,
  "durationMinutes": 1440
}

While final is false, hide vote counts and percentages from your UI; the values are all 0 by design and showing them would mislead users.

SymbolRef

Used in symbols, replyToSymbols, quotedSymbols. Each entry represents one cashtag the author selected from X’s cashtag picker. Cashtags typed inline (like $btc in plain text) do not produce entries.

Field	Type	Notes
`ticker`	string	Display ticker, like `"SOL"` or `"BTC"`
`name`	string	Display name, like `"Solana"` or `"Bitcoin"`
`restId`	string	X’s opaque asset identifier

Example

[
  { "ticker": "SOL", "name": "Solana", "restId": "solana:So11111111111111111111111111111111111111112" }
]

Treat restId as an opaque key. You can use it to look up live price or chart data from external sources.