SocialCrawl

Twitter/X data API

Read profiles, tweets and search results from Twitter/X with one key and one response shape.

Read X (formerly Twitter) profiles and their tweets, single tweets in full, communities, video transcripts and an AI-answered search over the network. One composite call returns a profile with computed analytics. Every endpoint returns the same JSON shape.

Your first call

1. Fetch a profile

cURL
curl "https://www.socialcrawl.dev/v1/twitter/profile?handle=elonmusk" \
  -H "x-api-key: sc_your_key_here"
TypeScript
const url = new URL("https://www.socialcrawl.dev/v1/twitter/profile");
url.searchParams.set("handle", "elonmusk");
const res = await fetch(url, {
  headers: { "x-api-key": process.env.SOCIALCRAWL_API_KEY! },
});
const { data } = await res.json();
console.log(data.author.display_name, data.author.followers);
Python
import os
import requests

res = requests.get(
    "https://www.socialcrawl.dev/v1/twitter/profile",
    headers={"x-api-key": os.environ["SOCIALCRAWL_API_KEY"]},
    params={"handle": "elonmusk"},
)
author = res.json()["data"]["author"]
print(author["display_name"], author["followers"])

The response is one author object with the follower, following and post counts, verification, privacy flag and join date. Measured on 22/11/2026: this call took about 6 seconds and cost 1 credit.

2. Fetch their content

cURL
curl "https://www.socialcrawl.dev/v1/twitter/user/tweets?handle=elonmusk" \
  -H "x-api-key: sc_your_key_here"

3. Read computed fields

When an endpoint supports a computed field and the required source inputs are present, the unified response includes that optional field. Depending on the endpoint, optional fields can include engagement_rate, language, content_category, and estimated_reach. See Computed fields for formulas, clamping rules, and null semantics. Where an endpoint supports them, list rows also carry judged labels (computed.labels, computed.relevance) by default at no extra credits; see Labels.

What it covers

What you wantCall
An account's followers, bio and join dateGET /v1/twitter/profile
Where an account is based, and how it is verifiedGET /v1/twitter/profile/about
An account's recent tweets, or only its photos and videosGET /v1/twitter/user/tweets, GET /v1/twitter/user/media
An account's followers and who it followsGET /v1/twitter/user/followers, GET /v1/twitter/user/following
One tweet in fullGET /v1/twitter/tweet
The replies to a tweet, and who retweeted itGET /v1/twitter/tweet/replies, GET /v1/twitter/tweet/retweeters
What is said in a videoGET /v1/twitter/tweet/transcript
Tweets by keyword, hashtag or mentionGET /v1/twitter/search/tweets, GET /v1/twitter/search/hashtag, GET /v1/twitter/search/mentions
Accounts by name or keywordGET /v1/twitter/search/users
A written answer with the posts it citesGET /v1/twitter/ai-search
A community and its recent postsGET /v1/twitter/community, GET /v1/twitter/community/tweets
A profile with posting cadence and engagement in one callGET /v1/twitter/profile/full

What it does not cover

  • Private accounts and anything behind a login.
  • Total likes received. X publishes no such figure, so author.likes_count is always null.
  • Verification on follower and following lists. It comes back null there; fetch profile for the account you need it on.
  • Community history. community/tweets returns one fixed window of recent posts and does not page.

What you can get

CallWhat it returns
GET /v1/twitter/profileFollower, following and tweet counts, bio, avatar, banner (author.ext.cover_url), bio website (author.ext.bio_link), verification, privacy flag, join date and location
GET /v1/twitter/profile/aboutThe same profile plus the region it is based in (author.ext.account_based_in), how it signed up (author.ext.signup_source), its handle history (author.ext.username_changes) and the verification breakdown
GET /v1/twitter/user/tweetsThe Posts tab newest first, with retweets, self-threads and the pinned tweet flagged. Each row carries the author's counts (post.ext.author_followers and siblings)
GET /v1/twitter/user/mediaThe same list, narrowed to tweets with a photo or video
GET /v1/twitter/user/followers, GET /v1/twitter/user/followingAbout 70 accounts a page, with counts, bio, avatar and join date per row. Verification comes back null
GET /v1/twitter/tweetText, likes, retweets, replies, bookmarks, views, media, author and timestamp, plus post.ext.quote_count
GET /v1/twitter/tweet/replies, GET /v1/twitter/tweet/retweetersThe replies, with each commenter's counts on comment.ext, and the accounts that retweeted
GET /v1/twitter/search/tweets, GET /v1/twitter/search/usersTweets by keyword or phrase, and accounts by name, handle or keyword
GET /v1/twitter/tweet/transcriptThe spoken words of a video, auto-generated captions included
GET /v1/twitter/community, GET /v1/twitter/community/tweetsA community's name, description, member count, creation date and rules (author.ext.rules), and its recent posts
GET /v1/twitter/ai-searchA written answer, the X posts cited as sources, and how many searches the model ran
GET /v1/twitter/profile/fullA profile, its recent posts, two average engagement rates, posting cadence, top post and format mix

