X / Twitter Profile Timeline Scraper

Paste an X (Twitter) @handle or profile URL. Get profile stats + timeline tweets — likes, replies, reposts, views & text as clean JSON. MCP-ready for AI.

Actor: social_developer/x-twitter-profile-timeline-scraper
MCP: https://mcp.apify.com/?tools=social_developer/x-twitter-profile-timeline-scraper

Turns any public X profile into structured rows:

• Profile: username, name, bio, followersCount, followingCount, statusesCount, isBlueVerified
• Timeline: tweetId, text, likeCount, retweetCount, replyCount, quoteCount, viewCount, createdAt, url, media

Profile in → timeline out. One dataset row per tweet. Not affiliated with X Corp.

Why this scraper
Profile timeline focus	Resolves handle → paginates UserTweets
Stable schema	Predictable fields for sheets, agents, pipelines
Cookie + residential proxy	Depth that guest mode cannot deliver
MCP-ready	Same Apify MCP pattern as our IG / YT / FB actors

---

Sibling scrapers (same paste → JSON workflow)

Actor	Best for
X Profile Timeline (this)	Profile + tweets by @handle
Instagram Post & Reel Scraper	IG link → views / likes / comments
YouTube Video Link Scraper	YT link → views / likes / comments
Facebook Posts & Reels Scraper	FB link → reactions / comments / shares / plays

---

Input

{
  "profiles": ["https://x.com/handle"],
  "fromDate": "2026-08-18",
  "toDate": "2026-08-20"
}

Field	Meaning
profiles	Profile link (https://x.com/handle) or @handle
fromDate	Start of window (inclusive), YYYY-MM-DD
toDate	End of window (inclusive), YYYY-MM-DD

There is no tweet cap. The Actor returns every tweet in the date window (or the full recent timeline if dates are empty). Auth cookies are built in — users do not paste them.

Wide ranges are split into 5-day search windows internally.

---

Output (one row per tweet)

{
  "inputProfile": "NASA",
  "username": "NASA",
  "userId": "11348282",
  "name": "NASA",
  "followersCount": 85000000,
  "tweetId": "1234567890",
  "url": "https://x.com/NASA/status/1234567890",
  "text": "…",
  "likeCount": 1200,
  "retweetCount": 400,
  "replyCount": 80,
  "viewCount": 250000,
  "createdAt": "2026-01-15T12:00:00Z",
  "isRetweet": false,
  "isReply": false,
  "hasMedia": true,
  "mediaUrls": ["https://pbs.twimg.com/…"],
  "scrapedAt": "2026-08-01T19:00:00Z"
}

---

Local run

cd X_TWITTER_PROFILE_TIMELINE_SCRAPER
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# Profile link + date range (all tweets in window)
python run_local.py https://x.com/handle --from 2026-08-18 --to 2026-08-20 --out output/run.json

Apify local:

$apify run -p

---

How it works

1. Normalize @handle / x.com/handle / twitter.com/handle.
2. Refresh GraphQL queryIds from X client JS when possible.
3. UserByScreenName → profile metadata + userId.
4. Paginate until the date window (or timeline) is exhausted.
5. Emit one dataset row per tweet (profile fields denormalized).

GraphQL query IDs rotate when X ships a new web client. Baked IDs + fallbacks live in src/constants.py; the actor also refreshes from client JS on hard 404s. If feature flags break, update FEATURES / USER_FEATURES there.

---

Out of scope (v1)

Followers/following export, keyword search, single-tweet-by-URL mode, posting, monitors, webhooks. Those can be separate actors later.

---

License / affiliation

Independent third-party tool. Not affiliated with X Corp. "Twitter" and "X" are trademarks of X Corp. Use only on data you are allowed to access; respect X Terms of Service and applicable law.