Social Fetch
Get API key
X (Twitter) hub

X (Twitter) profile tweets API

Page recent public posts for an X handle — text, engagement metrics, media, and author context — in the shared Social Fetch response envelope.

GET /v1/twitter/profiles/{handle}/tweets

2 credits per successful request.

Try in playgroundFull API docs

About this endpoint

Brand monitoring and creator tools usually need the recent timeline after they already know the handle: last N posts, like and reply counts, and stable tweet URLs to open in a UI or fan out into single-tweet routes. Building that against X's own developer product means app review, elevated access tiers, and rate-limit math you do not want in a simple enrichment job.

`GET /v1/twitter/profiles/{handle}/tweets` lists public posts for a handle (with or without a leading `@`). Send `x-api-key`, then read `data.lookupStatus` before you treat the page as usable. On `found`, `data.tweets` holds the page rows and `data.page` carries `nextCursor` / `hasMore`. Optional query params: `limit` (default 40, max 100), `cursor`, `includeReplies` (default false), and `includePinned` (default false, first page only). Each tweet can include id, url, text, createdAt, language, reply/quote/retweet linkage, author, metrics, media, and source. `data.profile` is a compact card derived from author data when present.

This route pages a profile timeline. A single post by URL is `GET /v1/twitter/tweets`. The profile card alone is `GET /v1/twitter/profiles/{handle}`. Pricing is on the credit badge for this operation; bill from `meta.creditsCharged` on every response.

X (Twitter) profile tweets API FAQ

How do I list tweets for an X / Twitter profile via API?

Call `GET /v1/twitter/profiles/{handle}/tweets` with your Social Fetch API key (`x-api-key`) and the public handle in the path. Read `data.lookupStatus`, then `data.tweets` and `data.page`. Full parameters and examples are in the API docs linked from this page.

How much does the Twitter profile tweets endpoint 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.

How does pagination work on profile tweets?

Each response includes `data.page.nextCursor` and `data.page.hasMore`. When `hasMore` is true, pass `nextCursor` as the `cursor` query param on the next request. Keep the same handle and filters across pages. The cursor is opaque — do not invent or parse it.

Can I include replies or pinned tweets?

Yes. Pass `includeReplies=true` to include reply tweets (default is false). Pass `includePinned=true` to include pinned tweets on the first page (default is false). Page size is optional via `limit` (default 40, maximum 100).

What fields are in each tweet row?

Items can include id, url, text, createdAt, createdAtLabel, language, conversationId, reply/quote/retweet linkage fields, author (handle, display name, avatar, verification flags), metrics (likes, retweets, replies, quotes, views, bookmarks), media, expandedUrl, isRetweet, and source when X exposes them.

What happens for missing accounts or empty timelines?

Branch on `data.lookupStatus`. Unknown handles resolve as `not_found` with an empty `tweets` array. `found` can still return zero tweets when the profile has no eligible posts in the current page or filter set. Keep `meta.requestId` if you need support on a failed list call.

Profile tweets vs single tweet vs profile card?

Use this route to page a handle's public timeline. Use `GET /v1/twitter/tweets` when you already have a tweet URL. Use `GET /v1/twitter/profiles/{handle}` when you only need the profile card and metrics. They are separate operations on the Twitter / X hub.

Do I need an X developer app to list a profile's tweets?

No. You authenticate to Social Fetch with an API key. The route reads publicly visible timeline data; it does not act on behalf of a logged-in X user or require X Bearer tokens.

Other X (Twitter) endpoints