> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trynia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# X (Twitter) Integration

> Index posts from X/Twitter accounts and search them with AI through Nia.

The X (Twitter) integration lets you index posts from any public X/Twitter account and make them searchable through Nia's unified search. Pull in tweets, filter by replies and retweets, and query the content alongside all your other indexed sources.

<Info>
  This integration uses the X API v2. You need a valid bearer token from the [X Developer Portal](https://developer.x.com/) to get started.
</Info>

***

## Prerequisites

Before setting up the X integration, you need:

1. **A Nia API key** -- Get one at [app.trynia.ai](https://app.trynia.ai)
2. **An X API bearer token** -- Create a project and app in the [X Developer Portal](https://developer.x.com/) to obtain a bearer token with read access

<Warning>
  Your X API bearer token grants read access to public tweets. Store it securely in an environment variable or secret manager. Nia encrypts tokens at rest.
</Warning>

***

## Getting Started

<Steps>
  <Step title="Get Your X API Bearer Token">
    Sign up at the [X Developer Portal](https://developer.x.com/), create a project and app, and copy the bearer token from the "Keys and Tokens" section.
  </Step>

  <Step title="Create an Installation">
    Register the X account you want to index by providing the username and your bearer token via the Nia API.
  </Step>

  <Step title="Configure Options">
    Choose how many posts to fetch and whether to include replies and retweets.
  </Step>

  <Step title="Trigger Indexing">
    Start the indexing job. Nia fetches posts from the account, chunks and embeds them, and stores everything in the vector index.
  </Step>

  <Step title="Search">
    Query indexed posts through the unified search endpoint, alongside repositories, docs, Slack, and other sources.
  </Step>
</Steps>

***

## Creating an Installation

Register an X account for indexing:

```bash theme={null}
curl -X POST https://apigcp.trynia.ai/v2/x/installations \
  -H "Authorization: Bearer $NIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "elaborateai",
    "bearer_token": "AAAAAAAAAAAAAAAAAAA...",
    "display_name": "Elaborate AI Posts",
    "max_results": 200,
    "include_replies": false,
    "include_retweets": false
  }'
```

```json theme={null}
{
  "id": "x-inst-7a3b9c01-...",
  "username": "elaborateai",
  "display_name": "Elaborate AI Posts",
  "max_results": 200,
  "include_replies": false,
  "include_retweets": false,
  "status": "created",
  "created_at": "2026-03-29T10:00:00Z"
}
```

### Request Parameters

| Parameter          | Type    | Required | Description                                                     |
| ------------------ | ------- | -------- | --------------------------------------------------------------- |
| `username`         | string  | Yes      | The X/Twitter username (without the `@`)                        |
| `bearer_token`     | string  | Yes      | X API v2 bearer token                                           |
| `display_name`     | string  | No       | A friendly label for this installation                          |
| `max_results`      | integer | No       | Number of posts to fetch per indexing run (1--500, default 100) |
| `include_replies`  | boolean | No       | Include reply tweets (default `false`)                          |
| `include_retweets` | boolean | No       | Include retweets (default `false`)                              |

<Info>
  The `max_results` parameter controls how many of the most recent posts are fetched each time indexing runs. Set it higher to capture more history, or lower to focus on recent content.
</Info>

***

## Managing Installations

### List All X Installations

```bash theme={null}
curl https://apigcp.trynia.ai/v2/x/installations \
  -H "Authorization: Bearer $NIA_API_KEY"
```

```json theme={null}
{
  "installations": [
    {
      "id": "x-inst-7a3b9c01-...",
      "username": "elaborateai",
      "display_name": "Elaborate AI Posts",
      "max_results": 200,
      "include_replies": false,
      "include_retweets": false,
      "status": "indexed",
      "indexed_post_count": 200,
      "last_indexed_at": "2026-03-29T10:15:00Z"
    }
  ]
}
```

### Get a Single Installation

```bash theme={null}
curl https://apigcp.trynia.ai/v2/x/installations/x-inst-7a3b9c01-... \
  -H "Authorization: Bearer $NIA_API_KEY"
```

### Delete an Installation

Remove an installation and all its indexed data:

```bash theme={null}
curl -X DELETE https://apigcp.trynia.ai/v2/x/installations/x-inst-7a3b9c01-... \
  -H "Authorization: Bearer $NIA_API_KEY"
```

```json theme={null}
{
  "message": "Installation deleted and indexed data removed."
}
```

<Warning>
  Deleting an installation permanently removes all indexed post data from Nia. This cannot be undone.
</Warning>

***

## Indexing

### Trigger Indexing

Start an indexing job to fetch and index posts from the configured X account:

```bash theme={null}
curl -X POST https://apigcp.trynia.ai/v2/x/installations/x-inst-7a3b9c01-.../index \
  -H "Authorization: Bearer $NIA_API_KEY"
```

```json theme={null}
{
  "installation_id": "x-inst-7a3b9c01-...",
  "status": "processing",
  "workflow_run_id": "wf-89ab12cd-..."
}
```

### Check Indexing Status

```bash theme={null}
curl https://apigcp.trynia.ai/v2/x/installations/x-inst-7a3b9c01-.../status \
  -H "Authorization: Bearer $NIA_API_KEY"
```

```json theme={null}
{
  "installation_id": "x-inst-7a3b9c01-...",
  "username": "elaborateai",
  "status": "processing",
  "progress": 65,
  "message": "Fetching and embedding posts (130/200)",
  "indexed_post_count": 130,
  "chunk_count": 145
}
```

| Status       | Meaning                               |
| ------------ | ------------------------------------- |
| `created`    | Installation created, not yet indexed |
| `processing` | Indexing is in progress               |
| `indexed`    | Indexing completed successfully       |
| `failed`     | Indexing encountered an error         |

***

## Configuration Options

Control what gets indexed by adjusting the installation parameters at creation time.

<CardGroup cols={3}>
  <Card title="max_results" icon="list-ol">
    Fetch between 1 and 500 of the most recent posts per indexing run. Higher values capture more history but take longer.
  </Card>

  <Card title="include_replies" icon="reply">
    When enabled, reply tweets from the account are included in the index. Useful for capturing conversational context.
  </Card>

  <Card title="include_retweets" icon="retweet">
    When enabled, retweets are included. Disable to focus only on original content from the account.
  </Card>
</CardGroup>

***

## Searching Indexed Posts

Once indexed, posts from X accounts are searchable through Nia's unified search endpoint:

```bash theme={null}
curl -X POST https://apigcp.trynia.ai/v2/search/query \
  -H "Authorization: Bearer $NIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "What has this account said about AI agents?"}],
    "include_sources": true,
    "stream": true
  }'
```

You can combine X posts with other sources for cross-source queries:

```bash theme={null}
curl -X POST https://apigcp.trynia.ai/v2/search/query \
  -H "Authorization: Bearer $NIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Compare the public announcements with the actual implementation"}],
    "repositories": [{"repository": "acme/product"}],
    "include_sources": true,
    "stream": true
  }'
```

**Streamed response:**

```
data: {"content": "Based on the indexed posts from @elaborateai and the repository code..."}
data: {"sources": [{"content": "@elaborateai (2026-03-15): We just shipped...", "metadata": {...}}]}
data: [DONE]
```

***

## API Reference

| Method   | Endpoint                          | Description               |
| -------- | --------------------------------- | ------------------------- |
| `GET`    | `/v2/x/installations`             | List all X installations  |
| `POST`   | `/v2/x/installations`             | Create a new installation |
| `GET`    | `/v2/x/installations/{id}`        | Get installation details  |
| `DELETE` | `/v2/x/installations/{id}`        | Delete an installation    |
| `POST`   | `/v2/x/installations/{id}/index`  | Trigger indexing          |
| `GET`    | `/v2/x/installations/{id}/status` | Get indexing status       |

***

<Accordion title="FAQ: How often should I re-index?">
  Re-index whenever you want to capture new posts. Since the integration fetches the most recent posts (up to `max_results`), running indexing periodically keeps the content fresh. You can trigger it manually or build automation around the API.
</Accordion>

<Accordion title="FAQ: Does this work with private/protected accounts?">
  The X API v2 bearer token only provides access to public tweets. Protected accounts cannot be indexed unless you use an OAuth token with appropriate access, which is not currently supported by this integration.
</Accordion>

<Accordion title="FAQ: What X API plan do I need?">
  A Basic or Pro plan on the X Developer Portal is sufficient. The Free tier has limited tweet read access and may not support the `max_results` range needed. Check the [X API documentation](https://developer.x.com/en/docs) for current tier details.
</Accordion>

***

<Warning>
  **Need Help?** Join our [Discord community](https://discord.gg/BBSwUMrrfn) or reach out through [app.trynia.ai](https://app.trynia.ai/) for support.
</Warning>