Accounts and tweets

A retweet row's computed.engagement_rate is null, because its counts belong to the original post. The original's numbers are on post.ext.retweeted_post. A post that publishes an X Article reads as the article's title, with the link in post.ext.article_url.

tweet does not check the handle in the URL. X serves a status by its numeric id, so the author you get back can differ from the handle you sent.

Put X's own operators in query: since_time: and until_time: in Unix seconds, from:handle, min_faves:20, filter:images and filter:videos. They beat dated since: and until:, which can return posts outside that day. The since and until parameters only filter the rows that come back.

sort=top ranks by engagement, so quote a multi-word phrase when you need precision. A post that is only a link is left out, and _warnings counts them. post.ext.author_location is the free text from the author's profile, not a country code. Discover reads a country from it. search/users has no spelling correction, so check the handle it returns.

tweet/transcript covers videos up to 10 minutes. A longer video returns the captions X publishes, if any, and otherwise 400 video_too_long. A video with no speech returns 404 no_captions. Both errors are free. See error reasons.

community/tweets returns one fixed window of 16 to 20 recent posts, and neither community call paginates. ai-search takes a plain-English query and narrows with from_handles, exclude_handles, from_date and to_date. Read a thin answer as thin retrieval, because search/tweets over the same window routinely finds more.

The composite

profile/full runs the profile and recent-post calls in parallel. posts sets how many tweets to average over, and include=computed drops the raw posts[] to save payload.

cURL
curl "https://www.socialcrawl.dev/v1/twitter/profile/full?handle=elonmusk&posts=50" \
  -H "x-api-key: YOUR_API_KEY"

Reading further back than one page

user/tweets, user/media, search/tweets, search/users, tweet/replies, tweet/retweeters, user/followers and user/following are all cursor-paged. Send pagination.next_cursor back as cursor until pagination.has_more is false. A page costs 1 credit, and the source sets the page size.

When the main source cannot fetch a page of user/tweets or a latest search, a second source answers it from the same position. Nothing repeats and the price stays the same. A first page answered that way for sort=top or tweet/replies is one page with no cursor.

profile/full takes a prior posts_cursor back as cursor. Its posts leg is one page of about 20 tweets, so posts=100 still returns about 20. community/tweets does not page, and a cursor sent to it is a 400 before it costs a credit.

The profile leg is the only critical leg on profile/full. If the tweets cannot be fetched you still get a 200 with the profile and null post-dependent metrics rather than an error, and every leg's outcome is reported in legs[]. Check legs[] before you treat a null cadence as a quiet account.

Labels

These lists label their rows by default, at no extra credit. Replies carry sentiment, question, purchase_intent and complaint on computed.labels. user/tweets and search/tweets rows carry sponsored, intent and niche. search/tweets adds a computed.relevance score. Send judgments=off to skip them. See Labels for the field shapes.

Questions people ask

How do I search a hashtag or the mentions of an account?

GET /v1/twitter/search/hashtag takes hashtag, with or without the #. It keeps only posts that carry that exact tag. So #tractor leaves out #tractorlife. GET /v1/twitter/search/mentions takes handle and returns posts that mention the account or reply to it, without the account's own posts unless you send include_self=true. Each row says why it matched in match_kind. Both take sort (latest by default, or top), since and until (YYYY-MM-DD), and cursor. Each page costs 1 credit.

cURL
curl "https://www.socialcrawl.dev/v1/twitter/search/hashtag?hashtag=farmer&sort=latest" \
  -H "x-api-key: YOUR_API_KEY"

How do I get only the replies since my last check?

Call GET /v1/twitter/tweet/replies with the tweet url, sort=latest and since_id set to the newest reply id from your last check. It returns only newer replies, newest first, and stops once it reaches older ones. A check with nothing new returns an empty list and costs nothing. since_id takes digits only, and sort=relevance with it is a free 400. Without sort, replies come in the platform's own ranking, not in time order.

How do I sort the rows a search collected, newest first?

Send sort_rows=newest on GET /v1/twitter/search/tweets. It orders the rows the call collected by publish date, newest first, with undated rows last. sort_rows=views orders them by view count, highest first. The sort covers only the rows that call collected over the pages it walked, so raise max_pages or max_items to give it more to sort. It does not reorder the whole feed. Each page walked is billed at 1 credit.

Why do an account's tweets stop at about 20, and how do I read more?

GET /v1/twitter/user/tweets returns about 20 tweets a page, because the page size is set by the source. Deeper history is a cursor walk: send pagination.next_cursor back as cursor until pagination.has_more is false. Send max_items or max_pages to walk several pages in one call, since to stop a newest-first walk at a date, or stop_at_id to stop at the newest tweet you already hold. Each page walked is billed as one call.

What does four hashtags cost, and how do I track them?

