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