Social Fetch
Start for freeStart free
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

1 credit Failed requests are free

Try in playgroundFull API docs

About this endpoint

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}. Bill from meta.creditsCharged.

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. See the API docs for parameters and examples.

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.

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, bio, location, website, follower and following counts, affiliation label), metrics (likes, retweets, replies, quotes, views, bookmarks), media with alt text and video duration, link preview card, poll, article, tagged place, Community Note, entities, 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. Protected accounts resolve as private, with the profile card when available and 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.

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