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 "https://www.socialcrawl.dev/v1/twitter/profile?handle=elonmusk" \
-H "x-api-key: sc_your_key_here"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);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 "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 want | Call |
|---|---|
| An account's followers, bio and join date | GET /v1/twitter/profile |
| Where an account is based, and how it is verified | GET /v1/twitter/profile/about |
| An account's recent tweets, or only its photos and videos | GET /v1/twitter/user/tweets, GET /v1/twitter/user/media |
| An account's followers and who it follows | GET /v1/twitter/user/followers, GET /v1/twitter/user/following |
| One tweet in full | GET /v1/twitter/tweet |
| The replies to a tweet, and who retweeted it | GET /v1/twitter/tweet/replies, GET /v1/twitter/tweet/retweeters |
| What is said in a video | GET /v1/twitter/tweet/transcript |
| Tweets by keyword, hashtag or mention | GET /v1/twitter/search/tweets, GET /v1/twitter/search/hashtag, GET /v1/twitter/search/mentions |
| Accounts by name or keyword | GET /v1/twitter/search/users |
| A written answer with the posts it cites | GET /v1/twitter/ai-search |
| A community and its recent posts | GET /v1/twitter/community, GET /v1/twitter/community/tweets |
| A profile with posting cadence and engagement in one call | GET /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_countis always null. - Verification on follower and following lists. It comes back null there; fetch
profilefor the account you need it on. - Community history.
community/tweetsreturns one fixed window of recent posts and does not page.
What you can get
| Call | What it returns |
|---|---|
GET /v1/twitter/profile | Follower, 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/about | The 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/tweets | The 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/media | The same list, narrowed to tweets with a photo or video |
GET /v1/twitter/user/followers, GET /v1/twitter/user/following | About 70 accounts a page, with counts, bio, avatar and join date per row. Verification comes back null |
GET /v1/twitter/tweet | Text, likes, retweets, replies, bookmarks, views, media, author and timestamp, plus post.ext.quote_count |
GET /v1/twitter/tweet/replies, GET /v1/twitter/tweet/retweeters | The replies, with each commenter's counts on comment.ext, and the accounts that retweeted |
GET /v1/twitter/search/tweets, GET /v1/twitter/search/users | Tweets by keyword or phrase, and accounts by name, handle or keyword |
GET /v1/twitter/tweet/transcript | The spoken words of a video, auto-generated captions included |
GET /v1/twitter/community, GET /v1/twitter/community/tweets | A community's name, description, member count, creation date and rules (author.ext.rules), and its recent posts |
GET /v1/twitter/ai-search | A written answer, the X posts cited as sources, and how many searches the model ran |
GET /v1/twitter/profile/full | A 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.
Search
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.
Video, communities and AI search
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 "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 "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.
| Endpoint | Path | Credit Tier |
|---|---|---|
| Get Twitter community details | /v1/twitter/community | standard (1cr) |
| List Twitter community tweets | /v1/twitter/community/tweets | standard (1cr) |
| Get Twitter user profile | /v1/twitter/profile | standard (1cr) |
| Get a Twitter account's About details | /v1/twitter/profile/about | standard (2cr) |
| X (Twitter) profile, recent posts, and computed analytics in one call. | /v1/twitter/profile/full | standard (5cr) |
| Search X (Twitter) posts carrying a hashtag | /v1/twitter/search/hashtag | standard (0-1cr)metered |
| Search X (Twitter) posts that mention an account | /v1/twitter/search/mentions | standard (0-1cr)metered |
| Search Twitter tweets | /v1/twitter/search/tweets | standard (1-9cr)metered |
| Search Twitter users | /v1/twitter/search/users | standard (1cr) |
| Get Twitter tweet details | /v1/twitter/tweet | standard (1cr) |
| List Twitter tweet replies | /v1/twitter/tweet/replies | standard (1-5cr)metered |
| List Twitter tweet retweeters | /v1/twitter/tweet/retweeters | standard (1cr) |
| List Twitter user followers | /v1/twitter/user/followers | standard (1cr) |
| List Twitter user following | /v1/twitter/user/following | standard (1cr) |
| List Twitter user media tweets | /v1/twitter/user/media | standard (1cr) |
| List Twitter user tweets | /v1/twitter/user/tweets | standard (1-5cr)metered |
| AI-powered X (Twitter) search via xAI Grok | /v1/twitter/ai-search | advanced (5cr) |
| Get Twitter video transcript | /v1/twitter/tweet/transcript | premium (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
| Path | Rows per page | Date window | One call collects |
|---|---|---|---|
/v1/twitter/community/tweets | varies | since and until, applied to each page fetched | one page a call |
/v1/twitter/profile/full | varies | none | one page a call |
/v1/twitter/search/hashtag | about 20 | none | one page a call |
/v1/twitter/search/mentions | about 19 | none | one page a call |
/v1/twitter/search/tweets | varies | since and until. Newest first with sort=latest, so a walk stops at since. | up to 5,000 rows or 50 pages |
/v1/twitter/search/users | varies | none | up to 5,000 rows or 50 pages |
/v1/twitter/tweet/replies | about 36 | since and until. Newest first with sort=latest, so a walk stops at since. | up to 5,000 rows or 50 pages |
/v1/twitter/tweet/retweeters | about 20 | none | up to 5,000 rows or 50 pages |
/v1/twitter/user/followers | about 70 | none | up to 5,000 rows or 50 pages |
/v1/twitter/user/following | about 70 | none | up to 5,000 rows or 50 pages |
/v1/twitter/user/media | about 14 | since and until, applied to each page fetched | up to 5,000 rows or 50 pages |
/v1/twitter/user/tweets | about 14 | since and until, applied to each page fetched | up 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.
| Path | Typical (median) | 95% finish within | Timeout to set |
|---|---|---|---|
/v1/twitter/ai-search | 20 s | 44 s | 80 s |
/v1/twitter/profile | 1.4 s | 2.4 s | 10 s |
/v1/twitter/profile/full | 2.9 s | 11 s | 21 s |
/v1/twitter/search/tweets | 2.8 s | 6.7 s | 15 s |
/v1/twitter/search/users | 1.7 s | 6.1 s | 16 s |
/v1/twitter/tweet | 1.4 s | 3.3 s | 10 s |
/v1/twitter/tweet/replies | 2.4 s | 4.4 s | 12 s |
/v1/twitter/tweet/transcript | 8.2 s | 25 s | 41 s |
/v1/twitter/user/followers | 1.5 s | 2.1 s | 10 s |
/v1/twitter/user/media | 1.8 s | 3.6 s | 10 s |
/v1/twitter/user/tweets | 2.0 s | 4.6 s | 13 s |
Platform notes
profile,profile/full,user/tweets,user/media,user/followersanduser/followingtake ahandle(no@).tweet,tweet/replies,tweet/retweeters,tweet/transcript,communityandcommunity/tweetstake aurl.search/tweets,search/usersandai-searchtake aquery.- 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_urlsholds the first. trim=trueis accepted onuser/tweetsandtweetfor backwards compatibility and is ignored.
Official Twitter/X Resources
- X API Documentation: Official X developer platform
- X API Access Levels: API tiers and access