GET /v1/twitter/search/hashtag takes one hashtag a call, so four hashtags are four calls, and each one walks its own pages. Every page is one search/tweets page at 1 credit. A page served from cache is free, and a failed page costs nothing. data.legs lists each page's charge and data.excluded counts the rows left out, such as #tractorlife for #tractor. Narrow the window with since and until, both as YYYY-MM-DD.

All endpoints

18 endpoints available.

EndpointPathCredit Tier
Get Twitter community details/v1/twitter/communitystandard (1cr)
List Twitter community tweets/v1/twitter/community/tweetsstandard (1cr)
Get Twitter user profile/v1/twitter/profilestandard (1cr)
Get a Twitter account's About details/v1/twitter/profile/aboutstandard (2cr)
X (Twitter) profile, recent posts, and computed analytics in one call./v1/twitter/profile/fullstandard (5cr)
Search X (Twitter) posts carrying a hashtag/v1/twitter/search/hashtagstandard (0-1cr)metered
Search X (Twitter) posts that mention an account/v1/twitter/search/mentionsstandard (0-1cr)metered
Search Twitter tweets/v1/twitter/search/tweetsstandard (1-9cr)metered
Search Twitter users/v1/twitter/search/usersstandard (1cr)
Get Twitter tweet details/v1/twitter/tweetstandard (1cr)
List Twitter tweet replies/v1/twitter/tweet/repliesstandard (1-5cr)metered
List Twitter tweet retweeters/v1/twitter/tweet/retweetersstandard (1cr)
List Twitter user followers/v1/twitter/user/followersstandard (1cr)
List Twitter user following/v1/twitter/user/followingstandard (1cr)
List Twitter user media tweets/v1/twitter/user/mediastandard (1cr)
List Twitter user tweets/v1/twitter/user/tweetsstandard (1-5cr)metered
AI-powered X (Twitter) search via xAI Grok/v1/twitter/ai-searchadvanced (5cr)
Get Twitter video transcript/v1/twitter/tweet/transcriptpremium (10cr)

How far back and how deep

Each list returns one page at a time. Send cursor for the next page, or max_items or max_pages to collect several pages in one call. A page size appears only where it has been verified. How paging works

PathRows per pageDate windowOne call collects
/v1/twitter/community/tweetsvariessince and until, applied to each page fetchedone page a call
/v1/twitter/profile/fullvariesnoneone page a call
/v1/twitter/search/hashtagabout 20noneone page a call
/v1/twitter/search/mentionsabout 19noneone page a call
/v1/twitter/search/tweetsvariessince and until. Newest first with sort=latest, so a walk stops at since.up to 5,000 rows or 50 pages
/v1/twitter/search/usersvariesnoneup to 5,000 rows or 50 pages
/v1/twitter/tweet/repliesabout 36since and until. Newest first with sort=latest, so a walk stops at since.up to 5,000 rows or 50 pages
/v1/twitter/tweet/retweetersabout 20noneup to 5,000 rows or 50 pages
/v1/twitter/user/followersabout 70noneup to 5,000 rows or 50 pages
/v1/twitter/user/followingabout 70noneup to 5,000 rows or 50 pages
/v1/twitter/user/mediaabout 14since and until, applied to each page fetchedup to 5,000 rows or 50 pages
/v1/twitter/user/tweetsabout 14since and until, applied to each page fetchedup to 5,000 rows or 50 pages

How long a call takes

Measured on production calls that were not served from the cache, 14/10/2026 to 21/10/2026. A cached call answers faster. Set your client timeout to the value in Timeout to set, so a slow call is not cut off and sent again.

PathTypical (median)95% finish withinTimeout to set
/v1/twitter/ai-search20 s44 s80 s
/v1/twitter/profile1.4 s2.4 s10 s
/v1/twitter/profile/full2.9 s11 s21 s
/v1/twitter/search/tweets2.8 s6.7 s15 s
/v1/twitter/search/users1.7 s6.1 s16 s
/v1/twitter/tweet1.4 s3.3 s10 s
/v1/twitter/tweet/replies2.4 s4.4 s12 s
/v1/twitter/tweet/transcript8.2 s25 s41 s
/v1/twitter/user/followers1.5 s2.1 s10 s
/v1/twitter/user/media1.8 s3.6 s10 s
/v1/twitter/user/tweets2.0 s4.6 s13 s

Platform notes

  • profile, profile/full, user/tweets, user/media, user/followers and user/following take a handle (no @). tweet, tweet/replies, tweet/retweeters, tweet/transcript, community and community/tweets take a url. search/tweets, search/users and ai-search take a query.
  • Long-form posts return their complete body, with t.co links resolved to their destinations.
  • A tweet with several photos lists every URL in post.ext.all_media_urls. post.content.media_urls holds the first.
  • trim=true is accepted on user/tweets and tweet for backwards compatibility and is ignored.

Official Twitter/X Resources

Next steps