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.

{
  "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:

{
  "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 or EditThisCookie from the Chrome Web Store.
2. Open and log in to 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/<id>), inputRef, and listId.

Read — list details:

{
  "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:

{
  "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: dubem115@gmail.com
• GitHub: github.com/DrunkCodes