Social Fetch
Get API key
X (Twitter) hub

X (Twitter) Tweet API

Resolve a public tweet URL (or numeric id) to structured post text, engagement metrics, and optional author profile in the shared Social Fetch envelope.

GET /v1/twitter/tweets

1 credit per successful request.

Try in playgroundFull API docs

About this endpoint

Monitoring and enrichment jobs often already have a status link from alerts, CRM notes, or search hits. The next step is a stable JSON post: text, view and engagement counts, media, quote/reply flags, and enough author context to store a row. Building that yourself means re-parsing x.com HTML or chasing unofficial GraphQL shapes every time the client changes.

`GET /v1/twitter/tweets` is the single-post lookup. Pass `url` as a tweet permalink (`x.com` or `twitter.com` `/status/...`) or a bare numeric tweet id, send `x-api-key`, and branch on `data.lookupStatus` before you write. On `found`, `data.tweet` holds id, url, text, language, createdAt, metrics (views, favorites, retweets, replies, bookmarks, quotes), media, entities, and quote/reply/repost fields when X exposes them. `data.author` mirrors a public profile card plus metrics unless you set `trim=true` for a smaller body without author or tweet `core`.

This route fetches one post. Timeline pages for a handle are `GET /v1/twitter/profiles/{handle}/tweets`. Thread replies are `GET /v1/twitter/tweets/replies`. Spoken text from a video tweet is `GET /v1/twitter/tweets/transcript`. Pricing is on the credit badge for this operation; bill from `meta.creditsCharged` on every response.

X (Twitter) Tweet API FAQ

How do I fetch a single X / Twitter tweet by URL?

Call GET /v1/twitter/tweets with your Social Fetch API key in the x-api-key header and a required url query param (tweet permalink or numeric id). Read data.lookupStatus, then data.tweet and data.author when the post is available. Full parameters and examples are in the API docs linked from this page.

How many credits does a Twitter tweet lookup cost?

Pricing is documented on the operation in the API registry (shown on this page). Confirm on every response with meta.creditsCharged — that field is the billing source of truth.

What does the tweet response include?

On a found lookup, data.tweet includes id, public url, text, language, timestamps, engagement metrics, media, entities, and flags for reply, quote, and retweet when present. data.author is a profile card plus aggregate metrics unless trim=true omits it. Exact field lists and nullability live in the OpenAPI schema for this route.

What is the trim query parameter?

Optional trim=true returns a smaller payload: author is null and tweet core detail is omitted. Use it when you only need post text and metrics and want less JSON per call.

What happens if the tweet is deleted or unavailable?

Branch on data.lookupStatus. not_found means Social Fetch could not return a public post for that url. Do not invent text or metrics. Keep meta.requestId if you need support on a failed lookup.

Tweet by URL vs profile tweets vs replies vs transcript?

Use this route when you already have a status link or id. Use GET /v1/twitter/profiles/{handle}/tweets to page a handle's timeline. Use GET /v1/twitter/tweets/replies for replies under a status. Use GET /v1/twitter/tweets/transcript for spoken text on video tweets. They are separate marketplace operations with their own credit notes.

Do I need an X developer account for this endpoint?

No. Authenticate with your Social Fetch API key only. You do not create an X developer app or pass X Bearer tokens for this public tweet lookup.

Other X (Twitter) endpoints