DEV Community

Cover image for How to Search Tweets with twitter-api-v2 in Node.js (2026)
XCROP
XCROP

Posted on Originally published at xcrop.io

How to Search Tweets with twitter-api-v2 in Node.js (2026)

Searching Tweets with twitter-api-v2

twitter-api-v2 is the most popular Node.js/TypeScript client for the X (Twitter) API, and searching recent tweets is one of the first things most developers reach for. It's also where people hit the most friction: the method returns a paginator, not a plain array, so getting to the actual tweets (tweets.data.data) and paging through results trips up newcomers constantly

This guide walks through searching tweets with twitter-api-v2 end to end: authenticating, calling client.v2.search(), reading the results correctly, paginating, the query operators worth knowing, and the rate-limit/cost realities. At the end we look at a simpler alternative for when the official API's setup and pricing are more than your project needs

Installing and Authenticating

npm install twitter-api-v2
Enter fullscreen mode Exit fullscreen mode

Recent tweet search is app-only, so all you need is a Bearer token from the X developer portal. No user OAuth flow required:

import { TwitterApi } from 'twitter-api-v2';

// App-only client from a Bearer token
const client = new TwitterApi(process.env.X_BEARER_TOKEN);

// Use the read-only sub-client for search/lookups
const roClient = client.readOnly;
Enter fullscreen mode Exit fullscreen mode

Two things to know up front:

  • Recent search covers the last 7 days only. The full-archive endpoint requires an elevated (Pro/Enterprise or Academic) access level
  • Your access tier determines your rate limits and how many tweets you can pull per month

Your First Search: client.v2.search()

const results = await roClient.v2.search('javascript lang:en -is:retweet', {
  'tweet.fields': ['created_at', 'public_metrics', 'author_id'],
  max_results: 100, // 10-100 per page
});
Enter fullscreen mode Exit fullscreen mode

The first argument is your query string (operators covered below). The options object mirrors the API's query params: tweet.fields, user.fields, expansions, start_time, end_time, and max_results (capped at 100 per request)

Reading the Results: the tweets.data.data Gotcha

client.v2.search() does not return an array of tweets. It returns a TweetSearchRecentV2Paginator. There are three correct ways to read it, and mixing them up is the single most common source of confusion:

// 1. Recommended - .tweets is every tweet fetched so far, as a flat array
for (const tweet of results.tweets) {
  console.log(tweet.id, tweet.text);
}

// 2. The RAW current-page payload - this is where "tweets.data.data" comes from
console.log(results.data.data);  // TweetV2[] for the current page
console.log(results.data.meta);  // { result_count, newest_id, next_token, ... }

// 3. Async iterator - automatically pages through results (mind rate limits)
for await (const tweet of results) {
  console.log(tweet.text);
}
Enter fullscreen mode Exit fullscreen mode

Why does results.data.data have a double .data? The paginator's .data property is the raw API response, shaped like { data: Tweet[], meta: {...}, includes: {...} }. So .data.data is the tweet array nested inside that response. Stick with results.tweets in application code, and reach for results.data.data only when you need the raw page exactly as the API returned it

Guard against empty results. When a search matches nothing, result_count is 0 and results.data.data can be undefined:

if (!results.meta.result_count) {
  console.log('No tweets matched.');
} else {
  for (const tweet of results.tweets) console.log(tweet.text);
}
Enter fullscreen mode Exit fullscreen mode

Pagination: Getting More Than One Page

Each request returns at most 100 tweets. The paginator handles the rest for you:

// Fetch one more page and merge it into results.tweets
await results.fetchNext();

// Keep fetching until you have ~1000 tweets (or the pages run out)
await results.fetchLast(1000);

console.log('Collected ' + results.tweets.length + ' tweets');
console.log('Exhausted?', results.done);
Enter fullscreen mode Exit fullscreen mode

The async iterator (for await ... of results) pages automatically. That's convenient, but it will happily burn through your rate limit on a broad query, so cap it yourself

Search Query Operators Worth Knowing

The query string is where most of the power lives:

Operator Matches
from:username Tweets from a specific account
to:username Replies directed at an account
#hashtag A hashtag
"exact phrase" An exact phrase
-keyword Excludes a keyword
lang:en A specific language
-is:retweet Excludes retweets
is:reply / -is:reply Only / no replies
has:media / has:links Tweets containing media / links
url:"github.com" Tweets linking a domain

Combine them freely: from:vitalikbuterin (ethereum OR rollup) -is:retweet has:links

Rate Limits and the Cost Problem

This is where teams get stuck. Recent search on the X API v2 is rate-limited per 15-minute window and capped by a monthly tweet-pull quota tied to your plan. In practice:

  • The Basic tier runs $200/month and still caps how many tweets you can retrieve
  • Recent search only reaches back 7 days; historical work needs the pricier full-archive access
  • Hitting the ceiling means 429 responses and building backoff, queueing, and quota tracking around them

For a detailed breakdown see our guides on X API pricing and rate limits

Other Recipes You Will Need Next

Search is rarely the only call. These are the four that follow it in almost every project

Pull a user's timeline

const timeline = await roClient.v2.userTimeline('44196397', {
  max_results: 100,
  'tweet.fields': ['created_at', 'public_metrics'],
  exclude: ['retweets', 'replies'],
});

