twscrape for Twitter (X): what the account pool costs you, and how to migrate to an API with no accounts

twscrape (GitHub vladkens/twscrape, PyPI twscrape) describes itself as "an async Python library and CLI for X/Twitter Search and GraphQL endpoints. It runs on your own account pool, keeps sessions in SQLite, rotates accounts when an endpoint is rate-limited" and returns "either parsed SNScrape-style models or raw API responses". The PyPI summary is "Twitter GraphQL and Search API implementation with SNScrape data models". As read this year: version 0.20.1, Python 3.10 or newer, MIT license, 2.9k stars, 330 forks, 301 commits, 77 open issues, releases v0.19.2, v0.20.0 and v0.20.1 all shipped in 2026, and the latest commit on main ("fix: retain tweets whose nested authors lack profiles") landed this year. It is maintained, which is the first thing to say about it and the main thing that separates it from snscrape and twint.

The pool comes first. Install is pip install twscrape, but nothing runs until accounts.db has at least one active account. The README gives two ways in. twscrape add_accounts ./accounts.txt username:password:email:email_password takes a text file of credentials, one account per line, and twscrape login_accounts logs each one in, handling the email verification code X sends by reading the mailbox you gave it. Or, the route the README calls the most stable, twscrape add_cookie my_account takes cookies exported from a browser session; an account whose cookies contain auth_token and ct0 is "activated immediately". Proxies are per account (add_account(..., proxy="http://login:pass@host:port")), per API(proxy=...) instance, or global through TWS_PROXY, with the API-level proxy winning. An optional twscrape[curl] extra switches the HTTP backend to curl-cffi for a browser-like TLS fingerprint.

Rotation and locks are the design. From the README: "Rate limits are tracked per account and per endpoint. When an account is limited for one operation, twscrape locks it for that operation until the reset time and tries another active account." That is the whole trick. One account gets a fixed number of search requests per 15-minute window from X; N accounts get N times that; when the pool is exhausted twscrape waits (newer releases added wait_timeout and wait_interval to bound that wait). The account-management CLI tells you what the operational surface looks like: twscrape accounts and twscrape stats to see the pool, relogin user1 user2 and relogin_failed to re-authenticate, reset_locks when locks go stale, delete_inactive and del_accounts to prune.

limit counts objects, not pages. The README is explicit: limit "is the target number of parsed objects, not a page size. X/Twitter controls page size per endpoint, so a call can return fewer or more objects than requested." X's search timeline serves about 20 tweets a page, so api.search(q, limit=500) is roughly 25 GraphQL requests spread across your accounts, and limit=20 is the one-page default every README example uses. Keep that arithmetic; the cost section uses it on both sides.

The Python surface is wide and consistent. Everything that returns many items is an async generator you drain with gather(): api.search(q, limit), api.search_user, api.user_tweets(user_id, limit), api.user_tweets_and_replies, api.user_media, api.followers(user_id, limit), api.following, api.verified_followers, api.subscriptions, api.tweet_replies, api.tweet_thread, api.retweeters, api.list_timeline, api.list_members, api.community_tweets, api.trends. Single-object calls are plain awaits: api.tweet_details(tweet_id), api.user_by_id(user_id), api.user_by_login(login), api.user_about, api.community_info. Each has a _raw twin that yields the HTTP responses, and each has a CLI command of the same name that prints JSON Lines. Note that timelines and follower lists take a numeric user_id, so a handle-based script always starts with user_by_login to resolve the id.

twscrape's code is free. Its inputs are not. You need X accounts you are willing to lose, an email inbox per account that the login flow can read, a residential or mobile proxy per account if you run more than a couple from one address, and someone to look at the pool when it degrades. The library's own CLI (relogin_failed, reset_locks, delete_inactive) exists because that degradation is routine. The open issues, read this year, show the shapes it takes; the titles below are quoted from the tracker.

