twitter-api-v2 (npm) Quick Start: the Twitter (X) API from Node.js and TypeScript in 2026

twitter-api-v2 describes itself on npm as a "strongly typed, full-featured, light, versatile yet powerful Twitter API v1.1 and v2 client for Node.js". It wraps both API generations behind one TwitterApi class, ships its own TypeScript types for request parameters and responses, signs OAuth 1.0a requests itself, supports OAuth 2.0 user context, streaming, media upload through v1.1, and has no runtime dependencies (the README puts it at about 23 kB minified and gzipped). It is published under the Apache-2.0 license by PLhery; the README names @alkihis as the former main contributor.

Status at review time, from the registry and the repository. The npm registry lists 1.29.1 as latest, published in August 2026, after 1.29.0 in January 2026 and 1.28.0 in November 2025, so the cadence is a few releases a year. The registry's download counter reported about 259,000 downloads for the latest full week. The GitHub repository is not archived: 1,555 stars, 211 forks, 31 open issues, and its most recent commit ("upgrade to 1.29.1") is the August 2026 release. The README also carries a note that the maintainers are "disappointed and discouraged by the recent turn of events at Twitter since the takeover by Elon Musk" and that much of the API work they built on "has been shelved". Read that as a maintenance mode signal: the library keeps working and gets fixes, but it tracks a platform that is no longer adding what it was designed for.

The one thing the library cannot change is what sits behind it. Since X moved its API to pay-per-usage pricing, every client.v2.* read is a billed request against a credit balance you top up on console.x.com. That is the subject of the cost section below, and the reason the second half of this page exists.

Install with npm i twitter-api-v2 (or yarn add twitter-api-v2). The package is ESM and CommonJS friendly; import { TwitterApi } from 'twitter-api-v2' or const { TwitterApi } = require('twitter-api-v2') both work, and the types come with it, so no @types package is needed.

App-only (bearer token). Pass the bearer token from your X developer app as a string: new TwitterApi(bearer). This is the read-only, no-user context: search, user lookups and public timelines work; anything that acts as a user (posting, liking, reading the home timeline) does not. If you only stored the consumer key and secret, new TwitterApi({ appKey, appSecret }) followed by await client.appLogin() fetches a bearer token for you.

User context, OAuth 1.0a. Pass the four keys from the developer portal: new TwitterApi({ appKey, appSecret, accessToken, accessSecret }). The library signs every request. This is the classic bot setup: the app acts as the one account whose access token you generated.

User context, OAuth 2.0 with PKCE. Build the client from the OAuth 2.0 client credentials, new TwitterApi({ clientId, clientSecret }), call generateOAuth2AuthLink(callbackUrl, { scope: [...] }), store the returned codeVerifier and state in the session, redirect the user, and on return call loginWithOAuth2({ code, codeVerifier, redirectUri }), which returns a logged-in client plus accessToken, refreshToken and expiresIn. With the offline.access scope you can later call refreshOAuth2Token(refreshToken) on the client-credentials client. Scopes decide what the token may do; tweet.read and users.read cover the reads on this page.

readOnly and readWrite. client.readOnly returns a view of the client that only exposes read methods, which is a cheap way to make sure a script that should never post cannot. The code below sets up all three contexts; pick one.

The v2 methods live under client.v2 and mirror the X endpoints one to one. The four below cover most scripts; the full list is in the repository's doc/v2.md.

