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

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