# 🐦 Twitter (X) Follower Scraper (`scrapeengine/twitter-x-follower-scraper`) Actor

Scrape Followers & Following lists of any public X (Twitter) profile in bulk. Returns rich, v1.1-compatible user records with pinned-tweet hydration, full bio, profile image, banner, verified badge and more — streamed live to the dataset.

- **URL**: https://apify.com/scrapeengine/twitter-x-follower-scraper.md
- **Developed by:** [ScrapeEngine](https://apify.com/scrapeengine) (community)
- **Categories:** Automation, Lead generation, Social media
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.99 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#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

## 🐦 Twitter (X) Follower & Following Scraper

> **Bulk-scrape Followers & Following lists of any public X (Twitter) profile — rich data, real-time output.**

Paste any number of X profile URLs (or @handles), choose to scrape **Followers**, **Following**, or both, and receive **v1.1-compatible user records** with full bio, profile image, banner, pinned tweet, verified badge, follower/following counts, and more — streamed live to the dataset so partial results are always preserved.

***

### ✨ Why Choose This Actor?

- ⚡ **Bulk input** — scrape dozens of profiles in a single run
- 🔄 **Both lists at once** — followers AND following in one go (toggleable)
- 📌 **Pinned-tweet hydration** — full pinned-tweet payload embedded in every record
- 🌐 **Smart auto proxy ladder** — direct → datacenter → residential, only escalates if blocked
- 💾 **Live results** — every user streams to the dataset the moment it's parsed
- 🛡️ **Anti-block resilient** — randomized delays, exponential backoff, sticky escalation
- 🎯 **v1.1-compatible output** — drop-in replacement for legacy Twitter API consumers

***

### 🔑 Key Features

| Feature | Description |
|---------|-------------|
| 🔗 **Bulk URLs / usernames** | One per line — accepts `x.com/elonmusk`, `twitter.com/elonmusk`, `@elonmusk`, or `elonmusk` |
| 👥 **Followers + ➡️ Following** | Toggle either or both per run |
| 🔢 **Per-list caps** | Hard cap with `maxFollowers` / `maxFollowings` |
| 📌 **Pinned tweets** | Auto-hydrated v1.1 status objects |
| 🌐 **Auto proxy fallback** | No proxy → Datacenter → Residential (3 retries) |
| 📡 **Real-time output** | Each user is pushed live to the dataset, grouped per-section via dataset views |
| ✅ **Verified flag, banner, avatar, bio** | Full profile metadata in every row |

***

### 📥 Input

```json
{
  "urls": [
    "https://x.com/elonmusk",
    "@sama"
  ],
  "getFollowers": true,
  "getFollowing": true,
  "maxFollowers": 200,
  "maxFollowings": 200,
  "auth_token": "YOUR_X_AUTH_TOKEN_COOKIE",
  "ct0": "YOUR_X_CT0_COOKIE",
  "proxyConfiguration": { "useApifyProxy": false }
}
```

| Field | Type | Description |
|-------|------|-------------|
| 🔗 `urls` | `array<string>` | **Required.** X profile URLs or @handles, one per item. |
| 👥 `getFollowers` | `boolean` | Scrape the Followers list. Default `true`. |
| ➡️ `getFollowing` | `boolean` | Scrape the Following list. Default `true`. |
| 🔢 `maxFollowers` | `integer` | Cap on followers per profile. Default `200`. |
| 🔢 `maxFollowings` | `integer` | Cap on followings per profile. Default `200`. |
| 🔑 `auth_token` | `string` | **Required.** Your X `auth_token` cookie (secret). |
| 🔑 `ct0` | `string` | **Required.** Your X `ct0` cookie (secret). |
| 🌐 `proxyConfiguration` | `object` | Optional. Override the auto proxy ladder. Default: **no proxy**. |

#### 🔐 How to find your `auth_token` and `ct0` cookies

1. Open https://x.com in your browser and log in.
2. Open **DevTools** → **Application** (Chrome) or **Storage** (Firefox) tab.
3. Expand **Cookies** → `https://x.com`.
4. Copy the `Value` of the `auth_token` row → paste into the input.
5. Copy the `Value` of the `ct0` row → paste into the input.
6. Both fields are marked `secret` — they never appear in run output.

***

### 📤 Output

Every row in the dataset is a v1.1-shaped user record carrying:

- `type` — either `"follower"` or `"following"`
- `target_username` — the profile whose list this row came from
- Full v1.1 user payload (followers\_count, friends\_count, verified, description, urls, profile\_image\_url\_https, profile\_banner\_url, …)
- `status` — embedded **pinned tweet** (v1.1 status object) when the user has one

Example:

```json
{
  "type": "follower",
  "target_username": "elonmusk",
  "id": 95092020,
  "id_str": "95092020",
  "name": "Dr Jordan B Peterson",
  "screen_name": "jordanbpeterson",
  "description": "Best-Selling Author | Clinical Psychologist | …",
  "url": "https://t.co/KgUEvmxeQD",
  "followers_count": 6182005,
  "friends_count": 1653,
  "statuses_count": 51533,
  "verified": false,
  "profile_image_url_https": "https://pbs.twimg.com/profile_images/.../TKBC60e1_normal.jpg",
  "profile_banner_url": "https://pbs.twimg.com/profile_banners/95092020/1768079001",
  "status": {
    "id_str": "1949912864271323255",
    "text": "The culmination of my life's work. …",
    "favorite_count": 10543,
    "retweet_count": 1312,
    "lang": "en"
  }
}
```

The output table has **three pre-built views** so each section is visible separately:

| View | Shows |
|------|-------|
| 📊 **All Scraped Users** | Mixed — both follower and following rows |
| 👥 **Followers Only** | Filter the table down to follower rows |
| ➡️ **Following Only** | Filter the table down to following rows |

You can also export the full dataset as **JSON / CSV / XLSX** from the Output tab.

***

### 🚀 How to Use (Apify Console)

1. Log in at https://console.apify.com → **Actors**.
2. Open **🐦 Twitter (X) Follower & Following Scraper**.
3. Paste your X profile URLs / @handles in the **URLs** field — one per line.
4. Toggle **Scrape Followers** / **Scrape Following** as needed.
5. Set the per-profile caps (defaults are 200 each).
6. Paste your **`auth_token`** and **`ct0`** cookies (see instructions above).
7. (Optional) Leave proxy as default — the actor escalates automatically if blocked.
8. Click **▶ Start**.
9. Watch logs in real time — every scraped user appears live in the Output tab.
10. Export the dataset to **JSON / CSV / XLSX** when the run completes.

***

### 🤖 Use via API

Run synchronously and get the dataset directly:

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/<ACTOR_ID>/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://x.com/elonmusk"],
    "getFollowers": true,
    "getFollowing": false,
    "maxFollowers": 100,
    "auth_token": "…",
    "ct0": "…"
  }'
