# X (Twitter) Lists – Scrape Tweets, Members & Manage Lists (`b2b_leads/x-lists-manager`) Actor Scrape and manage X (Twitter) Lists in one Actor. Export list tweets, members, followers & details as structured data, or create lists and add/remove members. Retweets expanded with real engagement. Filters, per-list caps & a request budget keep costs low. - **URL**: https://apify.com/b2b\_leads/x-lists-manager.md - **Developed by:** [Chidubem Aneke](https://apify.com/b2b_leads) (community) - **Categories:** Social media, Lead generation, MCP servers - **Stats:** 1 total users, 0 monthly users, 0.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. 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 ## X Lists Manager **One Actor for everything about X (Twitter) Lists — read them and manage them.** Pull a list's details, tweets, members, and followers as clean JSON, and create lists, add or remove members in bulk, and update or delete lists on your own account. No code, no glue scripts — just a form. Whether you're curating an audience, monitoring a competitor's list, generating leads, or cleaning up list membership at scale, this Actor does it in a single run. --- ### Why you'll like it - **Read + manage in one place.** Point it at any public list to extract data, or connect your account to change lists — or both in the same run. - **Batch everything.** Many lists in, many rows out. IDs and full `x.com/i/lists/...` URLs work in the same field. - **Effortless form.** Simple fields for the common case, optional advanced JSON for power users. Empty fields are simply skipped. - **LLM/MCP-friendly output.** One flat, camelCase row per record, each tagged with a clear `featureType`, ready to pipe into a spreadsheet, database, or AI pipeline. - **Safe by design.** Write caps, pacing, and automatic stop-on-error protect your account. --- ### Use cases - **Audience curation** — build and maintain topic/industry lists, adding hundreds of accounts from a spreadsheet of handles in one run. - **Competitor-list monitoring** — track who a rival adds to their public lists and what those lists are posting, on a schedule. - **List-based lead generation** — export the members and followers of a niche list as structured contact-ready rows. - **Bulk list hygiene** — prune inactive or off-topic accounts from your lists, or archive/delete stale lists en masse. --- ### What it can do #### Read (public — no login needed) For each target list, collect any combination of: | Type | What you get | | --- | --- | | **Details** | List metadata: id, name, description, member/follower counts, public/private mode, owner | | **Tweets** | The list timeline, newest first, fully paginated | | **Members** | Every user on the list | | **Followers** | Every user who follows the list | Reading is public and uses no account — just add the lists and run. #### Manage (requires your account) | Operation | What it does | | --- | --- | | **Create list** | Make a new list (name, description, public/private) | | **Add members** | Add users by @handle or numeric ID (handles resolved automatically) | | **Remove members** | Remove users by @handle or numeric ID | | **Update list** | Rename, re-describe, or change privacy *(where supported)* | | **Delete list** | Permanently delete a list *(where supported)* | --- ### Quick start — read a list 1. Paste one or more lists into **List targets** (IDs or `x.com/i/lists/...` URLs). 2. Choose **What to collect** (defaults to the list's tweets). 3. Run it. ```json { "listTargets": ["https://x.com/i/lists/1234567890123456789"], "listScrapeType": ["details", "tweets", "members"], "maxTweetsPerList": 200 } ```` ### Quick start — manage a list 1. Connect your account: fill **X auth token** and your **proxy** fields (see below). 2. Tick **Enable Manage mode**. 3. Fill only the operation(s) you want — e.g. add members: ```json { "enableManage": true, "authToken": "your_auth_token", "proxyHost": "proxy.example.com", "proxyPort": "8080", "proxyUsername": "myuser", "proxyPassword": "mypass", "addMembersListId": "1234567890123456789", "addMemberHandles": ["nasa", "spacex", "esa"] } ``` Each attempted action becomes one row showing whether it succeeded, plus the resulting id/URL. > **How the form works:** Reading turns on automatically when you add **List targets**. Managing is gated behind **Enable Manage mode** for safety. Each area is split into small sections — *Create a list*, *Add members*, *Remove members*, and *Advanced bulk operations*. Tick the toggle, fill only what you need, and combine several operations in one run. *** ### Requirements for Manage mode Reading needs nothing. **Managing writes to your own account**, so you connect it at run time. #### 1. Your X auth token The Actor acts using your account's `auth_token` cookie. **Easiest way (Chrome extension):** 1. Install a cookie viewer such as **[Cookie-Editor](https://chromewebstore.google.com/detail/cookie-editor/hlkenndednhfkekhgcdicdfddnkalmdm)** or **EditThisCookie** from the Chrome Web Store. 2. Open and log in to **[x.com](https://x.com)**. 3. Click the extension icon, find the cookie named **`auth_token`**, and copy its value. 4. Paste it into the **X auth token** field. **Manual way (no extension):** 1. Log in to **x.com** in Chrome. 2. Press **F12** → open the **Application** tab. 3. In the left sidebar: **Cookies → https://x.com**. 4. Find **`auth_token`** and copy its **Value**. If an operation needs it, grab **`ct0`** the same way and paste it into the optional **ct0** field. > Keep these values private — anyone with them can act as your account. They're stored as secrets and never logged. #### 2. A sticky proxy Provide a stable, user-owned proxy in four simple fields: - **Proxy host** — e.g. `proxy.example.com` - **Proxy port** — e.g. `8080` - **Proxy username** - **Proxy password** (Advanced users can instead paste a full `host:port@user:pass` string in the optional **Full proxy string** field, which overrides the four fields.) > Use a **sticky** (non-rotating) residential/ISP proxy whose IP stays consistent. **Apify's rotating proxy must not be used for logged-in actions** — switching IPs mid-session triggers security challenges. A stable IP keeps your session healthy. *** ### Safety (Manage mode) Writing to a social account is destructive, so the Actor is conservative by design: - **One row per action** with a clear `status` (`success`, `failed`, `skipped`, or `ambiguous`). - **One bad action never aborts the run** — the run keeps going and finishes with a summary. - **Max actions cap** (`maxActions`, default 50) guards against accidental bulk writes; extra actions are marked `skipped`. - **Pacing** (`delayBetweenActionsMs`, default ~1.5s) spaces out writes. - **Stop on session/proxy error** (`stopOnAuthOrProxyError`, default on) halts the run instead of hammering a dead session; the rest are `skipped`. - **Smart retries.** Add/remove member retry on rate limits and temporary errors (honoring `Retry-After`). **Create and delete are never retried after they're sent** — an ambiguous timeout is reported as `ambiguous`, never resent, so you never get duplicates. A create that returns no new list id is reported as a failure, not a false success. *** ### Input reference #### Read | Field | Type | Default | Description | | --- | --- | --- | --- | | `listTargets` | string\[] | — | List IDs and/or `x.com/i/lists/...` URLs (same field). | | `listScrapeType` | string\[] | `["tweets"]` | Any of `details`, `tweets`, `members`, `followers`. | | `maxTweetsPerList` | integer | `500` | Tweets collected per list (`0` = no per-list cap). Raise it to any number. | | `maxMembersPerList` / `maxFollowersPerList` | integer | `0` | Per-list caps for members/followers (`0` = no per-list cap). | | `maxPagesPerList` | integer | `10` | Upstream cost control — max cursor pages per list/type. Each page ≈ one request (~100 items). Covers the default 500 tweets (~6 pages); raise it if you increase the per-list caps. The run logs a warning if results are truncated here. | | `maxUpstreamRequests` | integer | `0` | Global cost cap — hard ceiling on total data requests per run (across every list and operation). Each request ≈ 100 items, so ~6 requests = 500 tweets from one list. When hit, the run stops and keeps everything collected so far (summary flags `stoppedEarly`). `0` = no limit. Most useful for multi-list runs. | | `maxItems` | integer | `100000` | Global cap across all lists/types. | #### Tweet filters (applied to list tweets) All optional: `filterLanguage`, `minLikes`, `minRetweets`, `minReplies`, `excludeRetweets`, `excludeReplies`, `onlyVerifiedAuthors`, `fromDate`, `toDate`, `mustContainText`, `mustNotContainText`, `hasMedia`, `hasLinks`. #### Manage | Field | Type | Description | | --- | --- | --- | | `enableManage` | boolean | Master switch for all write operations. | | `createListName` / `createListDescription` / `createListPrivate` | — | Create a single list. | | `addMembersListId` + `addMemberHandles` | — | Add @handles to a list. | | `removeMembersListId` + `removeMemberHandles` | — | Remove @handles from a list. | | `createLists` | JSON | `[{ "name": "...", "description": "...", "isPrivate": true }]` | | `addListMembers` / `removeListMembers` | JSON | `[{ "listId": "...", "username": "handle" }]` or `[{ "listId": "...", "userId": "..." }]` | | `updateLists` | JSON | `[{ "listId": "...", "name": "...", "description": "...", "isPrivate": false }]` | | `deleteListIds` | string\[] | List IDs to permanently delete. | #### Account & safety (Manage only) `authToken` (secret), `ct0` (secret, optional), `proxyHost`, `proxyPort`, `proxyUsername` (secret), `proxyPassword` (secret), `userProxy` (secret, advanced), `maxActions`, `delayBetweenActionsMs`, `stopOnAuthOrProxyError`. *** ### Output Every record is one flat, camelCase dataset row, tagged with a `featureType` and carrying `scrapedAt`, `sourceUrl` (`https://x.com/i/lists/`), `inputRef`, and `listId`. **Read — list details:** ```json { "featureType": "list_details", "listId": "1234567890123456789", "name": "Space & Astronomy", "description": "People worth following about space.", "memberCount": 128, "followerCount": 4400, "mode": "Public", "isPrivate": false, "ownerUsername": "someowner", "sourceUrl": "https://x.com/i/lists/1234567890123456789", "scrapedAt": "2026-07-06T12:00:00.000Z" } ``` **Read — list tweets** (`featureType: "list_tweets"`) use the canonical tweet shape stamped with the `listId`. List timelines are retweet-heavy, so retweets and quotes are fully expanded: - **Real engagement on retweets** — the retweet "wrapper" reports zeroed likes/views, so each row surfaces the *original* tweet's `likeCount`, `retweetCount`, `replyCount`, `quoteCount` and `viewCount`. Filtering and ranking reflect true reach. - **Retweet / quote / reply context** — `type` (`tweet`/`reply`/`quote`/`retweet`), `isRetweet`/`isQuote`/`isReply`, `retweetedTweetId` + `retweetedAuthorUsername` + `retweetedText`, `quotedTweetId` + `quotedAuthorUsername` + `quotedText`, and `inReplyToTweetId` + `inReplyToUsername`. The full nested originals are available as `retweetedTweet` and `quotedTweet`. - **Author (flattened)** — `authorId`, `authorName`, `authorFollowersCount`, `authorVerified`, `authorProfileUrl`. - **Content & entities** — `source` (posting client), `lang`, `hashtags`, `cashtags`, `mentions`, `urls` (with `expandedUrl`), `media` (photos/videos with `durationMs`, dimensions, alt text), plus a flattened link-preview card: `cardTitle`, `cardDescription`, `cardDomain`. Flags: `possiblySensitive`, `isEdited`. - **Roll-ups** — `engagementTotal` (likes + retweets + replies + quotes), `bookmarkCount`, `hashtagCount`, `mentionCount`, `mediaCount`, `mediaType`, `videoUrl`, `linkCount`, `hasMedia`, `hasLinks`. **Members/followers** (`featureType: "list_members"` / `"list_followers"`) use the canonical user shape, each stamped with the `listId`. **Manage — action result:** ```json { "featureType": "list_action", "operation": "add_member", "status": "success", "listId": "1234567890123456789", "inputRef": "1234567890123456789:nasa", "resultId": "11348282", "resultUrl": "https://x.com/i/lists/1234567890123456789", "apiAction": "add_list_member", "plannedRequest": { "endpoint": "list/add-member", "listId": "1234567890123456789", "userId": "11348282" }, "message": null, "scrapedAt": "2026-07-06T12:00:00.000Z" } ``` Targets that can't be read or managed (private, deleted, not found) appear as an `unavailable` row with a `reason` — they never crash the run. A per-run summary (operating mode, record counts, operation and status counts, records pushed, and non-fatal errors) is written to the key-value store record **`OUTPUT`**. The dataset ships with tabbed views: **Overview, List details, List tweets, Members, Followers, Actions, Unavailable.** *** ### 📬 Contact & custom projects Need something built? I take on custom work, including: - **Web scraping & data extraction** — Apify Actors, crawlers, and automation for any site or API. - **Web apps** — dashboards, tools, and full-stack applications of any kind. - **Automation & integrations** — bots, pipelines, and workflow automation. Reach out — happy to discuss your project: - **Email:** - **GitHub:** [github.com/DrunkCodes](https://github.com/DrunkCodes) # Actor input Schema ## `listTargets` (type: `array`): The lists to read. Paste list IDs and/or full x.com list URLs in the same field — e.g. 1234567890123456789 or https://x.com/i/lists/1234567890123456789. IDs are extracted from URLs automatically. Add as many as you like to batch many lists in one run. Leave empty if you only want to Manage lists (below). The prefilled ID (2043595344156504084) is a public list you can run right away to see the output. ## `listScrapeType` (type: `array`): Pick any combination of parts to collect for each list: details (metadata), tweets (the list timeline), members (users on the list), and followers (users who follow the list). Defaults to the list timeline (tweets). ## `maxItems` (type: `integer`): Hard cap on the total number of read records pushed across all lists and types this run. Protects against runaway large lists. 0 or blank uses the built-in default. ## `maxUpstreamRequests` (type: `integer`): Hard ceiling on the total number of upstream data requests this run makes, across every list and operation. Each request returns ~100 tweets/users, so this is the single lever to control subscription cost — e.g. 6 requests ≈ 500 tweets from one list. Once the ceiling is hit the run stops and keeps everything collected so far, and the log/summary note that it stopped early. Leave 0 for no limit (bounded by the per-list caps instead). Most useful when reading many lists at once. ## `maxTweetsPerList` (type: `integer`): Cap on tweets collected from each list timeline. Defaults to 500 — increase it to any number you want, or set 0 for no per-list cap (bounded only by Max items and Max pages). ## `maxMembersPerList` (type: `integer`): Cap on members collected from each list. 0 means no per-list cap. ## `maxFollowersPerList` (type: `integer`): Cap on followers collected from each list. 0 means no per-list cap. ## `maxPagesPerList` (type: `integer`): Upstream cost control: the maximum number of cursor pages fetched per list and per type. Each page is one upstream request (~100 tweets/users per page), so this directly caps how many requests a run makes. The default of 10 comfortably covers the default 500 tweets per list (~6 pages) while stopping runaway pagination — most useful for members/followers, which have no per-list cap by default. If you raise the per-list limits (e.g. many more tweets) and want the full result, increase this too; the run logs a warning when it stops here with more data available. ## `filterLanguage` (type: `string`): Optional. Keep only list tweets in this language (ISO code, e.g. en, es, fr). Leave empty to keep all languages. Applied after fetching. ## `minLikes` (type: `integer`): Optional. Keep only tweets with at least this many likes. 0 disables this filter. ## `minRetweets` (type: `integer`): Optional. Keep only tweets with at least this many retweets. 0 disables this filter. ## `minReplies` (type: `integer`): Optional. Keep only tweets with at least this many replies. 0 disables this filter. ## `excludeRetweets` (type: `boolean`): Optional. Drop retweets from the list timeline results. ## `excludeReplies` (type: `boolean`): Optional. Drop replies from the list timeline results. ## `onlyVerifiedAuthors` (type: `boolean`): Optional. Keep only tweets whose author is verified (legacy verified or Blue). ## `fromDate` (type: `string`): Optional. Keep only tweets created on or after this date/time (ISO 8601, e.g. 2026-01-01 or 2026-01-01T00:00:00Z). ## `toDate` (type: `string`): Optional. Keep only tweets created on or before this date/time (ISO 8601, e.g. 2026-06-30). ## `mustContainText` (type: `string`): Optional. Keep only tweets whose text contains this string (case-insensitive). ## `mustNotContainText` (type: `string`): Optional. Drop tweets whose text contains this string (case-insensitive). ## `hasMedia` (type: `boolean`): Optional. Keep only tweets that include at least one image/video/GIF. ## `hasLinks` (type: `boolean`): Optional. Keep only tweets that include at least one link. ## `enableManage` (type: `boolean`): Master switch for all write operations (create list, add/remove members, update, delete). Leave OFF for read-only runs. When ON, you must connect your X account and a sticky proxy in the sections below. ## `createListName` (type: `string`): Name of a single list to create. Leave empty if you are not creating a list. For creating many at once, use 'Advanced: bulk create lists' below. ## `createListDescription` (type: `string`): Optional description for the new list above. ## `createListPrivate` (type: `boolean`): If ticked, the new list above is private (only you can see it). Untick for a public list. ## `addMembersListId` (type: `string`): The list ID you want to add members to. Leave empty if you are not adding members. ## `addMemberHandles` (type: `array`): @handles to add to the list above (the leading @ is optional). Resolved to numeric user IDs automatically, in batches. ## `removeMembersListId` (type: `string`): The list ID you want to remove members from. Leave empty if you are not removing members. ## `removeMemberHandles` (type: `array`): @handles to remove from the list above (the leading @ is optional). Resolved to numeric user IDs automatically. ## `createLists` (type: `array`): Advanced — create many lists at once. Each item: { "name": "...", "description": "...", "isPrivate": true }. 'name' is required. Added on top of the single 'New list' above. ## `addListMembers` (type: `array`): Advanced — add members to any list(s). Each item: { "listId": "...", "username": "handle" } or { "listId": "...", "userId": "..." }. Handles are resolved automatically. Added on top of the simple 'Add members' fields. ## `removeListMembers` (type: `array`): Advanced — remove members from any list(s). Each item: { "listId": "...", "username": "handle" } or { "listId": "...", "userId": "..." }. Added on top of the simple 'Remove members' fields. ## `updateLists` (type: `array`): Advanced — rename a list or change its description/privacy. Each item: { "listId": "...", "name": "...", "description": "...", "isPrivate": false }. 'listId' plus at least one field to change is required. (Availability depends on the platform.) ## `deleteListIds` (type: `array`): Advanced — IDs of your own lists to permanently delete. This is irreversible. (Availability depends on the platform.) ## `authToken` (type: `string`): Your X account login token (the 'auth\_token' cookie). Required ONLY for Manage mode. HOW TO GET IT: 1) Log in to x.com in Chrome. 2) Press F12 → open the 'Application' tab → Cookies → https://x.com. 3) Copy the value of the cookie named 'auth\_token'. Easier option: install the free 'Cookie-Editor' or 'EditThisCookie' Chrome extension, click it on x.com, and copy the 'auth\_token' value. Treated as a secret and never logged. ## `ct0` (type: `string`): Optional. Your X 'ct0' CSRF cookie, retrieved the same way as auth\_token (F12 → Application → Cookies → https://x.com → copy 'ct0'; or via the Cookie-Editor / EditThisCookie extension). Only needed if a write operation requires the CSRF cookie. Treated as a secret and never logged. ## `proxyHost` (type: `string`): Your proxy server address, e.g. proxy.example.com or 123.45.67.89. From your proxy provider's dashboard. Required for Manage mode. ## `proxyPort` (type: `string`): Your proxy port number, e.g. 8080. From your proxy provider's dashboard. Required for Manage mode. ## `proxyUsername` (type: `string`): The username/login for your proxy. From your proxy provider's dashboard. Required for Manage mode. ## `proxyPassword` (type: `string`): The password for your proxy. From your proxy provider's dashboard. Treated as a secret and never logged. Required for Manage mode. ## `userProxy` (type: `string`): Advanced: instead of the four fields above, paste a full proxy string in host:port@user:pass format (e.g. proxy.example.com:8080@myuser:mypass). If set, this overrides the separate fields. Must be a sticky, non-rotating residential/ISP proxy. ## `maxActions` (type: `integer`): Hard cap on how many Manage actions this run will attempt. Extra actions beyond the cap are marked 'skipped'. Set 0 for unlimited (discouraged). Protects against accidental bulk writes. ## `delayBetweenActionsMs` (type: `integer`): Pause added after each Manage action to space out writes for account safety. 0 disables pacing. ## `stopOnAuthOrProxyError` (type: `boolean`): If a session (expired token) or proxy error occurs, stop the rest of the Manage run instead of hammering a dead session. Remaining actions are marked 'skipped'. ## `includeRaw` (type: `boolean`): Attach the raw upstream response object to each row. Useful for debugging; increases dataset size. ## `maxRetries` (type: `integer`): Retries for transient failures (rate limits / temporary server errors). Idempotent writes (add/remove member) are retried; list create/delete are never retried after dispatch, to avoid duplicates. ## `retryBaseDelayMs` (type: `integer`): Base backoff delay for retries. Grows exponentially and honors any Retry-After hint from the server. ## `retryMaxDelayMs` (type: `integer`): Maximum backoff delay between retries. ## Actor input object example ```json { "listTargets": [ "2043595344156504084" ], "listScrapeType": [ "tweets" ], "maxItems": 100000, "maxUpstreamRequests": 0, "maxTweetsPerList": 500, "maxMembersPerList": 0, "maxFollowersPerList": 0, "maxPagesPerList": 10, "filterLanguage": "", "minLikes": 0, "minRetweets": 0, "minReplies": 0, "excludeRetweets": false, "excludeReplies": false, "onlyVerifiedAuthors": false, "fromDate": "", "toDate": "", "mustContainText": "", "mustNotContainText": "", "hasMedia": false, "hasLinks": false, "enableManage": false, "createListName": "", "createListDescription": "", "createListPrivate": true, "addMembersListId": "", "addMemberHandles": [], "removeMembersListId": "", "removeMemberHandles": [], "createLists": [], "addListMembers": [], "removeListMembers": [], "updateLists": [], "deleteListIds": [], "maxActions": 50, "delayBetweenActionsMs": 1500, "stopOnAuthOrProxyError": true, "includeRaw": false, "maxRetries": 5, "retryBaseDelayMs": 2000, "retryMaxDelayMs": 30000 } ``` # Actor output Schema ## `results` (type: `string`): Every record from this run, tagged by featureType: list\_details, list\_tweets, list\_members, list\_followers, list\_action, and unavailable. ## `overview` (type: `string`): Key fields across every record type in a single table. ## `actions` (type: `string`): Just the Manage action results: operation, status, resulting id/URL, and any error message. ## `runSummary` (type: `string`): Per-run metadata: operating mode(s), record counts, operation and status counts, records pushed, upstream request count, and non-fatal errors. # 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 = { "listTargets": [ "2043595344156504084" ], "listScrapeType": [ "tweets" ], "maxTweetsPerList": 500, "addMemberHandles": [], "removeMemberHandles": [], "createLists": [], "addListMembers": [], "removeListMembers": [], "updateLists": [], "deleteListIds": [] }; // Run the Actor and wait for it to finish const run = await client.actor("b2b_leads/x-lists-manager").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 = { "listTargets": ["2043595344156504084"], "listScrapeType": ["tweets"], "maxTweetsPerList": 500, "addMemberHandles": [], "removeMemberHandles": [], "createLists": [], "addListMembers": [], "removeListMembers": [], "updateLists": [], "deleteListIds": [], } # Run the Actor and wait for it to finish run = client.actor("b2b_leads/x-lists-manager").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 '{ "listTargets": [ "2043595344156504084" ], "listScrapeType": [ "tweets" ], "maxTweetsPerList": 500, "addMemberHandles": [], "removeMemberHandles": [], "createLists": [], "addListMembers": [], "removeListMembers": [], "updateLists": [], "deleteListIds": [] }' | apify call b2b_leads/x-lists-manager --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=b2b_leads/x-lists-manager", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "X (Twitter) Lists – Scrape Tweets, Members & Manage Lists", "description": "Scrape and manage X (Twitter) Lists in one Actor. Export list tweets, members, followers & details as structured data, or create lists and add/remove members. Retweets expanded with real engagement. Filters, per-list caps & a request budget keep costs low.", "version": "0.0", "x-build-id": "g5ObQQk5jO3ZyDd8f" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/b2b_leads~x-lists-manager/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-b2b_leads-x-lists-manager", "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/b2b_leads~x-lists-manager/runs": { "post": { "operationId": "runs-sync-b2b_leads-x-lists-manager", "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/b2b_leads~x-lists-manager/run-sync": { "post": { "operationId": "run-sync-b2b_leads-x-lists-manager", "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": { "listTargets": { "title": "List targets (IDs or URLs)", "type": "array", "description": "The lists to read. Paste list IDs and/or full x.com list URLs in the same field — e.g. 1234567890123456789 or https://x.com/i/lists/1234567890123456789. IDs are extracted from URLs automatically. Add as many as you like to batch many lists in one run. Leave empty if you only want to Manage lists (below). The prefilled ID (2043595344156504084) is a public list you can run right away to see the output.", "default": [], "items": { "type": "string" } }, "listScrapeType": { "title": "What to collect per list", "type": "array", "description": "Pick any combination of parts to collect for each list: details (metadata), tweets (the list timeline), members (users on the list), and followers (users who follow the list). Defaults to the list timeline (tweets).", "items": { "type": "string", "enum": [ "details", "tweets", "members", "followers" ], "enumTitles": [ "Details (metadata)", "Tweets (timeline)", "Members", "Followers" ] }, "default": [ "tweets" ] }, "maxItems": { "title": "Max items (global)", "minimum": 0, "type": "integer", "description": "Hard cap on the total number of read records pushed across all lists and types this run. Protects against runaway large lists. 0 or blank uses the built-in default.", "default": 100000 }, "maxUpstreamRequests": { "title": "Max data requests per run (cost cap)", "minimum": 0, "type": "integer", "description": "Hard ceiling on the total number of upstream data requests this run makes, across every list and operation. Each request returns ~100 tweets/users, so this is the single lever to control subscription cost — e.g. 6 requests ≈ 500 tweets from one list. Once the ceiling is hit the run stops and keeps everything collected so far, and the log/summary note that it stopped early. Leave 0 for no limit (bounded by the per-list caps instead). Most useful when reading many lists at once.", "default": 0 }, "maxTweetsPerList": { "title": "Max tweets per list", "minimum": 0, "type": "integer", "description": "Cap on tweets collected from each list timeline. Defaults to 500 — increase it to any number you want, or set 0 for no per-list cap (bounded only by Max items and Max pages).", "default": 500 }, "maxMembersPerList": { "title": "Max members per list", "minimum": 0, "type": "integer", "description": "Cap on members collected from each list. 0 means no per-list cap.", "default": 0 }, "maxFollowersPerList": { "title": "Max followers per list", "minimum": 0, "type": "integer", "description": "Cap on followers collected from each list. 0 means no per-list cap.", "default": 0 }, "maxPagesPerList": { "title": "Max pages per list/type", "minimum": 1, "type": "integer", "description": "Upstream cost control: the maximum number of cursor pages fetched per list and per type. Each page is one upstream request (~100 tweets/users per page), so this directly caps how many requests a run makes. The default of 10 comfortably covers the default 500 tweets per list (~6 pages) while stopping runaway pagination — most useful for members/followers, which have no per-list cap by default. If you raise the per-list limits (e.g. many more tweets) and want the full result, increase this too; the run logs a warning when it stops here with more data available.", "default": 10 }, "filterLanguage": { "title": "Language", "type": "string", "description": "Optional. Keep only list tweets in this language (ISO code, e.g. en, es, fr). Leave empty to keep all languages. Applied after fetching.", "default": "" }, "minLikes": { "title": "Minimum likes", "minimum": 0, "type": "integer", "description": "Optional. Keep only tweets with at least this many likes. 0 disables this filter.", "default": 0 }, "minRetweets": { "title": "Minimum retweets", "minimum": 0, "type": "integer", "description": "Optional. Keep only tweets with at least this many retweets. 0 disables this filter.", "default": 0 }, "minReplies": { "title": "Minimum replies", "minimum": 0, "type": "integer", "description": "Optional. Keep only tweets with at least this many replies. 0 disables this filter.", "default": 0 }, "excludeRetweets": { "title": "Exclude retweets", "type": "boolean", "description": "Optional. Drop retweets from the list timeline results.", "default": false }, "excludeReplies": { "title": "Exclude replies", "type": "boolean", "description": "Optional. Drop replies from the list timeline results.", "default": false }, "onlyVerifiedAuthors": { "title": "Only verified authors", "type": "boolean", "description": "Optional. Keep only tweets whose author is verified (legacy verified or Blue).", "default": false }, "fromDate": { "title": "From date", "type": "string", "description": "Optional. Keep only tweets created on or after this date/time (ISO 8601, e.g. 2026-01-01 or 2026-01-01T00:00:00Z).", "default": "" }, "toDate": { "title": "To date", "type": "string", "description": "Optional. Keep only tweets created on or before this date/time (ISO 8601, e.g. 2026-06-30).", "default": "" }, "mustContainText": { "title": "Must contain text", "type": "string", "description": "Optional. Keep only tweets whose text contains this string (case-insensitive).", "default": "" }, "mustNotContainText": { "title": "Must NOT contain text", "type": "string", "description": "Optional. Drop tweets whose text contains this string (case-insensitive).", "default": "" }, "hasMedia": { "title": "Has media", "type": "boolean", "description": "Optional. Keep only tweets that include at least one image/video/GIF.", "default": false }, "hasLinks": { "title": "Has links", "type": "boolean", "description": "Optional. Keep only tweets that include at least one link.", "default": false }, "enableManage": { "title": "Enable Manage mode", "type": "boolean", "description": "Master switch for all write operations (create list, add/remove members, update, delete). Leave OFF for read-only runs. When ON, you must connect your X account and a sticky proxy in the sections below.", "default": false }, "createListName": { "title": "New list — name", "type": "string", "description": "Name of a single list to create. Leave empty if you are not creating a list. For creating many at once, use 'Advanced: bulk create lists' below.", "default": "" }, "createListDescription": { "title": "New list — description", "type": "string", "description": "Optional description for the new list above.", "default": "" }, "createListPrivate": { "title": "New list — private", "type": "boolean", "description": "If ticked, the new list above is private (only you can see it). Untick for a public list.", "default": true }, "addMembersListId": { "title": "Add members — list ID", "type": "string", "description": "The list ID you want to add members to. Leave empty if you are not adding members.", "default": "" }, "addMemberHandles": { "title": "Add members — usernames", "type": "array", "description": "@handles to add to the list above (the leading @ is optional). Resolved to numeric user IDs automatically, in batches.", "default": [], "items": { "type": "string" } }, "removeMembersListId": { "title": "Remove members — list ID", "type": "string", "description": "The list ID you want to remove members from. Leave empty if you are not removing members.", "default": "" }, "removeMemberHandles": { "title": "Remove members — usernames", "type": "array", "description": "@handles to remove from the list above (the leading @ is optional). Resolved to numeric user IDs automatically.", "default": [], "items": { "type": "string" } }, "createLists": { "title": "Advanced: bulk create lists (JSON)", "type": "array", "description": "Advanced — create many lists at once. Each item: { \"name\": \"...\", \"description\": \"...\", \"isPrivate\": true }. 'name' is required. Added on top of the single 'New list' above.", "default": [] }, "addListMembers": { "title": "Advanced: bulk add list members (JSON)", "type": "array", "description": "Advanced — add members to any list(s). Each item: { \"listId\": \"...\", \"username\": \"handle\" } or { \"listId\": \"...\", \"userId\": \"...\" }. Handles are resolved automatically. Added on top of the simple 'Add members' fields.", "default": [] }, "removeListMembers": { "title": "Advanced: bulk remove list members (JSON)", "type": "array", "description": "Advanced — remove members from any list(s). Each item: { \"listId\": \"...\", \"username\": \"handle\" } or { \"listId\": \"...\", \"userId\": \"...\" }. Added on top of the simple 'Remove members' fields.", "default": [] }, "updateLists": { "title": "Advanced: update lists (JSON)", "type": "array", "description": "Advanced — rename a list or change its description/privacy. Each item: { \"listId\": \"...\", \"name\": \"...\", \"description\": \"...\", \"isPrivate\": false }. 'listId' plus at least one field to change is required. (Availability depends on the platform.)", "default": [] }, "deleteListIds": { "title": "Advanced: delete list IDs", "type": "array", "description": "Advanced — IDs of your own lists to permanently delete. This is irreversible. (Availability depends on the platform.)", "default": [], "items": { "type": "string" } }, "authToken": { "title": "X auth token", "type": "string", "description": "Your X account login token (the 'auth_token' cookie). Required ONLY for Manage mode. HOW TO GET IT: 1) Log in to x.com in Chrome. 2) Press F12 → open the 'Application' tab → Cookies → https://x.com. 3) Copy the value of the cookie named 'auth_token'. Easier option: install the free 'Cookie-Editor' or 'EditThisCookie' Chrome extension, click it on x.com, and copy the 'auth_token' value. Treated as a secret and never logged." }, "ct0": { "title": "ct0 (CSRF cookie — optional)", "type": "string", "description": "Optional. Your X 'ct0' CSRF cookie, retrieved the same way as auth_token (F12 → Application → Cookies → https://x.com → copy 'ct0'; or via the Cookie-Editor / EditThisCookie extension). Only needed if a write operation requires the CSRF cookie. Treated as a secret and never logged." }, "proxyHost": { "title": "Proxy host", "type": "string", "description": "Your proxy server address, e.g. proxy.example.com or 123.45.67.89. From your proxy provider's dashboard. Required for Manage mode." }, "proxyPort": { "title": "Proxy port", "type": "string", "description": "Your proxy port number, e.g. 8080. From your proxy provider's dashboard. Required for Manage mode." }, "proxyUsername": { "title": "Proxy username", "type": "string", "description": "The username/login for your proxy. From your proxy provider's dashboard. Required for Manage mode." }, "proxyPassword": { "title": "Proxy password", "type": "string", "description": "The password for your proxy. From your proxy provider's dashboard. Treated as a secret and never logged. Required for Manage mode." }, "userProxy": { "title": "Full proxy string (advanced — optional)", "type": "string", "description": "Advanced: instead of the four fields above, paste a full proxy string in host:port@user:pass format (e.g. proxy.example.com:8080@myuser:mypass). If set, this overrides the separate fields. Must be a sticky, non-rotating residential/ISP proxy." }, "maxActions": { "title": "Max actions per run", "minimum": 0, "type": "integer", "description": "Hard cap on how many Manage actions this run will attempt. Extra actions beyond the cap are marked 'skipped'. Set 0 for unlimited (discouraged). Protects against accidental bulk writes.", "default": 50 }, "delayBetweenActionsMs": { "title": "Delay between actions (ms)", "minimum": 0, "type": "integer", "description": "Pause added after each Manage action to space out writes for account safety. 0 disables pacing.", "default": 1500 }, "stopOnAuthOrProxyError": { "title": "Stop on session/proxy error", "type": "boolean", "description": "If a session (expired token) or proxy error occurs, stop the rest of the Manage run instead of hammering a dead session. Remaining actions are marked 'skipped'.", "default": true }, "includeRaw": { "title": "Include raw response (debugging)", "type": "boolean", "description": "Attach the raw upstream response object to each row. Useful for debugging; increases dataset size.", "default": false }, "maxRetries": { "title": "Max retries", "minimum": 0, "type": "integer", "description": "Retries for transient failures (rate limits / temporary server errors). Idempotent writes (add/remove member) are retried; list create/delete are never retried after dispatch, to avoid duplicates.", "default": 5 }, "retryBaseDelayMs": { "title": "Retry base delay (ms)", "minimum": 100, "type": "integer", "description": "Base backoff delay for retries. Grows exponentially and honors any Retry-After hint from the server.", "default": 2000 }, "retryMaxDelayMs": { "title": "Retry max delay (ms)", "minimum": 1000, "type": "integer", "description": "Maximum backoff delay between retries.", "default": 30000 } } }, "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 } } } } } } } } } } ```