Three patterns are worth naming. First, the login path is the fragile one: the number of reports where add_accounts plus login_accounts fails and the answer is "use add_cookie from a browser" is why the README now calls the cookie route the most stable. Second, the request-signing dependency on x.com's shipped JavaScript (XClIdGen) means twscrape breaks whenever X's front end changes, independent of your accounts, and stays broken until a release; that is the same maintenance treadmill that ended snscrape's Twitter module, now carried by a maintainer who is still on it. Third, the costs are accounts: every lock, active=false and ban is an account you bought or made, plus the proxy it was tied to, and X's terms give it no protection. None of this is a criticism of the code; it is what a logged-in scraper is.

What twscrape gives you that no hosted API does: zero marginal cost per tweet once the pool exists, access to a few logged-in-only reads (bookmarks, user_about, verified-follower lists), raw GraphQL responses, and no third party in the data path. If you already operate accounts for other reasons and read a few thousand tweets a day, that trade can be right. If what you want is tweets as JSON for a pipeline, the rest of this page is the alternative.

twscrape is one of a family. The useful comparison is not features but what each tool needs to run and what stops it.

agent-twitter-client, specifically. This is the client that AI agent frameworks used to post and read X without the official API; on npm it describes itself as a Twitter client designed for agents that does not require the Twitter API and runs in browser and server environments, authenticating with the account's username, password and email, with optional cookies and a proxy. As read this year, the npm registry lists 0.0.18 (December 2024) as the latest version, marks every version with the deprecation notice "Package no longer supported" (followed by a pointer to npm support), and points at a repository URL that returns 404 (so does the old elizaOS/agent-twitter-client address). ElizaOS's current Twitter plugin documentation describes "Comprehensive Twitter/X API v2 integration for elizaOS agents" and requires TWITTER_API_KEY, TWITTER_API_SECRET_KEY, TWITTER_ACCESS_TOKEN and TWITTER_ACCESS_TOKEN_SECRET, with the note "Critical: Use OAuth 1.0a, NOT OAuth 2.0!". In other words, the agent framework that shipped the no-API client went back to API keys. If your agent still imports agent-twitter-client, the reads in it map onto the same endpoints as twscrape's below; the writes (posting as the agent's account) are a separate, authenticated-session product on twitterapi.io and are covered at the end of the migration table.

The pattern across the table is the one snscrape's maintainer predicted in 2021 when closing "Support for authentication" as wontfix: logged-in scraping works until the accounts stop working, and someone has to keep paying for accounts. twscrape is the project that accepted that bill; agent-twitter-client is the one that stopped paying it.

All endpoints are GET against https://api.twitterapi.io with an X-API-Key header. twscrape's limit becomes a page loop: follow next_cursor while has_next_page is true and stop when you have enough rows. Response shapes differ by endpoint, as noted; the twscrape_compat.py at the end normalizes them.

Three things change in your code. First, twscrape resolves handles to ids and then calls everything by id; here userName= works directly on last_tweets, followers and user/info, and userId= is available where you already have ids. Second, search excludes retweets (0 of 1,500 search tweets in our study were reposts) while last_tweets includes them, as twscrape's user_tweets does, so pick the endpoint by whether reposts matter. Third, there is no pool to wait on: new accounts are held to 0.2 requests per second until the first payment and 20 per second after, and a 429 is a short sleep, not a locked account.

The question behind api.search(q, limit=500) is rarely "give me 500 tweets"; it is "give me the last day", or "the last week", of a topic. Pages do not map onto time, so we measured the mapping. In 2026 we ran advanced_search with queryType=Latest for rust lang, kubernetes and postgres, following next_cursor for up to 25 pages each, and recorded tweets per page, the span between the newest and oldest post after each page, authors, post mix and the client's wall-clock per page. The chart is the span; the table is the rest.

