Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.x.com/llms.txt

Use this file to discover all available pages before exploring further.

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:
TypeExamples
PersonBarack Obama, Elon Musk
PlaceSan Francisco, Japan
ProductiPhone, ChatGPT
OrganizationNASA, Google
OtherSuper 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

FieldDescription
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:
IDDomain
3TV Shows
4TV Episodes
54Musician
56Actor
86Movie
91Podcast
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:
LanguageCoverage
EnglishHighest
JapaneseHigh
SpanishHigh
PortugueseMedium
FrenchMedium
HindiMedium
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.