# 🐦 X (Twitter) Scraper ✅ 100% Success | $0.25/1K | Search (`jacquemus/x-tweet-scraper`) Actor

The X API alternative that does not break: scrape X (Twitter) by search, username, tweet URL or ID for $0.25 per 1,000 — under the usual $0.25-0.40. 100% run success over the last 30 days. Full advanced search, no API key, no login. Text, media, views, likes, reposts, replies.

- **URL**: https://apify.com/jacquemus/x-tweet-scraper.md
- **Developed by:** [Jacquemus](https://apify.com/jacquemus) (community)
- **Categories:** Social media, Lead generation, Developer tools
- **Stats:** 25 total users, 7 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.10 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## 🐦 X (Twitter) Scraper — $0.25 / 1,000 tweets

**Scrape X (Twitter) into clean, structured JSON — from a scraper that does not
break.** Give it a **search query**, a **username**, or **tweet links**, and get
back tidy tweet records with full engagement metrics, media, and author data.
No X API key, no developer account, no login — just results.

> **$0.25 per 1,000 tweets**, under the usual $0.25–0.40 — and **100% of runs
> succeeded over the last 30 days** (5,000+ runs, see the stats above). Pay only
> for what you keep. Built on X's own endpoints over plain HTTP — no headless
> browser, so it stays fast and predictable.

***

### ⚡ Why this scraper

- 🛡️ **Built not to break** — 100% run success over the last 30 days. X changes
  its internals constantly; this scraper detects that and repairs itself mid-run,
  and a canary checks every data path hourly.
- 💸 **$0.25 / 1,000 tweets** — under the usual $0.25–0.40. No start fee, no
  per-query fee.
- 🔎 **Full X advanced search** — every operator works (`min_faves:`, `since:`,
  `from:`, `filter:media`, `lang:`, …). See the table below.
- 📊 **Complete engagement data** — likes, reposts, replies, quotes, **views**,
  and bookmarks on every tweet.
- 🖼️ **Media with thumbnails** — image, video, and GIF URLs, plus a video
  **poster** image so you can preview without downloading.
- 🔁 **Retweets expanded** — get the original tweet's full text and media, not the
  truncated `RT @…` shell.
- 🤖 **AI-agent ready** — callable as a tool from Claude, ChatGPT, Cursor, and any
  MCP client (see below).
- 🚀 **Fast & lightweight** — pure HTTP, no browser, so runs finish quickly.
- 🛡️ **Self-healing** — X changes its internal endpoints without notice; most
  scrapers go dark for days when that happens. This one detects the change
  mid-run, re-syncs itself against live X, and keeps delivering — no waiting for
  a developer to ship a fix.

***

### 🎯 What you can use it for

- **Market & brand research** — track what people say about a product, brand, or
  ticker in real time.
- **AI / LLM training & RAG** — feed fresh, structured tweets into your models,
  retrieval systems, and agents.
- **Sentiment & trend monitoring** — pull the latest tweets on any topic or
  hashtag and run your own analysis.
- **Finance & alt-data** — collect social signal around tickers and events for
  trading models.
- **Lead generation & outreach** — find people asking about what you offer.

***

### 🧭 What you can scrape

| Input | What you get |
|---|---|
| **Search** — `searchTerms` | Tweets matching a keyword/hashtag query (full advanced-search syntax) |
| **User timelines** — `usernames` | A user's recent tweets (paginated) |
| **Tweet URLs** — `tweetUrls` | Specific tweets by link (profile links → timelines) |
| **Tweet IDs** — `tweetIds` | Specific tweets by numeric id |

Pick one mode per run. Set `searchMode` to `Latest`, `Top`, or `Media`.

***

### 🤖 Use with AI agents (MCP)

This Actor is callable by AI agents through the **Apify MCP server** — no extra
setup. Point any MCP-capable client (Claude Desktop, ChatGPT, Cursor, or your own
agent) at `https://mcp.apify.com` and just ask:

> *"Search X for what people are saying about \<topic> and summarize the sentiment."*

The agent runs this Actor as a tool and streams back clean, structured tweets.

***

### 📥 Input examples

**Scrape user timelines:**

```json
{ "usernames": ["nasa", "esa"], "maxItems": 200, "includeReplies": false }
```

**Search with advanced operators:**

```json
{
  "searchTerms": ["artificial intelligence min_faves:100", "#nasa since:2026-01-01"],
  "searchMode": "Latest",
  "maxItems": 500,
  "includeSearchTerms": true
}
```

### Advanced search operators

`searchTerms` is passed to X exactly as if typed into X's search box, so **every
X advanced-search operator works** — no extra fields needed. Combine them freely:

| Goal | Operator | Example |
|---|---|---|
| Min engagement | `min_faves:` `min_retweets:` `min_replies:` | `climate min_faves:500` |
| Date range | `since:` `until:` | `nasa since:2026-01-01 until:2026-02-01` |
| By / to / mentioning a user | `from:` `to:` `@` | `from:nasa filter:media` |
| Language | `lang:` | `deprem lang:tr` |
| Only media / images / video | `filter:media` `filter:images` `filter:videos` | `spacex filter:videos` |
| Verified / Blue only | `filter:verified` `filter:blue_verified` | `ai filter:blue_verified` |
| Links / news / hashtags | `filter:links` `filter:news` `filter:hashtags` | `earnings filter:news` |
| A whole thread | `conversation_id:` | `conversation_id:1750000000000000001` |
| Tweets from a List | `list:` | `list:123456789` |
| Near a place | `near:` `within:` | `protest near:"Istanbul" within:20km` |
| Exclude a term | `-` | `apple -fruit` |
| Exact phrase | `"..."` | `"artificial general intelligence"` |

***

### 📤 Output

One tidy JSON object per tweet:

```json
{
  "id": "2075249100035866880",
  "url": "https://x.com/NASA/status/2075249100035866880",
  "text": "July 12 will mark four years of science from @NASAWebb! …",
  "createdAt": "2026-07-09T16:01:56.000Z",
  "lang": "en",
  "likeCount": 216,
  "retweetCount": 38,
  "replyCount": 45,
  "quoteCount": 3,
  "viewCount": 66671,
  "bookmarkCount": 12,
  "authorUsername": "NASA",
  "authorFollowers": 92161445,
  "authorVerified": true,
  "imageUrls": ["https://pbs.twimg.com/media/%E2%80%A6jpg"],
  "hashtags": [],
  "mentions": ["NASAWebb"],
  "isRetweet": false,
  "quotedTweetId": null
}
```

Video and GIF tweets also carry a `poster` (cover image) alongside the playback
URL in the `media` array, so you can show a thumbnail without downloading the
video. Full field list in `src/types.ts`.

***

### 💸 Pricing

**Pay per result** — $0.25 per 1,000 tweets delivered. Duplicates are removed
before you're charged. No start fee, no per-query fee. Cap any run with `maxItems`.

**As an X API alternative:** X's official API starts at **$200/month** for
15,000 tweets (~$13 per 1,000). The same 1,000 tweets here cost **$0.25** — with
no subscription, no approval process, and full advanced search included.

***

### ❓ FAQ

**Do I need an X API key or account?** No. Everything runs on Apify's
infrastructure — no key, no login, no developer account.

**What data does it collect?** Only **public** tweets — the same posts anyone can
see. No private/protected accounts, no DMs.

**What format is the output?** Flat JSON, exportable to CSV, Excel, JSON, or via
the API — ready for spreadsheets, databases, and AI pipelines.

**How do I control cost?** Set `maxItems` for a hard cap. You only pay per tweet
delivered.

**Can I search with filters?** Yes — every X advanced-search operator works (see
the table above): engagement thresholds, dates, language, media, verified-only,
and more.

**What happens when X changes its internals?** The scraper detects the rejection
mid-run, refreshes its configuration from live X automatically, and retries —
your run keeps producing data instead of failing. Reliability is monitored 24/7
on top of that.

**Can I export tweets to CSV or Excel?** Yes — every run's dataset downloads as
CSV, Excel, JSON, or XML straight from Apify, or via API into Google Sheets,
Python, or your database.

***

*Scrapes public data only. Please use responsibly and in line with applicable
laws and X's terms.*

# Actor input Schema

## `searchTerms` (type: `array`):

Search X for keywords or hashtags and return matching tweets. Use this to find what people are saying about a topic in real time. Supports X advanced-search operators: min\_faves:100 (min likes), since:2026-01-01 / until: (date range), lang:en, from:username, filter:media. Example: \["AI agents min\_faves:50", "#nasa since:2026-01-01"]. Each term is searched separately.

## `searchMode` (type: `string`):

Which search tab to pull from when using searchTerms. 'Latest' = most recent tweets (best for real-time monitoring), 'Top' = most engaged tweets, 'Media' = tweets with images/video.

## `usernames` (type: `array`):

Scrape recent tweets from these users' timelines. Provide X handles WITHOUT the @ symbol. Use this to monitor what specific accounts are posting. Example: \["nasa", "elonmusk"].

## `tweetUrls` (type: `array`):

Fetch specific tweets by their x.com/twitter.com links (each fetched individually). Profile URLs (e.g. https://x.com/nasa) are treated as timelines. Use this when you already have the exact tweet links.

## `tweetIds` (type: `array`):

Fetch specific tweets by their numeric ID (the number at the end of a tweet URL). Use this when you have raw tweet IDs rather than full links. Example: \["2075249100035866880"].

## `maxItems` (type: `integer`):

Maximum number of tweets to collect across all inputs. You are billed per tweet returned, so set this to the smallest number you need. 0 = no limit. Default 100.

## `includeReplies` (type: `boolean`):

When scraping a user timeline (usernames), also include the user's replies to other people, not just their own posts.

## `includeSearchTerms` (type: `boolean`):

When using searchTerms, add a 'searchTerm' field to each returned tweet showing which query produced it. Useful when searching several terms in one run.

## `proxyConfiguration` (type: `object`):

Proxy settings. The default Apify datacenter proxy is enough for most requests and keeps cost low; enable residential only if you hit blocks. Leave as default unless you know you need otherwise.

## Actor input object example

```json
{
  "searchMode": "Latest",
  "usernames": [
    "nasa"
  ],
  "maxItems": 100,
  "includeReplies": false,
  "includeSearchTerms": false,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "usernames": [
        "nasa"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("jacquemus/x-tweet-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "usernames": ["nasa"] }

# Run the Actor and wait for it to finish
run = client.actor("jacquemus/x-tweet-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "usernames": [
    "nasa"
  ]
}' |
apify call jacquemus/x-tweet-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,jacquemus/x-tweet-scraper"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/uL0DbGWGkDHb7VAlK/builds/eLejx6ddbuhccV7ak/openapi.json