for (const tweet of timeline.tweets) console.log(tweet.text);
Enter fullscreen mode Exit fullscreen mode

Note that userTimeline takes a numeric user id, not a handle. Resolving the handle first costs you an extra call

Resolve handles to ids

const user = await roClient.v2.userByUsername('elonmusk', {
  'user.fields': ['public_metrics', 'created_at', 'description'],
});
console.log(user.data.id, user.data.public_metrics.followers_count);

// Up to 100 at once
const many = await roClient.v2.usersByUsernames(['elonmusk', 'vitalikbuterin']);
Enter fullscreen mode Exit fullscreen mode

Read followers

const followers = await roClient.v2.followers('44196397', {
  max_results: 1000,
  'user.fields': ['public_metrics'],
  asPaginator: true,
});
Enter fullscreen mode Exit fullscreen mode

Followers is one of the tightest limits on the official API: 15 requests per 15 minutes on most tiers, so a 100k-follower account takes hours to page through

Filter by engagement, and why it silently fails

This is the trap that costs people the most time:

// Looks right. Does NOT work on API v2.
const results = await roClient.v2.search('solana min_faves:100');
Enter fullscreen mode Exit fullscreen mode

min_faves:, min_retweets: and min_replies: work in the web search box but are silently ignored by API v2. No error, no warning, just unfiltered results. Your options are to filter client-side after fetching (paying for every tweet you throw away), or to use a provider whose search speaks the full web operator set

Common Errors and Fixes

  • 401 Unauthorized: bad or missing Bearer token, or your app lacks read access. Regenerate the token and double-check the project's permissions
  • 403 Forbidden: your access tier can't use this endpoint (recent search needs Basic+, full-archive needs Pro/Academic)
  • 429 Too Many Requests: you're rate-limited. Read the x-rate-limit-reset header and back off with jitter
  • results.data.data is undefined: the search matched nothing, so check results.meta.result_count before indexing

A Simpler Alternative: XCROP

If the developer-app setup, the 7-day window, and the $200/month floor are more than your project needs, XCROP exposes the same tweet-search capability behind a single API key. No OAuth app, no Bearer-token juggling, and credit-based pricing that costs a fraction of the official API

curl -X POST https://xcrop.io/api/v2/search \
  -H "Authorization: Bearer xc_live_..." \
  -H "Content-Type: application/json" \
  -d '{"query": "javascript lang:en", "count": 100, "sort": "latest"}'
Enter fullscreen mode Exit fullscreen mode

The response is plain JSON: a data array of tweets plus a meta object with the cursor, so there is no paginator and no .data.data to unwrap:

const res = await fetch('https://xcrop.io/api/v2/search', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + process.env.XCROP_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ query: 'javascript lang:en', count: 100, sort: 'latest' }),
});

const { data } = await res.json();
for (const tweet of data) console.log(tweet.text);
Enter fullscreen mode Exit fullscreen mode

You can sort by latest, engagement, or media, filter by min_likes / min_retweets / lang, and request up to 1,000 results in a single call. See every parameter in the interactive builder

Which Should You Use?

twitter-api-v2 (official) XCROP
Setup Developer app + Bearer token One API key
Auth OAuth / app-only token Bearer key in a header
Results shape Paginator (.tweets / .data.data) Plain JSON (data array + meta)
Search window 7 days (recent tier) Recent + trending coverage
Per-request cap 100 tweets Up to 1,000
Pricing From $200/mo (Basic) Free tier, then credit-based
Best for Deep X-native integrations Fast data pulls without the API-tier tax

If you're building a product deeply tied to the X platform, the official twitter-api-v2 library is the right tool. If you just need clean tweet data for a dashboard, a bot, research, or a side project, and you'd rather not wrestle with paginators, OAuth apps, and a $200/month minimum, XCROP gets you there in one curl

FAQ

What is tweets.data.data in twitter-api-v2?

It is the raw payload of the current page inside the paginator object. client.v2.search() returns a TweetSearchRecentV2Paginator, not an array: results.data is the API response and results.data.data is the TweetV2 array inside it. In application code you almost always want results.tweets instead, which flattens every page fetched so far

Why is data.data undefined after a search?

The search matched zero tweets. When nothing matches, result_count is 0 and results.data.data can be undefined, so check results.meta.result_count before you index into it

How far back can client.v2.search() go?

Seven days. Recent search only covers the last week; anything older needs full-archive search, which sits behind the Pro or Academic access tier

How many tweets can you get per call?

One hundred at most, set through max_results, then you paginate. Call results.fetchNext() for one more page or results.fetchLast(1000) to keep fetching toward a target count

Does twitter-api-v2 handle rate limits for you?

No. The library surfaces the rate-limit headers and throws on a 429, but the backoff is yours to write. Read x-rate-limit-reset and wait for the window rather than retrying immediately

Why does min_faves not work in API v2 search?

min_faves, min_retweets and min_replies work in the web search box but are silently ignored by API v2. There is no error, just unfiltered results, so you either filter client-side after fetching or use a provider whose search accepts the full web operator set


Originally published on the XCROP blog.

Top comments (0)