> ## Documentation Index
> Fetch the complete documentation index at: https://x-preview-mintlify-508d47e7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Post Annotations

> Use X API v2 entity and context annotations to identify people, places, products, organizations, and topic domains semantically inside Post text.

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

```bash theme={null}
curl "https://api.x.com/2/tweets/1234567890?tweet.fields=context_annotations,entities" \
  -H "Authorization: Bearer $TOKEN"
```

***

## Response structure

```json title="Example response" expandable lines wrap icon="https://mintcdn.com/x-preview-mintlify-508d47e7/K_EDPi0sX8nSJWO1/icons/xds/icon-brackets.svg?fit=max&auto=format&n=K_EDPi0sX8nSJWO1&q=85&s=fbbeace0b61ab86c0a4f8da0e43ebe06" theme={null}
{
  "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:

<Tabs>
  <Tab title="Entertainment">
    | ID | Domain |
    | :- | :- |
    | 3 | TV Shows |
    | 4 | TV Episodes |
    | 54 | Musician |
    | 56 | Actor |
    | 86 | Movie |
    | 91 | Podcast |
  </Tab>

  <Tab title="Sports">
    | ID | Domain |
    | :- | :- |
    | 6 | Sports Events |
    | 11 | Sport |
    | 12 | Sports Team |
    | 26 | Sports League |
    | 60 | Athlete |
    | 93 | Coach |
  </Tab>

  <Tab title="Business & Tech">
    | ID | Domain |
    | :- | :- |
    | 45 | Brand Vertical |
    | 46 | Brand Category |
    | 47 | Brand |
    | 48 | Product |
    | 165 | Technology |
    | 166 | Stocks |
  </Tab>

  <Tab title="Other">
    | ID | Domain |
    | :- | :- |
    | 10 | Person |
    | 13 | Place |
    | 29 | Events |
    | 35 | Politicians |
    | 119 | Holiday |
    | 131 | Unified Twitter Taxonomy |
  </Tab>
</Tabs>

<Note>
  Domain 131 (Unified Twitter Taxonomy) powers X's Topics feature visible to users on the platform.
</Note>

***

## Using annotations in filters

### Search and filtered stream

Filter posts by context annotation entity ID:

```bash theme={null}
# Posts about a specific entity
context:86.1234567890

# Posts in a specific domain
context:86.*
```

### Practical examples

```bash theme={null}
# 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

<Warning>
  **Not all posts are annotated.** Annotation coverage depends on:

  * Language support
  * Topic coverage in X's taxonomy
  * Semantic richness of the post text
</Warning>

* 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

<CardGroup cols={2}>
  <Card title="Context Entity List" icon="github" href="https://github.com/xdevplatform/twitter-context-annotations">
    CSV of available context annotation entities.
  </Card>
</CardGroup>