# X (Twitter) Follower Scraper | $0.15/1K | Pay-Per Result (`xquik/x-follower-scraper`) Actor Scrape X (Twitter) followers, following, verified followers, list members & list subscribers for $0.15 per 1,000 profiles. Filter by follower count, verification, bio keyword, or location before you pay. No X API key. No rate limits. No mock data. Built by Xquik. - **URL**: https://apify.com/xquik/x-follower-scraper.md - **Developed by:** [Xquik](https://apify.com/xquik) (community) - **Categories:** Social media, Lead generation, Developer tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: 5.00 out of 5 stars ## Pricing from $0.15 / 1,000 followers 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 a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use 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 Scrape X (Twitter) **followers**, **following**, **verified followers**, **list members**, **list subscribers** and **community members** at scale for just **$0.15 per 1,000 profiles**. No X API key needed, no rate limits, no login required. Built by [Xquik](https://xquik.com). ### What does X Follower Scraper do? X Follower Scraper extracts complete profile data for the followers, following, list members, list subscribers and community members of any public X (formerly Twitter) account. It returns structured JSON ready for audience analysis, lead generation, competitor research, or integration into your pipeline. #### What can this scraper do? - **Scrape X followers** - paste a profile URL like `https://x.com/nasa/followers` and export every follower profile - **Scrape X following** - paste `https://x.com/nasa/following` to export every account a user follows - **Scrape X verified followers only** - paste `https://x.com/nasa/verified_followers` to target only Premium / verified accounts - **Scrape X list members** - paste a list URL like `https://x.com/i/lists/1748648376080666720/members` to export everyone on the list - **Scrape X list subscribers** - export users who follow a list via `https://x.com/i/lists//followers` - **Scrape X community members** - export members of any public X Community via `https://x.com/i/communities//members` - **Bulk X profile follower scraper** - pass an array of handles like `["elonmusk", "nasa"]` and scrape many targets in one run - **Server-side filters** - apply `minFollowers`, `verifiedOnly`, `bioContains`, `locationContains` filters on our side so you only pay for profiles that match - **Dedup across targets** - for overlap analysis between competitors or lists - **Per-target attribution** - every row carries `sourceTarget`, `sourceRelation` and `sourceUrl` so you always know where a profile came from #### What data can X Follower Scraper extract? | Field | Description | | ----------------- | ------------------------------------------------------- | | `id` | Numeric X user ID | | `username` | Handle (without `@`) | | `name` | Display name | | `description` | Bio text | | `followers` | Follower count | | `following` | Following count | | `statusesCount` | Total tweets posted | | `mediaCount` | Total media uploaded | | `favouritesCount` | Total likes given | | `verified` | Verified (Premium) flag | | `verifiedType` | `blue`, `business`, `government`, or `none` | | `location` | Self-reported location | | `url` | Website URL from profile | | `profilePicture` | Avatar URL (full-size) | | `coverPicture` | Banner URL | | `createdAt` | Account creation timestamp (ISO 8601) | | `canDm` | Whether the account accepts DMs | | `sourceTarget` | Handle / ID you scraped this profile from | | `sourceRelation` | Relation: `followers`, `following`, `list_members`, ... | | `sourceUrl` | Exact URL the profile was discovered on | Set `outputMode: "full"` to also get every raw field from the profile payload (entities, pinned tweet, professional info, affiliates, etc.) alongside the compact fields above. ### Why scrape X followers? - **Lead generation** - pull the followers of a competitor or niche influencer and build a targeted outreach list - **Audience analysis** - understand who follows you vs a competitor, spot overlap, find lookalike prospects - **Influencer discovery** - filter followers by `minFollowers` and `verifiedOnly` to surface the most influential people in any community - **Competitor research** - export a rival brand's follower base, segment by bio keyword, location, or engagement proxies - **Community research** - export the members of any X Community for academic, market, or product research - **List auditing** - verify who is on a curated X list and how the list has grown - **Retargeting seeds** - build follower-based audiences for downstream ad, email, or outreach campaigns - **Academic research** - build social-network datasets for trend analysis, NLP training, or sociological study All runs on **Apify's platform** with built-in scheduling, webhooks, API access, integrations (Make, n8n, Zapier), proxy rotation, and dataset export in JSON, CSV, Excel, or HTML. ### How much does it cost to scrape X followers? | Profiles | Cost | | --------- | ------ | | 1,000 | $0.15 | | 10,000 | $1.50 | | 100,000 | $15.00 | | 1,000,000 | $150 | You pay for rows written to your dataset at $0.15 per 1,000 rows. No subscriptions, no hidden fees, no start fee. Platform usage is included. - **Never charged for filtered-out profiles.** Server-side filters (`minFollowers`, `verifiedOnly`, `bioContains`, `locationContains`, `minAccountAgeDays`, `hasWebsite`, `hasLocation`) run **before** a profile enters your dataset. - **Never charged for duplicates.** When `dedupeAcrossTargets: true`, repeats are dropped before the dataset write. - **Never charged for data not delivered.** On timeout or hard failure, already-fetched profiles are flushed and the run exits cleanly; anything the Actor never pushed, you never pay for. - **One diagnostic row per empty run.** When a run produces no profiles (no input, invalid handles, or zero matches after filters), the actor writes a single structured row that explains why, so you always know what happened. This costs $0.00015 per empty run on paid plans (one-fifteen-thousandth of a cent). Diagnostic rows carry a `status` field (`no-input`, `invalid-input`, or `zero-output`) and are easy to filter out with `dataset.filter(r => !r.status)`. Set `ACTOR_MAX_TOTAL_CHARGE_USD` in Apify run options to hard-cap spend. The Actor respects it strictly. ### How do I use X Follower Scraper to scrape follower data? #### 1. Paste profile or list URLs Paste any mix of profile, list, or community URLs and the scraper routes each to the correct endpoint automatically: ```json { "startUrls": [ "https://x.com/nasa/followers", "https://x.com/spacex/verified_followers", "https://x.com/elonmusk/following", "https://x.com/i/lists/1748648376080666720/members", "https://x.com/i/communities/1493446837214187523/members" ], "maxItems": 5000 } ```` #### 2. Bulk handles Shorthand for many `//followers` targets. Usernames accept `@` or no prefix: ```json { "twitterHandles": ["elonmusk", "nasa", "openai"], "relation": "followers", "maxItems": 1000 } ``` Set `relation` to `followers`, `following`, or `verified_followers` to switch what is scraped for every handle. #### 3. Scrape by numeric user, list, or community IDs ```json { "userIds": ["44196397"], "listIds": ["1748648376080666720"], "communityIds": ["1493446837214187523"], "relation": "followers", "maxItems": 2000 } ``` #### 4. Filter before you pay Apply server-side filters so only matching profiles enter your dataset: ```json { "twitterHandles": ["openai"], "relation": "followers", "minFollowers": 1000, "verifiedOnly": true, "bioContains": "founder", "locationContains": "San Francisco", "maxItems": 500 } ``` Raw profiles fetched may be 10-100x more than rows billed - you only pay for the rows that pass every filter. #### Accepted URL shapes | URL | Relation | | ------------------------------------------- | --------------------------------------- | | `https://x.com//followers` | `followers` | | `https://x.com//verified_followers` | `verified_followers` | | `https://x.com//following` | `following` | | `https://x.com/` | default `relation` (followers if unset) | | `https://x.com/i/lists//members` | `list_members` | | `https://x.com/i/lists//followers` | `list_followers` | | `https://x.com/i/lists/` | `list_members` | | `https://x.com/i/communities//members` | `community_members` | | `https://x.com/i/communities/` | `community_members` | `twitter.com` and `mobile.twitter.com` are also accepted everywhere. ### Input See the **Input** tab for the complete list of options. All fields are optional except at least one of: `startUrls`, `twitterHandles`, `userIds`, `listIds`, or `communityIds`. Common patterns: - **Competitor follower export** - add the competitor handle to `twitterHandles` with `relation: "followers"` - **Verified-only lead list** - paste `https://x.com//verified_followers` into Start URLs - **List audit** - paste the list URL into Start URLs - **Multi-account overlap** - add 2+ handles, set `dedupeAcrossTargets: true` to keep only shared followers ### Output Each profile is a JSON object. Compact mode (default) returns 17 normalized fields: ```json { "schemaVersion": 1, "_schema_version": 1, "id": "44196397", "username": "elonmusk", "name": "Elon Musk", "description": "...", "followers": 180000000, "following": 500, "statusesCount": 42000, "mediaCount": 3200, "favouritesCount": 120000, "verified": true, "verifiedType": "blue", "location": "...", "url": "https://...", "profilePicture": "https://...", "coverPicture": "https://...", "createdAt": "2009-06-02T20:12:29Z", "canDm": true, "sourceTarget": "nasa", "sourceRelation": "followers", "sourceUrl": "https://x.com/nasa/followers" } ``` Export as JSON, CSV, Excel, or HTML from the Apify dataset. ### Tips & advanced options - **Cut costs** - set `maxItems` and `maxItemsPerTarget` to the exact number you need. Extra profiles cost extra. - **Filter before you pay** - combine `minFollowers`, `verifiedOnly`, `bioContains`, `locationContains` to narrow the billed dataset. - **Dedup** - set `dedupeAcrossTargets: true` when scraping multiple competitor handles to get only unique profiles across all targets. - **Overlap analysis** - run two competitor handles with `dedupeAcrossTargets: false` to analyze shared vs unique audience in post-processing. - **Full profile payload** - set `outputMode: "full"` to get every raw field including pinned tweet, entities, professional, and affiliates. - **Real-time monitoring** - for ongoing monitoring of new followers, use the Xquik API webhooks. They cost less than repeated Actor runs for watch-style workloads. ### Use cases - **Lead generation** - export competitor followers and build targeted lists - **Audience research** - analyze who follows you, a competitor, or an influencer - **Influencer discovery** - filter by follower count and verification to find the most influential people in any niche - **Community growth** - export members of relevant X Communities for outreach - **Academic research** - build large-scale social-network datasets - **Marketing intelligence** - segment follower bases by bio keyword, location, or profile type ### Why X Follower Scraper vs other follower scrapers? | Feature | X Follower Scraper | Other top scrapers | | --------------------------------- | ------------------- | ------------------ | | Price per 1,000 profiles | **$0.15** | $0.10 to $5.00 | | Followers / following | Yes | Yes | | Verified followers (Premium-only) | Yes | Rare | | List members & list subscribers | Yes | Rare | | Community members | Yes | Rare | | Server-side filters | **Yes (7 filters)** | No | | Diagnostic row on empty runs | **Yes** | No (silent empty) | | Mix URLs, handles, IDs in one run | Yes | No | | Per-target attribution on rows | Yes | No | | Dedup across targets | Yes | No | | No X API key required | Yes | Yes | | Export JSON, CSV, Excel, HTML | Yes | Yes | | Part of full X automation suite | Yes (Xquik) | No | ### Is it legal to scrape X (Twitter) followers? Our Actors are ethical and do not extract any private user data, such as email addresses, gender, or location beyond what the user has chosen to publish. They only extract what the user has chosen to share publicly on X. We therefore believe that our Actors, when used for ethical purposes by Apify users, are safe. However, you should be aware that your results could contain personal data. Personal data is protected by the GDPR in the European Union and by other regulations around the world. You should not scrape personal data unless you have a legitimate reason to do so. If you're unsure whether your reason is legitimate, consult your lawyers. ### Related Actors - [X Tweet Scraper](https://apify.com/xquik/x-tweet-scraper) - scrape tweets, engagement metrics, author profiles, and media with 40+ advanced search filters at $0.15 per 1,000 tweets *** If this scraper saves you time, a short review on the Apify Store helps other users find it. Thanks! *** ### Need more than scraping? Xquik is a full X automation platform with 40+ tools, a REST API, webhooks, and an MCP server for AI agents. - [API Documentation](https://docs.xquik.com/introduction) - full REST API with 70+ endpoints - [Followers API](https://docs.xquik.com/api-reference/x/followers) - the endpoint powering this Actor - [Following API](https://docs.xquik.com/api-reference/x/following) - get who a user follows - [List Members API](https://docs.xquik.com/api-reference/x/list-members) - export any X list - [MCP Server](https://docs.xquik.com/mcp/overview) - connect X data to AI agents (Claude, GPT, etc.) - [Webhooks](https://docs.xquik.com/webhooks/overview) - real-time event delivery for new followers / unfollows - [GitHub](https://github.com/Xquik-dev/x-twitter-scraper) - source code and issue tracker ### FAQ **Do I need a Twitter/X API key?** No. This scraper uses its own infrastructure. No login or credentials required. **Is there a rate limit?** No. Scrape as many profiles as you need. **How fast is it?** Typically 20-50 profiles per second depending on account size and filter settings. **Why is my run returning fewer rows than `maxItems`?** Because server-side filters (`minFollowers`, `verifiedOnly`, `bioContains`, etc.) are applied before counting. Raw profiles fetched may be 10-100x more than rows pushed. Relax filters if you want more results. **How many followers can I scrape from a single account?** Large accounts (millions of followers) can be scraped, but X paginates in batches. Use `maxItemsPerTarget` to chunk very large targets across multiple runs. **Does the Actor retry on 429 / Cloudflare / timeout?** Yes. 3 attempts per page with exponential backoff. Partial results are preserved on hard failures. **What happens if the run hits the Apify timeout?** The Actor detects it 15 seconds early, flushes everything already fetched, and exits cleanly with a `Partial: ...` status message. You are never billed for data not delivered. **Can I resume where I left off?** Not yet. Coming in a future version via `sinceCursor`. For now, use `maxItemsPerTarget` to chunk large runs. **Can I use the Apify API to run this?** Yes. See the [API tab](https://apify.com/xquik/x-follower-scraper/api) for integration examples in Python, JavaScript, cURL, and more. **Can I schedule recurring scrapes?** Yes. Use Apify's built-in [scheduling](https://docs.apify.com/platform/schedules) to run this Actor on a cron and watch for new followers over time. **Where do I report issues?** Open an issue on [GitHub](https://github.com/Xquik-dev/x-twitter-scraper/issues) or use the Issues tab on this Actor's page. Most issues are answered within 4 hours. **Can I get a custom solution?** Yes. Visit [xquik.com](https://xquik.com) or check the [API docs](https://docs.xquik.com/introduction) for direct API access with more endpoints and features. # Actor input Schema ## `startUrls` (type: `array`): X URLs to scrape. Supports profile relation URLs (/followers, /verified\_followers, /following), list URLs (/lists/ID/members, /lists/ID/followers) and community URLs (/communities/ID/members). Mix freely. ## `twitterHandles` (type: `array`): X usernames to scrape (with or without @). Use together with the Relation field below to decide what to pull. Example: elonmusk, @nasa ## `userIds` (type: `array`): Numeric X user IDs. Faster than handles when you already have IDs. Use with the Relation field. ## `listIds` (type: `array`): Numeric X list IDs. Use with Relation field set to list\_members or list\_followers. ## `communityIds` (type: `array`): Numeric X community IDs. Use with Relation field set to community\_members. ## `relation` (type: `string`): Which relation to scrape for each handle / user ID / list ID / community ID. URLs in Start URLs always override this field. ## `maxItems` (type: `integer`): Maximum users to return across the entire run. Price: $0.15 per 1,000 users. No per-target minimum. Set to 5 for testing, 10000+ for bulk. ## `maxItemsPerTarget` (type: `integer`): Optional cap per target. Leave empty to let maxItems run across all targets freely. Useful when scraping many targets and you want fairness. ## `outputMode` (type: `string`): compact returns 17 normalized profile fields plus source metadata (recommended). full adds raw profile entities, pinned tweet, and professional data. ## `includeTargetMetadata` (type: `boolean`): Attach sourceTarget, sourceRelation, and sourceUrl on every row. Critical when scraping multiple targets in one run. ## `dedupeAcrossTargets` (type: `boolean`): When true, a user appearing in multiple targets is returned only once (first target wins). Useful for follower-overlap analysis. ## `minFollowers` (type: `integer`): Only include users with at least this many followers. ## `maxFollowers` (type: `integer`): Only include users with at most this many followers. Useful to exclude celebrities from a follower list. ## `minAccountAgeDays` (type: `integer`): Only include users whose account is at least this many days old. Good anti-bot signal. ## `verifiedOnly` (type: `boolean`): Only include verified (X Premium / Blue) accounts. ## `hasWebsite` (type: `boolean`): Only include users who list a website in their profile. ## `hasLocation` (type: `boolean`): Only include users who list a location in their profile. ## `bioContains` (type: `string`): Only include users whose bio contains this text (case-insensitive). Example: founder, CEO, engineer. ## `locationContains` (type: `string`): Only include users whose location contains this text (case-insensitive). Example: New York, London, Tokyo. ## Actor input object example ```json { "startUrls": [ { "url": "https://x.com/elonmusk/followers" }, { "url": "https://x.com/nasa/verified_followers" } ], "twitterHandles": [ "elonmusk", "@nasa" ], "userIds": [ "44196397" ], "listIds": [ "1442216750565797889" ], "communityIds": [ "1493446837214187523" ], "relation": "followers", "maxItems": 100, "outputMode": "compact", "includeTargetMetadata": true, "dedupeAcrossTargets": false, "minFollowers": 1000, "verifiedOnly": false, "hasWebsite": false, "hasLocation": false, "bioContains": "founder", "locationContains": "New York" } ``` # Actor output Schema ## `users` (type: `string`): Scraped users dataset. ## `runReport` (type: `string`): JSON summary: configuration, per-target results, anomaly counts, duration, outcome. # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "startUrls": [ { "url": "https://x.com/elonmusk/followers" }, { "url": "https://x.com/nasa/verified_followers" } ], "maxItems": 100, "minFollowers": 1000 }; // Run the Actor and wait for it to finish const run = await client.actor("xquik/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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "startUrls": [ { "url": "https://x.com/elonmusk/followers" }, { "url": "https://x.com/nasa/verified_followers" }, ], "maxItems": 100, "minFollowers": 1000, } # Run the Actor and wait for it to finish run = client.actor("xquik/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 '{ "startUrls": [ { "url": "https://x.com/elonmusk/followers" }, { "url": "https://x.com/nasa/verified_followers" } ], "maxItems": 100, "minFollowers": 1000 }' | apify call xquik/x-follower-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=xquik/x-follower-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "X (Twitter) Follower Scraper | $0.15/1K | Pay-Per Result", "description": "Scrape X (Twitter) followers, following, verified followers, list members & list subscribers for $0.15 per 1,000 profiles. Filter by follower count, verification, bio keyword, or location before you pay. No X API key. No rate limits. No mock data. Built by Xquik.", "version": "1.0", "x-build-id": "4ex4VzQbV7ONXJ2dr" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/xquik~x-follower-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-xquik-x-follower-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/xquik~x-follower-scraper/runs": { "post": { "operationId": "runs-sync-xquik-x-follower-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/xquik~x-follower-scraper/run-sync": { "post": { "operationId": "run-sync-xquik-x-follower-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "startUrls": { "title": "Start URLs", "type": "array", "description": "X URLs to scrape. Supports profile relation URLs (/followers, /verified_followers, /following), list URLs (/lists/ID/members, /lists/ID/followers) and community URLs (/communities/ID/members). Mix freely.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "twitterHandles": { "title": "Twitter Handles", "type": "array", "description": "X usernames to scrape (with or without @). Use together with the Relation field below to decide what to pull. Example: elonmusk, @nasa", "items": { "type": "string" } }, "userIds": { "title": "Numeric User IDs", "type": "array", "description": "Numeric X user IDs. Faster than handles when you already have IDs. Use with the Relation field.", "items": { "type": "string" } }, "listIds": { "title": "List IDs", "type": "array", "description": "Numeric X list IDs. Use with Relation field set to list_members or list_followers.", "items": { "type": "string" } }, "communityIds": { "title": "Community IDs", "type": "array", "description": "Numeric X community IDs. Use with Relation field set to community_members.", "items": { "type": "string" } }, "relation": { "title": "Relation", "enum": [ "followers", "following", "verified_followers", "list_members", "list_followers", "community_members" ], "type": "string", "description": "Which relation to scrape for each handle / user ID / list ID / community ID. URLs in Start URLs always override this field.", "default": "followers" }, "maxItems": { "title": "Max Items", "minimum": 1, "maximum": 10000000, "type": "integer", "description": "Maximum users to return across the entire run. Price: $0.15 per 1,000 users. No per-target minimum. Set to 5 for testing, 10000+ for bulk.", "default": 200 }, "maxItemsPerTarget": { "title": "Max Items Per Target", "minimum": 1, "maximum": 10000000, "type": "integer", "description": "Optional cap per target. Leave empty to let maxItems run across all targets freely. Useful when scraping many targets and you want fairness." }, "outputMode": { "title": "Output Mode", "enum": [ "compact", "full" ], "type": "string", "description": "compact returns 17 normalized profile fields plus source metadata (recommended). full adds raw profile entities, pinned tweet, and professional data.", "default": "compact" }, "includeTargetMetadata": { "title": "Tag With Source Target", "type": "boolean", "description": "Attach sourceTarget, sourceRelation, and sourceUrl on every row. Critical when scraping multiple targets in one run.", "default": true }, "dedupeAcrossTargets": { "title": "Deduplicate Across Targets", "type": "boolean", "description": "When true, a user appearing in multiple targets is returned only once (first target wins). Useful for follower-overlap analysis.", "default": false }, "minFollowers": { "title": "Minimum Followers", "minimum": 0, "type": "integer", "description": "Only include users with at least this many followers." }, "maxFollowers": { "title": "Maximum Followers", "minimum": 0, "type": "integer", "description": "Only include users with at most this many followers. Useful to exclude celebrities from a follower list." }, "minAccountAgeDays": { "title": "Minimum Account Age (days)", "minimum": 0, "type": "integer", "description": "Only include users whose account is at least this many days old. Good anti-bot signal." }, "verifiedOnly": { "title": "Verified Only", "type": "boolean", "description": "Only include verified (X Premium / Blue) accounts.", "default": false }, "hasWebsite": { "title": "Has Website", "type": "boolean", "description": "Only include users who list a website in their profile.", "default": false }, "hasLocation": { "title": "Has Location", "type": "boolean", "description": "Only include users who list a location in their profile.", "default": false }, "bioContains": { "title": "Bio Contains", "type": "string", "description": "Only include users whose bio contains this text (case-insensitive). Example: founder, CEO, engineer." }, "locationContains": { "title": "Location Contains", "type": "string", "description": "Only include users whose location contains this text (case-insensitive). Example: New York, London, Tokyo." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```