Pages are full; time is not. All 75 pages across the three main runs held exactly 20 tweets, so limit arithmetic is clean: 500 tweets is 25 requests and 7,500 credits ($0.075) on each query. What those 25 requests bought in history differed by a factor of 40. rust lang is a quiet two-word query (0.3 matching posts an hour), so 500 tweets ran back 61.6 days and the first 5 pages alone covered almost four days. kubernetes and postgres each produce about 13 matching posts an hour, so the same 500 tweets covered a day and a half, and 5 pages covered 6 to 7 hours. If your job is "everything about kubernetes in the last 24 hours", that is about 16 pages; for rust lang it is one. Put since_time: and until_time: (Unix seconds) in the query and let the API stop, rather than guessing a limit.

Authors spread out fast. 500 tweets came from 352 to 405 distinct authors per query, 1,125 across the three; 83% to 87% of authors appeared once. The ten most frequent authors wrote 21% of rust lang (quiet topics have regulars) and 10% of postgres. There is no author.id pool to dedupe against, as there would be with a timeline pull, so a sentiment or mention dataset built from search is broad by default.

One cursor ended early, and a fresh one did not. The first kubernetes run returned four full pages (80 tweets, 6.3 hours of posts) and then a fifth page with zero tweets, has_next_page: false and next_cursor: null. The 80 tweets were billed (1,200 credits, $0.012); the empty page cost the 15-credit minimum. A second run from an empty cursor minutes later went the full 25 pages. The lesson for a migrated limit loop is in the code above: stop on has_next_page false, log how many rows you have against the target, and if the gap matters, re-issue the query bounded with until_time: set to your oldest createdAt rather than assuming the cursor was exhaustive. twscrape users will recognize this: its search can also return fewer objects than limit, which is why the README says what it says about limit.

Pace. The 80 timed requests took 185 s, median 2.24 s and 90th percentile 2.70 s per page, through a client that spaces requests at least 0.2 s apart and was shared with other jobs on the same machine; treat it as what a careful script sees, not an API benchmark. On a new account held to 0.2 requests per second, 25 pages take about two minutes; after the first payment, at 20 per second, the client's own latency is the floor.

