# X / Twitter User scraper (`simoit/x-twitter-user-scrapper`) Actor

Understand X accounts beyond tweets with profile data and optional relationship mapping.

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

## Pricing

from $0.15 / 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.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## User Scraper

![SIMO IT logo](https://simoit.tech/favicon.ico)

Discover X users and understand accounts beyond tweets with profile data, followers, or following data for research, outreach, and audience analysis.

### New: search for X users

You can now discover X accounts even when you do not know their exact handles. Select the `search` input type and enter a name, handle fragment, brand, role, or keyword in `searchQuery`. The Actor returns matching user profiles with fields such as username, display name, bio, profile URL, verification status, and audience counts.

This makes the User Scraper useful for:

- finding a person from a partial name, such as `elon`
- discovering creators, experts, founders, or brands in a niche
- building prospect and influencer lists from keywords
- finding the correct account before collecting its followers or following

Search mode supports pagination through `page` and `maxPages`, page size through `limit`, and a total result cap through `maxItems`.

### About SIMO IT

SIMO IT provides actionable scraping solutions that convert social graph data into growth and research signals.

### Features

- collect profile data for one or many X handles
- search X users by name, handle, or keyword
- fetch only followers as a flat dataset
- fetch only following as a flat dataset
- analyze network overlap and relationship patterns
- build lead lists and influencer maps

### Use cases

- account research before outreach and partnerships
- audience and community analysis
- profile segmentation for sales and marketing campaigns

### Output

Choose one output mode per run: exact user profiles, user search results, followers, or following.

### How to use

1. Open the Actor on Apify.
2. Provide `handles`/`userUrls`, or enter `searchQuery` in search mode.
3. Choose whether you want `users`, `search`, `followers`, or `following`.
4. Configure pagination and run the Actor.

No technical setup is required from your side. Backend infrastructure is managed by SIMO IT.

Pricing note: profile lookup pricing was updated because fetching a single profile still requires a full backend/X request, even though it usually returns only one dataset row. The previous row-based price underpriced profile-only runs and could fall below the real infrastructure and runtime cost. Profile lookups, follower pages, and following pages are now tracked separately so pricing can better reflect the actual work performed.

Need a custom plan, custom limits, or a tailored data workflow? Contact `contact@simoit.tech`.

### Related Actors

- Need tweet content instead of account metadata? Use [Tweet Scraper](https://apify.com/simoit/x-twitter-search-tweets-scrapper).
- Need posts from one selected profile? Use [Profile Scraper](https://apify.com/simoit/x-twitter-profile-scrapper).
- Need list-based monitoring across curated sources? Use [List Scraper](https://apify.com/simoit/x-twitter-list-scraper).
- Need trend discovery before mapping who matters in a topic? Use [Trends Scraper](https://apify.com/simoit/x-twitter-preset-trends-scrapper) or [Global Trending Scraper](https://apify.com/simoit/x-twitter-trends-scrapper).

### Input

- `inputTargetType` (string, optional, default: `users`): Output mode.
  - `users`: return profile records
  - `search`: search X accounts and return matching profile records
  - `followers`: return follower records for each source handle
  - `following`: return following records for each source handle
- `handles` (string, conditionally required): X usernames (without `@`), comma-separated or new lines.
- `userUrls` (string, optional): X/Twitter profile URLs (comma-separated or new lines).
- `searchQuery` (string, conditionally required): Search text used when `inputTargetType` is `search`.
- `page` (integer, optional, default: `1`): Starting page number.
- `limit` (integer, optional, default: `20`, max: `100`): Records per page.
- `maxPages` (integer, optional, default: `1`): Number of pages to fetch starting from `page`. Example: `page=2` and `maxPages=3` fetches pages `2..4`.
- `maxItems` (integer, optional): Maximum profile records in search mode.
- `followersMaxItems` (integer, optional): Maximum followers per handle.
- `followingMaxItems` (integer, optional): Maximum following per handle.

#### Filters and pagination

- user target: `handles`, `userUrls`, or `searchQuery`
- output mode: `inputTargetType`
- page controls (search/followers/following): `page`, `limit`, `maxPages`
- output caps: `maxItems`, `followersMaxItems`, `followingMaxItems`

#### Example input

```json
{
  "inputTargetType": "followers",
  "userUrls": "https://x.com/openai, https://twitter.com/apify",
  "limit": 20,
  "followersMaxItems": 100
}
```

#### Search users example

```json
{
  "inputTargetType": "search",
  "searchQuery": "elon",
  "limit": 20,
  "maxPages": 1,
  "maxItems": 20
}
```

The example above returns matching accounts such as `elonmusk`. Search results use the same `user` profile structure as exact profile lookups:

```json
{
  "search_query": "elon",
  "handle": "elonmusk",
  "user": {
    "id_str": "44196397",
    "username": "elonmusk",
    "displayname": "Elon Musk",
    "url": "https://x.com/elonmusk"
  }
}
```

#### Example output

```json
{
  "source_handle": "openai",
  "source_user_id": 4398626122,
  "relationship": "follower",
  "user": {
    "id": 12345,
    "username": "example_follower",
    "displayname": "Example Follower"
  }
}
```

### FAQ

**Do I need my own backend or API setup?**\
No. This Actor is ready to run on Apify, and backend infrastructure is managed by SIMO IT.

**Can I run multiple handles in one job?**\
Yes. Pass multiple usernames in `handles` as comma-separated or newline-separated text.

**What is the difference between `users` and `search`?**

Use `users` when you already know the exact handles or profile URLs. Use `search` when you want to discover matching accounts from a name, partial handle, brand, or keyword.

**Will this return followers and following by default?**\
No. The default mode is `users`. Switch `inputTargetType` to `followers` or `following`.

# Actor input Schema

## `inputTargetType` (type: `string`):

Choose whether to fetch exact profiles, search for users, or collect followers/following.

## `searchQuery` (type: `string`):

Text used to search X users when the selected target type is Search users. Example: elon.

## `handles` (type: `string`):

X usernames without @ (comma-separated or new lines).

## `userUrls` (type: `string`):

Optional x.com/twitter.com user profile URLs (comma-separated or new lines).

## `page` (type: `integer`):

Starting page number.

## `limit` (type: `integer`):

Items per page.

## `maxPages` (type: `integer`):

Number of pages to fetch starting from Page. Example: page=2 and maxPages=3 fetches pages 2..4.

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

Maximum user records returned in Search users mode.

## `followersMaxItems` (type: `integer`):

Maximum followers per handle.

## `followingMaxItems` (type: `integer`):

Maximum following per handle.

## Actor input object example

```json
{
  "inputTargetType": "users",
  "handles": "openai",
  "page": 1,
  "limit": 20,
  "maxPages": 1
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `runReport` (type: `string`):

No description

## `userErrorReport` (type: `string`):

No description

# 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 = {
    "inputTargetType": "users",
    "handles": "openai"
};

// Run the Actor and wait for it to finish
const run = await client.actor("simoit/x-twitter-user-scrapper").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 = {
    "inputTargetType": "users",
    "handles": "openai",
}

# Run the Actor and wait for it to finish
run = client.actor("simoit/x-twitter-user-scrapper").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 '{
  "inputTargetType": "users",
  "handles": "openai"
}' |
apify call simoit/x-twitter-user-scrapper --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

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