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 |
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 |
|---|
start | Start position in text |
end | End position in text |
probability | Confidence score (0-1) |
type | Entity type (Person, Place, etc.) |
normalized_text | Standardized 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 |
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
