# 🐦 Twitter (X) User Scraper (`scraper-engine/twitter-x-user-scraper`) Actor

- **URL**: https://apify.com/scraper-engine/twitter-x-user-scraper.md
- **Developed by:** [Scraper Engine](https://apify.com/scraper-engine) (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 $4.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) User Scraper

Scrape **public Twitter / X user profiles, followers, following counts and
retweeter networks** at scale — no login or API key required. Powered by the
Apify platform with built-in auto proxy escalation, live result streaming and
a smart fallback strategy for blocked requests.

> ⚡ Get clean, structured user data straight from `x.com` — verified status,
> follower/following counts, bio, location, account age, profile pictures,
> banners, professional badges, and an enriched `about` payload.

***

### ✨ Why this actor

| | Other scrapers | 🐦 This actor |
|---|---|---|
| Login required | Often | ❌ Never (optional) |
| Block handling | Manual | ✅ Auto direct → datacenter → residential |
| Live results | ❌ End-of-run only | ✅ Streamed per-user |
| Pricing | Subscription | 💸 Pay-per-event |
| Outputs | Single dataset | 📦 Dataset + per-section KVS files |

***

### 🚀 Key features

- 🔗 **Bulk URLs** — paste a list of profile URLs or plain usernames.
- 🌐 **No-proxy by default** — automatically escalates to Apify DATACENTER then
  RESIDENTIAL proxies (with 3 retries) only when X blocks the connection.
- 📡 **Live streaming** — every captured user is pushed to the dataset
  immediately, so a crash mid-run never wipes your progress.
- 🪪 **Rich profile mode** — toggle `🪪 Include rich 'about' profile` to fetch
  verification info, profile image shape, account creation source, etc.
- 👻 **Unavailable users** — optionally surface suspended / protected accounts.
- 📚 **Per-section output** — each input URL writes its own grouped JSON file
  to the run’s key-value store, plus a combined `OUTPUT` key.

***

### 📥 Input

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| 🔗 `startUrls` | array | – | Profile URLs or `@usernames`. Bulk supported. |
| 🔁 `getRetweeters` | bool | `true` | Capture retweeters / related users from the timeline. |
| 👥 `getFollowers` | bool | `true` | Include follower count on each record. |
| 🤝 `getFollowing` | bool | `true` | Include friends (following) count. |
| 🪪 `getAbout` | bool | `true` | Enrich with verification / account metadata. |
| 👻 `includeUnavailableUsers` | bool | `false` | Surface suspended / protected accounts. |
| 🎯 `maxItems` | int | `100` | Cap users collected per source URL. |
| ⏱️ `requestDelay` | number | `1.0` | Float seconds between pagination requests. |
| 🔐 `authToken` | string (secret) | – | Optional X `auth_token` cookie. |
| 🛡️ `csrfToken` | string (secret) | – | Optional X `ct0` cookie. |
| 🌐 `proxyConfiguration` | object | direct | Defaults to no proxy. Overrides auto-escalation. |

#### Example input

```json
{
  "startUrls": [
    "https://twitter.com/elonmusk",
    "https://x.com/openai"
  ],
  "getRetweeters": true,
  "getFollowers": true,
  "getFollowing": true,
  "getAbout": true,
  "includeUnavailableUsers": false,
  "maxItems": 100,
  "requestDelay": 1.0,
  "proxyConfiguration": { "useApifyProxy": false }
}
```

***

### 📤 Output

Each record is pushed live to the default dataset.

```json
{
  "inputSource": "https://twitter.com/elonmusk",
  "type": "user",
  "userName": "elonmusk",
  "url": "https://x.com/elonmusk",
  "twitterUrl": "https://twitter.com/elonmusk",
  "id": "44196397",
  "name": "Elon Musk",
  "isVerified": true,
  "hasNftAvatar": false,
  "profilePicture": "https://pbs.twimg.com/profile_images/.../m8mdWZCG_normal.jpg",
  "coverPicture": "https://pbs.twimg.com/profile_banners/44196397/1774145451",
  "description": "https://t.co/dDtDyVssfm",
  "location": "",
  "followers": 239969983,
  "following": 1332,
  "protected": false,
  "createdAt": "Tue Jun 02 20:12:29 +0000 2009",
  "statusesCount": 102639,
  "mediaCount": 4489,
  "favouritesCount": 227779,
  "listedCount": 169028,
  "about": {
    "accountBasedIn": "",
    "locationAccurate": false,
    "profileImageShape": "Circle",
    "avatarUrl": "https://pbs.twimg.com/profile_images/.../m8mdWZCG_normal.jpg",
    "usernameChangeCount": "0",
    "accountCreatedAt": "Tue Jun 02 20:12:29 +0000 2009",
    "accountSource": "",
    "verifiedSince": "-156836000000000"
  }
}
```

The run also writes a **per-section JSON** to the key-value store
(`source_01_elonmusk.json`, `source_02_openai.json`, …) and a combined
`OUTPUT.json` that mirrors the legacy grouped-by-name format.

***

### 🚀 How to use (Apify Console)

1. Log in at <https://console.apify.com> → **Actors**.
2. Open **🐦 Twitter (X) User Scraper**.
3. Paste your profile URLs into **🔗 Profile URLs**.
4. Pick which networks / fields you want (`🔁`, `👥`, `🤝`, `🪪`).
5. (Optional) Drop in an `authToken` + `csrfToken` for tougher targets.
6. Hit **Start**.
7. Watch the live log — it will tick `📥 @username — N followers` per user.
8. Open the **Dataset** or **Key-value store** tab when the run completes.
9. Export to JSON / CSV / XLSX.

***

### 🤖 Use via API

```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 '{
       "startUrls": ["https://twitter.com/elonmusk"],
       "maxItems": 50
     }'
```

***

### 🎯 Best use cases

- 🧠 **Audience research** — analyze who is engaging with a brand or person.
- 📈 **Influencer discovery** — find creators by exploring a competitor's
  retweeter / quoter graph.
- 🏷️ **Lead generation** — extract bios and external links from prospects.
- 🛡️ **Brand safety** — monitor verified status changes on managed accounts.

***

### 💸 Pricing

This actor uses Apify's **pay-per-event (PPE)** model:

| Event | When it fires |
|-------|---------------|
| `apify-actor-start` | Once at run start (synthetic; Apify covers the first 5s). |
| `row_result` | **One charge per user record written to the default dataset.** |

- **No data → no charge.** If a source fails or returns nothing, no `row_result`
  events are emitted, so you are not billed for empty runs.
- Skipped unavailable users and the per-section KVS mirror copies are **not**
  chargeable events — only successful default-dataset writes are.
- When your spend cap (`ACTOR_MAX_TOTAL_CHARGE_USD`) is reached, the actor
  stops pushing further items and exits cleanly — never with a failed-run.

Configure the `row_result` event's USD price (and any tiered discounts) in
**Apify Console → Actor → Publication → Monetization**.

***

### ❓ FAQ

**Do I need an X account?**
No. The actor runs in guest mode out of the box. You can paste an
`auth_token` + `ct0` for harder cases — both stay encrypted in Apify Secrets.

**Why does the first run take a few seconds?**
The actor warms up by fetching the X web client bundle so it can stay in sync
with the latest GraphQL schema. After that, throughput is steady.

**How do you handle rate limits?**
On a block we escalate proxies (`direct → datacenter → residential`) and
rotate residential IPs up to three times before failing the source.

**Will protected / suspended accounts appear?**
Only if you enable `👻 includeUnavailableUsers`. They are tagged with
`isUnavailable: true` and an `unavailableReason`.

***

### 🛟 Support & feedback

- 🐞 Issues — open a ticket on the Apify Store actor page.
- 💬 Questions / feature requests — ping the maintainer via Apify chat.

***

### ⚖️ Legal

Data is collected only from **publicly available** profile information.
End users are responsible for compliance with applicable laws (GDPR, CCPA),
the [X Terms of Service](https://x.com/en/tos) and `robots.txt`.

***

*Built with ❤️ for the Apify platform.*

# Actor input Schema

## `startUrls` (type: `array`):

List one or more X / Twitter profile URLs. Examples: `https://x.com/elonmusk`, `https://twitter.com/openai`. You can also paste plain usernames (e.g. `elonmusk`).

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

Maximum number of users to collect per input URL. Helps you stay inside your monetization budget.

## `authToken` (type: `string`):

Required. Paste your `auth_token` cookie from x.com. Open x.com in your browser → DevTools → Application → Cookies → copy the `auth_token` value.

## `csrfToken` (type: `string`):

Required. The `ct0` cookie from x.com that pairs with your `auth_token` — found beside it in DevTools → Application → Cookies.

## `getRetweeters` (type: `boolean`):

When enabled, also collect users surfaced from the profile's timeline (retweeters, mentions, quoted authors). Disable to scrape only the profile owner.

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

Include `followers` (follower count) in each output record.

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

Include `following` (friends count) in each output record.

## `getAbout` (type: `boolean`):

Enrich each user with verification info, profile image shape, account creation source, and other profile-only fields. Slightly slower because every user is re-fetched via the profile API.

## `includeUnavailableUsers` (type: `boolean`):

Include users that X marks as suspended / protected / deleted. They appear with `isUnavailable: true` and `unavailableReason`.

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

By default the actor goes direct (no proxy). If X blocks the request, it automatically falls back to Apify DATACENTER proxies, then to RESIDENTIAL (3 retries). Override here to force a specific proxy.

## Actor input object example

```json
{
  "startUrls": [
    "https://twitter.com/elonmusk"
  ],
  "maxItems": 10,
  "getRetweeters": true,
  "getFollowers": true,
  "getFollowing": true,
  "getAbout": false,
  "includeUnavailableUsers": false,
  "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 = {
    "startUrls": [
        "https://twitter.com/elonmusk"
    ],
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

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

# Run the Actor and wait for it to finish
run = client.actor("scraper-engine/twitter-x-user-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 '{
  "startUrls": [
    "https://twitter.com/elonmusk"
  ],
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call scraper-engine/twitter-x-user-scraper --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/YRbZp9ZAiUZ3YTTzA/builds/RI9hhLJhinaETDdlt/openapi.json