# X Post Info (twitter)

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/x/post/info` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 2 credits per call |
| **Documentation** | https://www.piloterr.com/library/x-post-info |

## Description

X Post Info API: fetch public tweet data (text, likes, retweets, views, media) from a status URL or tweet ID via browser rendering.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/x/post/info' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Tweet by @rauchg on x.com

```json
{
  "url": "https://x.com/rauchg/status/2070215849970119090",
  "name": null,
  "text": "Grok Imagine Video has become the clear leader in @vercel AI Gateway, now amounting to ~50% of videos generated by developers 🤯 vercel.com/ai-gateway/lea…",
  "media": [
    "https://pbs.twimg.com/media/HLrgznVbwAAG4y8.png"
  ],
  "tweet_id": "2070215849970119090",
  "username": "rauchg",
  "verified": true,
  "created_at": null,
  "like_count": 2517,
  "view_count": 232,
  "reply_count": 279,
  "retweet_count": 791
}
```

## Documentation

## Overview
The **X Post Info API** returns public tweet data from [x.com](https://x.com). Pass a **status URL** or **numeric tweet ID** and receive text, engagement metrics, media URLs, and author handle as JSON.

X status pages require **browser rendering** to load tweet articles and `window.__INITIAL_STATE__` data.

**X Search is not supported**: search results are not rendered as parseable HTML.

## Quickstart
```
GET https://api.piloterr.com/v2/x/post/info?query=https://x.com/rauchg/status/2070215849970119090
```

Or with tweet ID only:
```
GET https://api.piloterr.com/v2/x/post/info?query=2070215849970119090
```

Via POST:
```
POST https://api.piloterr.com/v2/x/post/info
Content-Type: application/json

{"query": "2070215849970119090", "return_page_source": false}
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Tweet URL (`/user/status/{id}`) or numeric status ID |
| `return_page_source` | boolean | no | Return raw HTML as `{"result": "..."}` (default: `false`) |

## Input formats
| Format | Example |
|---|---|
| Status URL | `https://x.com/rauchg/status/2070215849970119090` |
| Numeric ID | `2070215849970119090` |
| Legacy domain | `https://twitter.com/rauchg/status/2070215849970119090` |

## Response fields
| Field | Type | Always present | Description |
|---|---|---|---|
| `tweet_id` | string | yes | Numeric tweet ID |
| `username` | string | yes | Author handle |
| `name` | string \| null | no | Display name (often absent on status pages) |
| `text` | string \| null | no | Tweet content |
| `url` | string | yes | Canonical status URL |
| `created_at` | string \| null | no | Publication date (ISO 8601 when available) |
| `verified` | boolean | yes | Author verified badge |
| `reply_count` | integer \| null | no | Reply count |
| `retweet_count` | integer \| null | no | Retweet count |
| `like_count` | integer \| null | no | Like count |
| `view_count` | integer \| null | no | View count |
| `media` | string[] \| null | no | Image/thumbnail URLs |

Parsed from DOM `<article>` elements with fallback to `window.__INITIAL_STATE__`.

## Error codes
| Code | Meaning |
|---|---|
| `400` | Missing or invalid `query` |
| `404` | X error page, unrendered content, or tweet not found |
| `500` | Rendering or parsing error |

## Notes
- Accepted domains: `x.com`, `twitter.com`.
- `created_at` and `name` may be `null` when not exposed on the rendered status page.
- Costs **2 credits** per call (browser rendering, ~8s wait).

## Main use cases
- **Social listening**: track likes, retweets and views on specific posts
- **Brand monitoring**: ingest tweet text and media from status URLs
- **Trend analysis**: collect engagement metrics at scale
- **Archive enrichment**: resolve tweet IDs to canonical URLs and author handles