Annotations provide semantic metadata about post content. X analyzes posts to identify entities (people, places, products) and context (topics, domains) to help you understand and filter content.
Annotation types Entity annotations Named-entity recognition (NER) identifies specific mentions in post text:
Type Examples Person Barack Obama, Elon Musk Place San Francisco, Japan Product iPhone, ChatGPT Organization NASA, Google Other Super Bowl, Diabetes
Entity annotations include a confidence score and position in the text.
Context annotations Semantic analysis that classifies posts by topic and domain:
Domain : Broad category (Sports, Entertainment, Technology)Entity : Specific topic within the domain (NBA, Marvel Movies, AI)
Context annotations help filter and categorize posts without relying on keywords.
Requesting annotations Add context_annotations and entities to your tweet.fields:
curl "https://api.x.com/2/tweets/1234567890?tweet.fields=context_annotations,entities" \ -H "Authorization: Bearer $TOKEN "
Response structure { "data" : { "id" : "1234567890" , "text" : "Just saw the new Marvel movie - it was amazing!" , "entities" : { "annotations" : [ { "start" : 17 , "end" : 22 , "probability" : 0.9234 , "type" : "Organization" , "normalized_text" : "Marvel" } ] }, "context_annotations" : [ { "domain" : { "id" : "86" , "name" : "Movie" , "description" : "A film" }, "entity" : { "id" : "1234567890" , "name" : "Marvel Cinematic Universe" } }, { "domain" : { "id" : "65" , "name" : "Interests and Hobbies Vertical" }, "entity" : { "id" : "781974596752842752" , "name" : "Entertainment" } } ] } }
Entity annotation fields Field Description startStart position in text endEnd position in text probabilityConfidence score (0-1) typeEntity type (Person, Place, etc.) normalized_textStandardized entity name
Context domains X uses 80+ domains to categorize posts. Common domains include:
Entertainment
Sports
Business & Tech
Other
ID Domain 3 TV Shows 4 TV Episodes 54 Musician 56 Actor 86 Movie 91 Podcast
ID Domain 6 Sports Events 11 Sport 12 Sports Team 26 Sports League 60 Athlete 93 Coach
ID Domain 45 Brand Vertical 46 Brand Category 47 Brand 48 Product 165 Technology 166 Stocks
ID Domain 10 Person 13 Place 29 Events 35 Politicians 119 Holiday 131 Unified Twitter Taxonomy
Domain 131 (Unified Twitter Taxonomy) powers X’s Topics feature visible to users on the platform.
Using annotations in filters Search and filtered stream Filter posts by context annotation entity ID:
# Posts about a specific entity context:86.1234567890 # Posts in a specific domain context:86.*
Practical examples # Posts about the NBA query = context:26.852137520 # Posts about Apple products query = context:47.10026792024 # Posts about movies query = context:86.*
Language support Annotations are available for multiple languages:
Language Coverage English Highest Japanese High Spanish High Portuguese Medium French Medium Hindi Medium
Coverage varies by domain and market.
Important notes Not all posts are annotated. Annotation coverage depends on:
Language support
Topic coverage in X’s taxonomy
Semantic richness of the post text
Annotations are not retroactive—only applied when entities are tracked
The same entity can appear in multiple domains (e.g., a celebrity is both Person and Actor)
Entity IDs are stable across domains
Resources
Entity Explorer Interactive tool to discover annotations.
Context Entity List CSV of available context annotation entities.
