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

# X (formerly Twitter)

> Track X accounts, search posts, and backfill history in real-time

Monitor X accounts in real-time with sub-second latency. Track users, search posts by keyword or cashtag, fetch user profiles, and backfill historical data.

## What You Can Do

| Capability       | Endpoint                   | Description                                  |
| ---------------- | -------------------------- | -------------------------------------------- |
| **Track Users**  | `POST /track/x`            | Monitor an X account for new posts           |
| **User Profile** | `GET /x/user`              | Fetch user profile by username               |
| **Get Post**     | `GET /x/tweet`             | Fetch a specific post by ID                  |
| **Search Posts** | `GET /x/search`            | Full-text search with pagination             |
| **Quick Search** | `GET /x/quick-search`      | Typeahead search for users, cashtags, topics |
| **Backfill**     | `PUT /backfill`            | Trigger historical data backfill             |
| **History**      | `GET /account/history/:id` | Retrieve backfilled historical posts         |

## Track an X User

Start receiving real-time posts from any public X account.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://scrape.st/track/x \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"sid": "elonmusk"}'
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch("https://scrape.st/track/x", {
    method: "POST",
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ sid: "elonmusk" }),
  });
  const data = await res.json();
  ```

  ```python Python theme={null}
  import requests

  res = requests.post(
      "https://scrape.st/track/x",
      headers={"x-api-key": "YOUR_API_KEY"},
      json={"sid": "elonmusk"},
  )
  print(res.json())
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "data": {
    "id": "src_123",
    "source": "X",
    "externalId": "elonmusk",
    "username": "elonmusk",
    "name": "Elon Musk"
  },
  "message": "Now tracking elonmusk on x"
}
```

## Search Posts

Search for posts matching a keyword, cashtag, or phrase. Useful for monitoring token mentions like `$BTC`, `$ETH`, or any trending topic.

```bash theme={null}
# Search for Bitcoin-related posts
curl -X GET "https://scrape.st/x/search?q=%24BTC&count=20" \
  -H "x-api-key: YOUR_API_KEY"

# Quick search (typeahead) for users and cashtags
curl -X GET "https://scrape.st/x/quick-search?q=solana&resultTypes=users,cashtags" \
  -H "x-api-key: YOUR_API_KEY"
```

## Backfill History

Trigger a historical backfill to retrieve past posts from tracked accounts.

<Note>
  In the examples below, `src_123` is the **internal ID** of the account whose
  historical data you want to pull. This is the same `id` returned when you
  created the tracking via `POST /track/x`.
</Note>

```bash theme={null}
# Trigger backfill
curl -X PUT https://scrape.st/backfill \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "src_123"}'

# Check backfill status
curl -X GET "https://scrape.st/backfill/status?id=src_123" \
  -H "x-api-key: YOUR_API_KEY"

# Retrieve historical data
curl -X GET "https://scrape.st/account/history/src_123?limit=50" \
  -H "x-api-key: YOUR_API_KEY"
```

## Webhook Payload

When a tracked X user posts, your webhook receives a `SourceEvent` object. This is the exact shape sent via `JSON.stringify` to your webhook URL:

```json theme={null}
{
  "mid": "1886493083207827456",
  "sid": "44196397",
  "source": "x",
  "timestamp": 1712072400000,
  "content": "Bitcoin hits new all-time high! 🚀 $BTC",
  "images": ["https://pbs.twimg.com/media/xxx.jpg"],
  "payload": {
    "id": "1886493083207827456",
    "text": "Bitcoin hits new all-time high! 🚀 $BTC",
    "created_at": "2024-04-02T15:30:00.000Z",
    "lang": "en",
    "favorite_count": 15000,
    "retweet_count": 3000,
    "reply_count": 800,
    "quote_count": 400,
    "bookmark_count": 1200,
    "author": {
      "id": "44196397",
      "name": "Elon Musk",
      "screen_name": "elonmusk",
      "profile_image_url": "https://pbs.twimg.com/profile_images/xxx/photo.jpg",
      "verified": true,
      "is_blue_verified": true
    },
    "entities": {
      "symbols": [{ "text": "BTC" }],
      "hashtags": [],
      "urls": [],
      "user_mentions": []
    },
    "media": [],
    "retweeted_tweet": false,
    "link": "https://x.com/elonmusk/status/1886493083207827456"
  }
}
```

| Field       | Type   | Description                                               |
| ----------- | ------ | --------------------------------------------------------- |
| `mid`       | string | Message ID — the post ID                                  |
| `sid`       | string | Source ID — the author's X user ID                        |
| `source`    | string | `"x"` or `"fast-x"` (fast push before GraphQL enrichment) |
| `timestamp` | number | Unix timestamp (ms) when the event was received           |
| `content`   | string | Post text (note-tweet text for long posts, else `text`)   |
| `images`    | array  | Photo URLs from the post's media (videos excluded)        |
| `payload`   | object | Full `ResolvedXPost` object (see fields above)            |

## API Reference

All tracking endpoints use `/track/:source` where `:source` is `x`, `telegram`, or `discord`.

* [Create Tracking](/rest-api-reference/create-tracking) — `POST /track/x`
* [List Tracked Sources](/rest-api-reference/list-tracking) — `GET /track/x`
* [Delete Tracking](/rest-api-reference/delete-tracking) — `DELETE /track/x`
* [User Information](/rest-api-reference/user-information) — `GET /x/user`
* [Post Data](/rest-api-reference/tweet-data) — `GET /x/tweet`
* [Search Posts](/rest-api-reference/search-tweets) — `GET /x/search`
* [Quick Search](/rest-api-reference/quick-search) — `GET /x/quick-search`
* [Trigger Backfill](/rest-api-reference/backfill/trigger) — `PUT /backfill`
* [Backfill Status](/rest-api-reference/backfill/status) — `GET /backfill/status`
* [Get History](/rest-api-reference/backfill/get-history) — `GET /account/history/:id`