```

Or asynchronously (returns a run ID — poll for status):

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/<ACTOR_ID>/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://x.com/sama"],"auth_token":"…","ct0":"…"}'
```

***

### 🌐 Proxy Strategy

The actor uses a **sticky tiered fallback**:

```
1. 🟢 Direct (no proxy)        ← start here
2. 🟡 Apify Datacenter Proxy   ← on first block
3. 🔴 Apify Residential Proxy  ← if datacenter blocked too (3 retries)
```

Once the actor escalates to a higher tier, it **stays there** for the rest of the run — no flapping. Every escalation is logged clearly so you can see exactly what happened.

***

### 🎯 Best Use Cases

- 📈 **Audience analysis** — who follows / is followed by influencers in your niche
- 🤝 **Lead generation** — pull a Following list of a target buyer persona
- 🔬 **Research & journalism** — map social graphs of public figures
- 🧠 **Competitive intelligence** — see who key competitors follow
- 📊 **Dataset enrichment** — feed v1.1-shaped user rows into existing pipelines

***

### 💰 Pricing (Pay-Per-Event)

| Event | What it covers |
|-------|---------------|
| `apify-actor-start` | One-time charge per run (covers startup) |
| `apify-default-dataset-item` | Charged per successfully pushed user record |

You only pay for **users we actually scrape** — failed lookups don't charge the per-item event.

