Post Annotations

Annotations provide semantic metadata about post content. X analyzes posts to identify entities (people, places, products) and context (topics, domains) to.

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
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

ID	Domain
3	TV Shows
4	TV Episodes
54	Musician
56	Actor
86	Movie
91	Podcast

Sports

ID	Domain
6	Sports Events
11	Sport
12	Sports Team
26	Sports League
60	Athlete
93	Coach

Business & Tech

ID	Domain
45	Brand Vertical
46	Brand Category
47	Brand
48	Product
165	Technology
166	Stocks

Other

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

Context Entity List

CSV of available context annotation entities.