X (Twitter)

The X connector exposes three endpoints:

Endpoint	Purpose	Billed
GET /v1/x/search	Keyword / boolean post search, with optional deep-history date windowing	per page
GET /v1/x/post/{tweet_id}	A single post with author, media, and all engagement metrics	per request
GET /v1/x/user/{handle}	A public account's recent posts, newest first	per page

A common workflow is search → fetch: run a query to discover relevant posts, then pass any result's id (or url) to the post endpoint for the full record.

Post identifiers

A post is identified by its numeric tweet id — the code in a post URL. The post endpoint accepts either the id or a full URL verbatim:

https://x.com/nasa/status/1234567890123456789
                          └─────────────────┘
                          tweet_id = 1234567890123456789

Search and timeline results already include both the url and the id.

Post types

type	Meaning
post	A standard post
reply	A reply to another post
quote	A post quoting another post
repost	A repost (the original is under retweeted)

Quoted and reposted posts are nested one level deep under quoted / retweeted.

Engagement vocabulary

Every post carries engagement under stable keys in metrics:

Field	Meaning
replies	Reply count
retweets	Repost count
likes	Like count
quotes	Quote count
bookmarks	Bookmark count
views	View count, when available

Why some fields are null

Not every post exposes every metric. Missing values are returned as null rather than dropped, so your schema stays stable.

Engagement metrics are a snapshot taken when the post was captured. Every response includes a fetched_at UTC timestamp marking that moment, so you can re-fetch later and compare how a post's metrics changed over time.

Latency & reliability

X is a public-web source, so:

• Results are best-effort discovery — they reflect what is publicly available and can shift over time; they are not exhaustive.
• A single query surfaces only a shallow slice of recent posts. To reach deeper history, use the search endpoint's since parameter — see Search.
• Occasional 429 upstream_rate_limited responses indicate a transient block — retry with backoff and it will clear. See Errors.
• max_pages is capped at 15 per request (each page runs a sequential fetch). For big pulls, keep page counts modest and continue across multiple calls using the next_cursor returned by search and user-timeline responses.