***

### ❓ Frequently Asked Questions

**Q: Why do I need to provide `auth_token` and `ct0`?**
X's GraphQL endpoints for Followers/Following require an authenticated session. The actor cannot read these lists without your own logged-in cookies — there is no public anonymous endpoint.

**Q: Are my cookies safe?**
Both fields are marked `secret` in the input schema and never appear in logs or output. They live only inside the run sandbox and are discarded when the run ends. Still, use a throwaway account when possible.

**Q: How many followers can I scrape per profile?**
We've tested up to **5,000 per list**. X starts rate-limiting harder above that — increase patience (and/or add a residential proxy) if you push higher.

**Q: Will I get rate-limited?**
Possible on huge lists. The actor handles this gracefully — it slows down, retries, and escalates to datacenter / residential proxies automatically.

**Q: What if a profile is private or suspended?**
The lookup logs a warning and skips that profile — the rest continue normally.

**Q: Is this legal?**
The actor only reads publicly-listed followers/following on profiles your account can already see. You are responsible for downstream compliance with X's ToS, GDPR/CCPA, and any applicable anti-spam laws.

***

### ⚖️ Cautions / Legal

- Data is collected only from **publicly accessible** profiles.
- Do **not** use this to scrape private/protected accounts.
- The end user is responsible for legal compliance (GDPR, CCPA, target site ToS, anti-spam laws).
- Be respectful — keep per-profile caps reasonable.

***

### 💬 Support & Feedback

Issues, feature requests, or just want to chat? Open an issue on the actor's Apify page or contact the maintainer through your Apify Console messages.

# Actor input Schema

## `urls` (type: `array`):

Paste one URL/username per line. Accepts:
• `https://x.com/elonmusk`
• `https://twitter.com/elonmusk`
• `@elonmusk`
• `elonmusk`

⚠️ Ignored when **User ID List** is provided below.

## `user_ids` (type: `array`):

Enter the numeric X user IDs you want to scrape — one per line. Example: `1846987139428634858`.

💡 Use this when you already have user IDs (faster — skips the username lookup).

⚠️ **Note:** When this field has a value, all other URL/username inputs above will be ignored.

## `getFollowers` (type: `boolean`):

Collect the profile's **Followers** list.

## `getFollowing` (type: `boolean`):

Collect the profile's **Following** list.

## `maxFollowers` (type: `integer`):

Hard cap on how many followers to fetch per profile. Lower = faster & cheaper.

## `maxFollowings` (type: `integer`):

Hard cap on how many followings to fetch per profile.

## `auth_token` (type: `string`):

Your X (Twitter) `auth_token` cookie from a logged-in browser session. Required — X's Followers/Following GraphQL endpoints reject anonymous traffic.

👉 How to find it: open x.com → DevTools → Application → Cookies → copy the value of `auth_token`.

## `ct0` (type: `string`):

Your X (Twitter) `ct0` cookie from the same session as `auth_token`. Used as the `x-csrf-token` header.

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

Default = **no proxy**. If X blocks the run, the actor automatically escalates: Direct → Datacenter → Residential (3 retries on residential). Override only if you have a specific reason — the actor handles blocks for you.

## Actor input object example

```json
{
  "urls": [
    "https://x.com/elonmusk"
  ],
  "user_ids": [],
  "getFollowers": true,
  "getFollowing": true,
  "maxFollowers": 20,
  "maxFollowings": 20,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# 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 = {
    "urls": [
        "https://x.com/elonmusk"
    ],
    "user_ids": [],
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("scrapeengine/twitter-x-follower-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 = {
    "urls": ["https://x.com/elonmusk"],
    "user_ids": [],
    "proxyConfiguration": { "useApifyProxy": False },
}

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

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

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

```

## CLI example

```bash
echo '{
  "urls": [
    "https://x.com/elonmusk"
  ],
  "user_ids": [],
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call scrapeengine/twitter-x-follower-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=scrapeengine/twitter-x-follower-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

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