client.v2.search(query, options) hits recent search ("Search tweets of the last 7 days with a text query", in the doc's words) and returns a paginator. client.v2.searchAll is the full-archive variant and needs an access level that allows it. The query uses X's search operators (from:, -is:retweet, lang:), and max_results goes up to 100 per page.

client.v2.userByUsername(username, options) returns a UserV2Result ({ data: { id, name, username, ... } }); usersByUsernames takes an array. You need the numeric id from here before you can read a timeline, because client.v2.userTimeline(userId, options) takes an ID, not a handle. It returns a paginator over GET /2/users/:id/tweets; userMentionTimeline is the mentions equivalent.

client.v2.tweets(ids, options) looks up up to 100 tweets by ID (singleTweet for one). All four take the same option keys: expansions, tweet.fields, user.fields, media.fields. Nothing beyond id and text comes back unless you ask for it: created_at, public_metrics, entities and referenced_tweets are opt-in tweet.fields, and media, authors and quoted or retweeted posts arrive in a separate includes block that you join to each tweet with the paginator's helper (includes.medias(tweet), includes.author(tweet), includes.quote(tweet), includes.retweet(tweet)). That join is what the TwitterAPI.io section replaces.

Search and timeline methods return a paginator rather than a bare page. await paginator.fetchNext() appends the next page to the same instance; await paginator.fetchLast(1000) keeps fetching until it has 1,000 more tweets, the API runs dry, or, in the doc's words, "the rate limit is hit"; paginator.next() returns the next page as a separate instance; for await (const tweet of paginator) walks every tweet across pages until the rate limit or the end; paginator.done tells you whether there is more. Fetched items are under .tweets (or .users, .ids for other endpoints), with .meta, .includes and .errors merged across pages.

Rate limits are per 15-minute window and come back in headers. Per docs.x.com, each response carries x-rate-limit-limit, x-rate-limit-remaining and x-rate-limit-reset (a Unix timestamp), and exceeding the window returns HTTP 429 "Rate limit exceeded". The published windows for the four reads on this page: recent search 450 requests per 15 minutes app-only or 300 with a user token; a user's tweets 10,000 app-only or 900 user; user by username 300 app-only or 900 user. The paginator exposes the last response's values as paginator.rateLimit ({ limit, remaining, reset }).

The plugin remembers them for you. @twitter-api-v2/plugin-rate-limit (version 1.1.0 on npm) stores the headers from every response, in memory by default or in a store you implement (the README mentions Redis, MongoDB and SQL as candidates). Pass it in the client options and ask rateLimitPlugin.v2.getRateLimit('users/me') before a call; hasHitRateLimit(status) and isRateLimitStatusObsolete(status) tell you whether to wait and whether the stored window has already reset.

One subtlety worth internalizing before the cost section: the docs state that "rate limits and billing are separate". Staying inside the 15-minute windows does not make a read free, and a 429 does not refund anything. The windows bound how fast you can spend; the rate card decides how much.

None of the code above runs until you have an X developer app and a credit balance. Per docs.x.com, X API v2 "uses pay-per-usage pricing": you "purchase credits, deducted per request" on console.x.com, and the rate card prices each resource read rather than each request. The published numbers that apply to the four reads on this page, and to the one write most bots make:

Two more rules from the same page: pay-per-usage plans are "capped at 3 million Post reads per monthly billing cycle" (Enterprise above that), and new accounts get "$20 in free X API credits when you save your first eligible payment card" plus a match of the first auto-recharge up to $50. The rate card also prices follower and following reads at $0.010 each and "owned reads" of your own app's own data at $0.001. Prices, the page says, "are subject to change"; the Developer Console is the authority.

What that means for a script. A timeline paginator that fetchLast(1000) through one account's posts is 1,000 post reads, $5.00. A keyword monitor that searches every minute and gets ten new posts each time reads 14,400 posts a day, $72. The rate limit never stops either of those; the credit balance does. twitter-api-v2 is a good wrapper around that economics, not a way out of it. The alternative below changes the economics, not the code shape.

TwitterAPI.io exposes X data over plain HTTPS GET endpoints with one header, X-API-Key, so from Node 18+ the whole client is fetch plus a cursor loop; there is nothing to install. Reads need no X account, no developer app and no OAuth of any kind. Pricing is per data returned: tweet endpoints cost 15 credits per tweet returned ($0.15 per 1,000 tweets, with a 15-credit minimum per request so an empty search costs $0.00015 and a full 20-tweet page $0.003), profiles 18 credits each ($0.18 per 1,000), and $1 buys 100,000 credits. Against the official $0.005 per post read that is about 33x less per 1,000 tweets ($5.00 vs $0.15). New accounts that pass the automatic bot check get up to $1 of free credits (at most 100,000 credits, no card, one per person or network, expiring after 31 days); purchased credits never expire. The rate limit is 0.2 requests per second before the first payment and 20 once paid.

Three differences to code around. First, timelines are addressed by handle, not numeric ID, so the userByUsername round trip the library needs before userTimeline disappears. Second, /twitter/user/info answers HTTP 200 with status: "error", msg: "user not found" and data: null for an unknown handle, never a 404, so check body.status as well as res.ok; a missing or invalid parameter is an HTTP 400 with the text in detail. Third, the timeline endpoint nests its array under data.tweets while search, mentions and tweets-by-ID return tweets at the top level; the generator functions in the full example at the end of this page hide that.

Search operators carry over. from:, -filter:replies, lang:, since_time: and the rest of the classic search syntax work in query; queryType=Latest orders by time, Top by relevance. The library's -is:retweet becomes -filter:retweets here, though a from: search already omits reposts in our experience; use last_tweets for the account's full timeline including reposts.

Writes. client.v2.tweet() has an equivalent, but it is a different product with different rules: one /twitter/user_login_v2 login ($0.10, with a proxy you supply) returns login_cookies, and each post, like, retweet or follow is then $0.002 per call (/twitter/create_tweet_v2, /twitter/like_tweet_v2, /twitter/follow_user_v2). The call acts as that account, so X can rate-limit, lock or suspend it; keep a human pace, expect the session to need a re-login, and note that every HTTP 200 call is billed. This page stays on reads.

A twitter-api-v2 script that asked for expansions=attachments.media_keys,referenced_tweets.id,author_id and the usual tweet.fields reads five things out of each tweet: its author, its media, its referenced tweets (quoted, retweeted, replied to), its entities and its public_metrics. On TwitterAPI.io those arrive inline on every tweet with no includes join. The question for a port is which of them are actually populated and how often, because that decides the null handling. We pulled the 200 most recent timeline posts from @nodejs, @npmjs, @github, @vercel and @typescript (1,000 posts, 50 requests, every page exactly 20 tweets) and counted.

Media hides inside reposts. 24.0% of these posts are reposts, and a repost wrapper carries an empty extendedEntities almost every time: the photos and videos sit on retweeted_tweet.extendedEntities.media. Counting only the wrapper finds media on 21.7% of posts; reading the wrapper or, failing that, the inner tweet finds it on 29.9%. For 8.2% of all posts the media exists only in the inner object. The toTweetV2() function in the full example below does const src = t.retweeted_tweet ?? t before it looks for media for exactly that reason; the library's includes.medias(t) on a retweet behaves the same way, so a port that got it right before will need the same two-level lookup here.

Almost nothing is plain text. Only 4.8% of the 1,000 posts had no media, no link, no quoted or retweeted post, no card and were not a reply. A port that treats these fields as rare edge cases will be wrong on 19 posts in 20. The card object is the one field with no counterpart in the library's v2 types: it is the link preview X renders (title, description, image URLs under binding_values), present on 45.9% of posts and on most posts that contain a URL. Median text length was 154 characters, 9.0% of posts exceeded 280 (long-form posts return their full text in text), and 1.6% carried an article object.

viewCount is zero on old posts, not on random ones. viewCount was present on 100% of posts but greater than zero on only 66.4%. The split is exact: of the 336 posts created before 2023, 100% report viewCount: 0; of the 664 posts from 2023 on, 0% do, and their median is 59,248 views. X rolled view counts out on December 22, 2022, and press coverage of the launch (TechCrunch) noted it applied only to posts from mid-December 2022 on; older posts simply have no number. Two of our five accounts post rarely enough that 200 posts reach back years (191 of @npmjs's 200 and 145 of @typescript's are pre-2023), which is why their median viewCount is 0 while @github's is 81,557 and @vercel's 83,968. Map viewCount to impression_count, but treat 0 as "not available" when the post predates 2023, which the mapping function below does with t.viewCount || null. likeCount has no such gap: 99.9% of posts had at least one like, median 179, 90th percentile 1,042, maximum 10,598.

Views per like, for sanity checks. Across the 664 posts with a view count, the median post collected 0.36 likes per 100 views, or about 274 views per like. If a port's engagement-rate code suddenly reports 100% because it divided by a zero viewCount, this is why.

Quoted posts are rare everywhere: 2.0% for @nodejs and @npmjs, 3.0% for @vercel, 4.0% for @github, 5.0% for @typescript, 3.2% overall. Engagement, by contrast, depends on how far back 200 posts reach:

The spread is the point. @nodejs is 46.0% reposts, so most of its media is one level down; @github attaches media to 59.0% of its posts and almost never links out through a card; @typescript links in 84.5% of posts. A mapping tested only against one account will pass and then break on the next. Test the port on the accounts you will actually read, and keep the de-identified per-post rows in sample.json if you want to re-run the counts.

What the study cost, both ways. 1,000 posts over 50 requests was 15,000 credits, $0.15, on TwitterAPI.io. The same 1,000 post reads on the official pay-per-usage rate card are $5.00, before the developer app and the first card. The 20-tweets-per-page figure held on all 50 pages, so budget 50 requests per 1,000 timeline posts; at the paid rate limit of 20 requests per second that is a few seconds, and at the pre-payment 0.2 per second about four minutes.

Plenty of teams run both: the library for the OAuth 2.0 user features their product needs, fetch against TwitterAPI.io for the read volume that would otherwise dominate the X bill. The interfaces below are derived from the response shapes in the study, so they match what the endpoints return rather than what the OpenAPI spec promises; keep viewCount and the nested objects optional.

ESM or CommonJS. The examples use top-level await, which needs an .mjs file or "type": "module" in package.json. In CommonJS wrap them in an async function main(). fetch is global from Node 18; on older runtimes install undici and import it.

Question: for a Node developer porting twitter-api-v2 code that relies on expansions and includes, which TwitterAPI.io tweet fields are populated and how often: media on the post and on its repost, links, quoted and retweeted posts, replies, cards, author fields, createdAt format, the viewCount versus likeCount distributions, and the number of tweets per page.

Accounts: five public organization accounts: @nodejs, @npmjs, @github, @vercel and @typescript.

Method: /twitter/user/last_tweets with the default includeReplies (replies excluded), 10 pages of 20 per account, newest first: 50 requests, 1,000 posts, collected in 2026 through a rate-limited, read-only client. Each post was reduced to a row of booleans and counts (media on the post, media on its retweeted_tweet, URLs, hashtags, mentions, quoted, retweeted, reply, card, place, article, author fields present, createdAt parseable, viewCount, likeCount, text length) and aggregated per account and overall. The viewCount era split uses the post's own createdAt with January 2023 as the boundary.

What the sample cannot show: 200 posts per account is a snapshot, and for the two quieter accounts it reaches back several years, which is what exposed the viewCount boundary but also means their engagement medians describe old posts. Five organization accounts are not individuals, news accounts or reply-heavy accounts; a timeline fetched with includeReplies=true, or a keyword search, will have a reply share far above the 0% here and probably a different media share. The field shares are about availability, not about what X's own API would have returned for the same posts, which we did not fetch. Library facts (version, downloads, stars, method names) were read from the npm registry and the GitHub repository at review time and will drift.

Aggregates only. The accounts named are organizations; no individual's posts were analyzed. The analysis script, results, de-identified per-post rows and the gzip-compressed raw pages for these organization accounts are kept with the study.