Collectors · Social & communities
Twitter (X) scraper API in Python
Latest public tweets of X profiles, with exact likes, replies, reposts and quotes. One POST from Python with usernames, rows back as JSON with 28 fields, $0.00025 per delivered tweet. No proxies or parsers to maintain.
First call
Install, call, read the rows.
pip install requestsimport os, requests
r = requests.post(
"https://api.quanticdata.io/v1/scraper/collectors/x_user_tweets/run",
headers={"Authorization": f"Bearer {os.environ['QD_API_KEY']}"},
json={
"usernames": ["NASA"],
"max_results": 20,
},
timeout=120,
)
r.raise_for_status()
run = r.json()["payload"]
print(run["count"], "rows,", run["cost"]["usd"], "USD")
for row in run["results"]:
print(row.get("username"), row.get("author_name"), row.get("author_followers"), row.get("author_verified"))The key comes from an environment variable, never from the code. The run answers in the same request when it finishes in time; payload.results holds the rows and payload.cost what they cost.
Request parameters
What the collector takes.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
usernames | string[] | yes | X handles, with or without @, or profile URLs, one per line, up to 20. |
include_replies | boolean | no (default true) | Deliver the profile's replies to other tweets too (default true). |
include_retweets | boolean | no (default true) | Deliver the profile's reposts too (default true). |
country | string | no | ISO 3166-1 alpha-2 code — proxy exit geo and Google locale (gl). Omit for the default pool. |
max_results | integer | no (default 20) | How many tweets to deliver at most (1–200). You pay only for delivered tweets. |
Response fields
28 fields per tweet.
| Field | Type | What it holds |
|---|---|---|
username | string | Profile handle. |
author_name | string, nullable | Profile display name. |
author_followers | integer, nullable | Profile follower count. |
author_verified | boolean | Verified badge on the profile. |
tweet_id | string | Tweet id. |
url | string | Tweet URL. |
created_at | string, nullable | Posted at (ISO 8601). |
text | string | Full text, t.co links expanded (the original's text for a repost). |
lang | string, nullable | Language code X assigned. |
likes | integer, nullable | Exact like count. |
replies | integer, nullable | Exact reply count. |
retweets | integer, nullable | Exact repost count. |
quotes | integer, nullable | Exact quote count. |
is_retweet | boolean | True for a repost; text and counts are the original tweet's. |
retweeted_user | string, nullable | Handle of the reposted author. |
original_tweet_id | string, nullable | Id of the reposted tweet. |
is_reply | boolean | True for a reply. |
in_reply_to_user | string, nullable | Handle replied to. |
in_reply_to_tweet_id | string, nullable | Tweet id replied to. |
conversation_id | string, nullable | Thread (conversation) id. |
is_quote | boolean | True when the tweet quotes another. |
quoted_tweet_id | string, nullable | Id of the quoted tweet. |
hashtags | string[] | Hashtags used. |
mentions | string[] | Handles mentioned. |
links | string[] | Expanded link URLs. |
media | object[] | Photos and videos: type, url, alt_text, video_url (best MP4), duration_seconds. |
possibly_sensitive | boolean | X's sensitive-media flag. |
rank | integer | 1-based delivery order. |
Add ?format=csv to the runs endpoint to get the same rows as CSV.
Long runs
Run in the background, then poll.
A run that needs more time can go to the background: send "async": true, get 202 with the run id, and poll the runs endpoint until the status is done. Reading a run is free.
import os, time, requests
H = {"Authorization": f"Bearer {os.environ['QD_API_KEY']}"}
r = requests.post("https://api.quanticdata.io/v1/scraper/collectors/x_user_tweets/run", headers=H,
json={**{"usernames":["NASA"],"max_results":20}, "async": True}, timeout=30)
run_id = r.json()["payload"]["run_id"]
while True:
run = requests.get(f"https://api.quanticdata.io/v1/scraper/collectors/runs/{run_id}", headers=H, timeout=30).json()["payload"]
if run["status"] in ("done", "failed"):
break
time.sleep(5)
print(run["status"], run["count"])Errors
What can come back, and what is billed.
| Status | Meaning | Billed |
|---|---|---|
400 | The input does not match the collector (payload.errors) | No |
401 | Missing or wrong API key | No |
402 | Balance and free credit do not cover the run: top up | No |
422 | The input can never resolve; retrying the same input cannot help | No |
424 | The run failed at the source (blocked, timed out, layout changed); safe to retry | No |
429 | Rate limit or a per-account brake; wait for Retry-After | No |
Only delivered rows are billed: a run that delivers nothing costs nothing.
Price
$0.00025 per delivered tweet.
| Rows | Cost |
|---|---|
| 1 | $0.00025 |
| 1,000 | $0.25 |
| 10,000 | $2.50 |
Up to 200 tweets per run; split larger jobs into several runs. The $2 free credit every month covers about 8,000 tweets. No subscription; paid tiers lower the unit price. All collector prices: collector pricing.
Before you run it
Questions developers ask
Is there a free X (Twitter) profile tweets API?
Every account gets $2 of free usage each month, about 8,000 tweets of this collector at $0.00025 each, with no card.
Do I have to handle proxies, retries or blocks?
No. The collector runs on our network and handles them; a run blocked at the source returns 424 and is not billed.
How many rows can one run return?
Up to 200 tweets per run (the max_results input, where the collector has one).
Can an AI agent run it?
Yes: the MCP server exposes it as the run_collector tool, with the same input and price. See the MCP server.
Run it on the free credit.
Create an API key, export it as QD_API_KEY and run the example. $0.00025 per delivered tweet, no subscription.