A twscrape search and this endpoint read the same X search timeline, so what comes back is a property of the query, not the client. Across the 1,500 tweets in the three main runs: 56% original posts, 38% replies (isReply true), 6% quotes (quoted_tweet present) and 0 reposts (retweeted_tweet was never present; Latest search does not return retweets, which matches twscrape's behavior and differs from user_tweets, where reposts appear).

Replies are a large share of a topic search: nearly half of postgres, a quarter of kubernetes. If your twscrape pipeline post-filtered them, add -filter:replies to query and pay for fewer tweets instead; if it kept them, the inReplyToId, inReplyToUsername and conversationId fields are present on each reply for threading. rust lang was only 55% English because the two words appear in several languages' posts; lang:en in the query fixes that at the source. A quarter to a third of tweets exceeded 280 characters (text carries the full long-form post; snscrape-era VARCHAR(280) columns truncate), with a 90th percentile of 417 to 699 characters.

The field set per tweet is the same as on every tweet endpoint: id, url, text, createdAt (classic Fri Oct 16 18:13:45 +0000 2026 format), lang, likeCount, retweetCount, replyCount, quoteCount, viewCount, bookmarkCount, conversationId, isReply, inReplyToId, entities.hashtags / urls / user_mentions, extendedEntities.media[], quoted_tweet, retweeted_tweet, and a full author object (id, userName, name, followers, following, isBlueVerified, createdAt). twscrape's snscrape-shaped Tweet model maps onto that one to one (rawContent is text, date is createdAt, user.username is author.userName); the full field-by-field table lives on the snscrape page, since twscrape deliberately reused those models.

twscrape's marginal cost per tweet is zero and its fixed cost is the pool: accounts, proxies, inboxes and your time, none of which this page can price for you. The hosted API inverts that: nothing fixed, 15 credits per tweet returned ($1 is 100,000 credits, so $0.15 per 1,000 tweets), a 15-credit minimum per request so an empty page costs $0.00015, profiles 18 credits each ($0.18 per 1,000), followers 1 to 3 credits per user. The official X API's pay-per-usage rate card (docs.x.com) is $0.005 per post read, $0.010 per user read, $0.010 per follower read, capped at 3 million post reads a month. Both metered columns below use the study's measured 20 tweets a page; the history column uses the study's posts-per-hour rates and is an extrapolation past 500.

The row that matters for a twscrape user is the daily one. A pool that reads 10,000 tweets a day needs enough accounts to absorb 500 search requests a day across X's per-account 15-minute windows, plus proxies; the same reads are $1.50 a day here, or $45 a month, with no accounts or proxies to buy, and the official route is $1,500 a month. For user_by_login lookups the arithmetic is 18 credits each: 1,000 profiles is $0.18, against $10.00 at the official rate. For followers, a 200-user page is billed per user at 1 to 3 credits by tier; the pricing page has the tiers.

New accounts that pass the automatic bot check get $1 of free credits (100,000 credits, no card; one per person or network, others get $0.10; the credits expire after 31 days), which is about 6,600 search tweets: enough to rerun your twscrape job through the compat module and diff the output before paying. Purchased credits do not expire. Subscriptions start at Starter $29 a month with bonus credits; the pricing page lists Builder, Pro, Scale and Business. Rate: 0.2 requests per second before the first payment, 20 once paid, 50 on Scale, 500 on Business.

The main code block at the end of this page is twscrape_compat.py: a synchronous API class with twscrape's method names (search, search_user, user_by_login, user_by_id, user_tweets, user_tweets_and_replies, tweet_details, followers, following) and the same limit semantics, plus a gather() that accepts either a list or a generator so await gather(api.search(...)) becomes gather(api.search(...)). Objects come back as the API's JSON dicts rather than twscrape's dataclasses, so attribute access (t.rawContent) becomes key access (t["text"]); the mapping is the snscrape one. There is no accounts.db, no login_accounts, no proxy and no lock table, and no equivalents for bookmarks, user_about, verified_followers or subscriptions, which are views of your own logged-in account.

How we collected this. Question: how deep does one api.search(q, limit) go through the replacement, in pages, hours of history, authors and post mix, and what does it cost? Queries: rust lang, kubernetes, postgres, each queryType=Latest, following next_cursor for up to 25 pages of /twitter/tweet/advanced_search. Window: the most recent results at collection time; per query, the span from the oldest to the newest createdAt in the pages collected (37 hours to 61.6 days). Sample: 1,580 tweets in 80 requests, of which 1,500 tweets in the three 25-page runs and 80 in a first kubernetes run whose cursor ended after four pages. Collected in 2026 through a read-only client capped at 5 requests per second; per-page wall-clock measured around each client call. Hours after N pages = newest createdAt minus oldest createdAt across the first N pages. Reply = isReply; quote = quoted_tweet present; repost = retweeted_tweet present.

What the sample cannot show. Three developer-topic queries are not all of X: a consumer topic, a hashtag or a from: query has a different posts-per-hour rate, language mix and reply share, and the history-per-page numbers are specific to these queries at this time. The early cursor end happened once in four runs; we cannot say how often it happens. The pace figure reflects a shared rate limiter, not the API's ceiling. We did not exercise user_tweets, followers, tweet_details or user_by_id in this study; their rows in the migration table come from the endpoint reference and the response shapes we use elsewhere, not from this run. Nothing on this page measures twscrape itself; its account-side numbers (requests per account per window, lock frequency) depend on your accounts and are not reproduced here.

Aggregates only. Topic searches return posts from private individuals, so the raw pages were kept only in a temporary directory and were not committed; the study folder holds the protocol, the analysis script, results.json with the aggregates, and sample.json with one de-identified row per page (page index, tweet count, time offsets, post mix, authors in page, seconds), with no ids, text, URLs or handles.