<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0"><channel><title><![CDATA[XCROP Blog]]></title><description><![CDATA[XCROP Blog]]></description><link>https://xcrop.hashnode.dev</link><image><url>https://cdn.hashnode.com/uploads/logos/6affed10c92f649a80167e86/ccefdf0a-77d3-427c-9709-7e0f60781137.png</url><title>XCROP Blog</title><link>https://xcrop.hashnode.dev</link></image><generator>RSS for Node</generator><lastBuildDate>Fri, 20 Nov 2026 15:47:03 GMT</lastBuildDate><atom:link href="https://xcrop.hashnode.dev/rss.xml" rel="self" type="application/rss+xml"/><language><![CDATA[en]]></language><ttl>60</ttl><item><title><![CDATA[Getting Started with XCROP API in 5 Minutes]]></title><description><![CDATA[From zero to your first API call in under 5 minutes: signup, API key, request examples in cURL, JavaScript and Python, plus pagination]]></description><link>https://xcrop.hashnode.dev/getting-started-with-xcrop-api-in-5-minutes</link><guid isPermaLink="true">https://xcrop.hashnode.dev/getting-started-with-xcrop-api-in-5-minutes</guid><category><![CDATA[api]]></category><category><![CDATA[Tutorial]]></category><category><![CDATA[quickstart]]></category><dc:creator><![CDATA[XCROP]]></dc:creator><pubDate>Fri, 20 Nov 2026 07:02:34 GMT</pubDate><content:encoded><![CDATA[<h2>Why XCROP?</h2>
<p>XCROP is an X (formerly Twitter) data API built for crypto traders, researchers, and builders. It covers 58 endpoints, interaction verification, and credit-based pricing that's up to 50% cheaper than comparable third-party X APIs, so you get crypto social intelligence without the usual API tax</p>
<p>In this guide, you'll go from zero to your first API call in under 5 minutes</p>
<h2>Step 1: Create Your Account</h2>
<p>Head to the signup page and create your account. You'll get <strong>5,000 free credits</strong> on the Starter plan, plenty to explore the API and test your integration</p>
<h3>What You Get on Starter</h3>
<ul>
<li>5,000 monthly credits</li>
<li>60 requests per minute</li>
<li>Up to 1,000 results per call</li>
<li>Access to all endpoints</li>
</ul>
<h2>Step 2: Generate an API Key</h2>
<p>After logging in, open the <strong>API Keys</strong> tab in the <strong>Dashboard</strong> and click <strong>Create New Key</strong>. Your API key will look like this:</p>
<pre><code>xc_live_a1b2c3d4e5f6g7h8i9j0...
</code></pre>
<p>Store this key securely, treat it like a password. Never commit it to version control or expose it in client-side code</p>
<h3>Environment Variables</h3>
<pre><code class="language-bash"># .env
XCROP_API_KEY=xc_live_your_api_key_here
</code></pre>
<h2>Step 3: Make Your First Request</h2>
<p>Let's fetch an X user's profile. Here's how in cURL, JavaScript, and Python:</p>
<h3>cURL</h3>
<pre><code class="language-bash">curl -X GET "https://xcrop.io/api/v2/users/elonmusk" \
  -H "Authorization: Bearer xc_live_your_key"
</code></pre>
<h3>JavaScript</h3>
<pre><code class="language-javascript">const response = await fetch("https://xcrop.io/api/v2/users/elonmusk", {
  headers: {
    "Authorization": "Bearer " + process.env.XCROP_API_KEY
  }
});

const result = await response.json();
console.log(result.data.name);      // "Elon Musk"
console.log(result.data.followers);  // 200000000+
</code></pre>
<h3>Python</h3>
<pre><code class="language-python">import requests
import os

response = requests.get(
    "https://xcrop.io/api/v2/users/elonmusk",
    headers={"Authorization": "Bearer " + os.environ["XCROP_API_KEY"]}
)

user = response.json()["data"]
print(user["name"])       # Elon Musk
print(user["followers"])  # 200000000+
</code></pre>
<h2>Step 4: Understanding Response Structure</h2>
<p>Every XCROP response follows a consistent format:</p>
<pre><code class="language-json">{
  "data": { ... },
  "meta": {
    "total": 20,
    "next_cursor": "abc123...",
    "has_next_page": true,
    "latency_ms": 245
  }
}
</code></pre>
<ul>
<li><strong>data</strong>: the actual payload (object or array depending on endpoint)</li>
<li><strong>meta.total</strong>: number of results returned</li>
<li><strong>meta.next_cursor</strong>: pagination cursor for fetching the next page</li>
<li><strong>meta.has_next_page</strong>: whether more results are available</li>
</ul>
<h3>Pagination</h3>
<p>For list endpoints (tweets, followers, etc.), use the <code>next_cursor</code> to page through results:</p>
<pre><code class="language-python">import requests
import os

url = "https://xcrop.io/api/v2/users/elonmusk/tweets"
headers = {"Authorization": "Bearer " + os.environ["XCROP_API_KEY"]}
all_tweets = []
cursor = None

for page in range(3):  # Fetch 3 pages
    params = {"count": 20}
    if cursor:
        params["cursor"] = cursor

    response = requests.get(url, headers=headers, params=params)
    result = response.json()

    all_tweets.extend(result["data"])
    cursor = result["meta"].get("next_cursor")

    if not cursor:
        break

print("Total tweets fetched: " + str(len(all_tweets)))
</code></pre>
<h2>Step 5: Monitor Your Usage</h2>
<p>Check your credit consumption in the Dashboard (Usage tab). Each response also carries headers you can use for pacing:</p>
<ul>
<li><code>X-RateLimit-Remaining</code>: requests left in the current minute window</li>
<li><code>X-Response-Time</code>: how long the request took</li>
<li><code>X-MaxResults-Allowed</code>: the most results one request can return (1,000 on every plan)</li>
</ul>
<h3>Credit Costs at a Glance</h3>
<table>
<thead>
<tr>
<th>Endpoint</th>
<th>Credits</th>
</tr>
</thead>
<tbody><tr>
<td>User profile</td>
<td>18 per profile</td>
</tr>
<tr>
<td>Batch user lookup (POST /users/batch)</td>
<td>1 per user returned (10 per call minimum)</td>
</tr>
<tr>
<td>Tweet / search result</td>
<td>15 per result</td>
</tr>
<tr>
<td>Follower / following</td>
<td>1 per result</td>
</tr>
<tr>
<td>Trending topics</td>
<td>100 per call (flat)</td>
</tr>
<tr>
<td>Write operations</td>
<td>100 per operation (flat)</td>
</tr>
<tr>
<td>Minimum per call</td>
<td>10 credits</td>
</tr>
</tbody></table>
<h2>Tips for Success</h2>
<ol>
<li><strong>Use environment variables</strong>: never hardcode API keys in source code</li>
<li><strong>Handle rate limits</strong>: check for 429 status and implement exponential backoff</li>
<li><strong>Cache responses</strong>: don't re-fetch data that hasn't changed</li>
<li><strong>Use batch endpoints</strong>: look up 100 users or tweets in a single call</li>
<li><strong>Try the Endpoints</strong>: test any endpoint interactively before writing code</li>
</ol>
<h2>What's Next?</h2>
<p>Now that you're set up, explore these topics:</p>
<ul>
<li><strong>KOL Tracking</strong>: monitor crypto influencers in real-time</li>
<li><strong>Trending Topics</strong>: spot emerging narratives before they peak</li>
<li><strong>Search</strong>: find any tweet or user with powerful filters</li>
<li><strong>Write API</strong>: automate posting to X via your connected account</li>
</ul>
<hr />
<p><em>Originally published on the <a href="https://xcrop.io/blog/getting-started-5-minutes">XCROP blog</a>.</em></p>
]]></content:encoded></item><item><title><![CDATA[Giveaway Verification API: Check Retweets, Replies, Follows]]></title><description><![CDATA[Verify giveaway, airdrop and NFT whitelist entries on X automatically. Check if a user retweeted, replied, quoted or follows you, from $0.25 per 1K checks]]></description><link>https://xcrop.hashnode.dev/giveaway-verification-api-check-retweets-replies-follows</link><guid isPermaLink="true">https://xcrop.hashnode.dev/giveaway-verification-api-check-retweets-replies-follows</guid><category><![CDATA[api]]></category><category><![CDATA[Tutorial]]></category><category><![CDATA[crypto]]></category><category><![CDATA[airdrop]]></category><dc:creator><![CDATA[XCROP]]></dc:creator><pubDate>Fri, 20 Nov 2026 07:01:45 GMT</pubDate><content:encoded><![CDATA[<h2>The Problem: Manual Verification Doesn't Scale</h2>
<p>Running an airdrop, giveaway or NFT whitelist on X? You've probably seen the drill:</p>
<ol>
<li>Post a tweet: "Retweet + Reply (tag 3 friends) + Follow to enter"</li>
<li>Thousands of entries flood in</li>
<li>Now... <strong>how do you verify all of them?</strong></li>
</ol>
<p>Manually checking 5,000 retweets and 5,000 replies is impossible. Many projects resort to random selection (unfair) or trusting participants (exploitable). Bots and fake entries slip through</p>
<p><strong>XCROP's Interaction Check API solves this.</strong> Seven dedicated endpoints let you programmatically verify every single participant (retweets, replies, quotes, follow relationships, and account-quality filters) in minutes</p>
<h2>The 7 Interaction Check Endpoints</h2>
<table>
<thead>
<tr>
<th>Endpoint</th>
<th>What it checks</th>
<th>Credits</th>
</tr>
</thead>
<tbody><tr>
<td><code>GET /v2/tweets/:tweetId/check-retweet</code></td>
<td>Did user retweet?</td>
<td>50</td>
</tr>
<tr>
<td><code>GET /v2/tweets/:tweetId/check-reply</code></td>
<td>Did user reply? (+ tag verification)</td>
<td>50</td>
</tr>
<tr>
<td><code>GET /v2/tweets/:tweetId/check-quote</code></td>
<td>Did user quote-tweet? (+ tag verification)</td>
<td>50</td>
</tr>
<tr>
<td><code>GET /v2/users/:username/check-qualified-account</code></td>
<td>Account old enough / enough followers?</td>
<td>50</td>
</tr>
<tr>
<td><code>GET /v2/users/:username/check-qualified-name</code></td>
<td>Display name contains required text?</td>
<td>50</td>
</tr>
<tr>
<td><code>GET /v2/users/check-follow</code></td>
<td>Does user follow you?</td>
<td>50</td>
</tr>
<tr>
<td><code>GET /v2/users/:username/check-median-views</code></td>
<td>Do people see the account's recent posts? (median views, filters bots)</td>
<td>200 to 400</td>
</tr>
</tbody></table>
<p>Every endpoint returns a simple boolean result (<code>qualified</code> for the eligibility checks), no complex parsing needed</p>
<blockquote>
<p><strong>Note on likes:</strong> X removed public like visibility in June 2024, so like-checking is not offered. Use retweet, reply, and quote checks instead, plus the qualified-account checks above to filter bot entries by account age, follower count, or display-name requirements</p>
</blockquote>
<h2>Quick Start: Verify a Single User</h2>
<pre><code class="language-python">import requests
import os

API_KEY = os.environ["XCROP_API_KEY"]
HEADERS = {"Authorization": "Bearer " + API_KEY}
BASE = "https://xcrop.io/api/v2"
TWEET_ID = "1893045621038174208"

# Check retweet
rt = requests.get(
    BASE + "/tweets/" + TWEET_ID + "/check-retweet",
    headers=HEADERS,
    params={"username": "alice_crypto"}
).json()
print("Retweeted:", rt["data"]["retweeted"])

# Check reply with 3 friend tags required
reply = requests.get(
    BASE + "/tweets/" + TWEET_ID + "/check-reply",
    headers=HEADERS,
    params={"username": "alice_crypto", "min_tags": 3}
).json()
print("Replied:", reply["data"]["replied"])
print("Tags met:", reply["data"]["tags_met"])

# Check follow relationship
follow = requests.get(
    BASE + "/users/check-follow",
    headers=HEADERS,
    params={"source": "alice_crypto", "target": "your_project"}
).json()
print("Follows you:", follow["data"]["source_follows_target"])
</code></pre>
<h2>Bulk Verification: Check All Participants</h2>
<p>Here's a complete script to verify an entire airdrop campaign:</p>
<pre><code class="language-python">import requests
import time
import os
import json

API_KEY = os.environ["XCROP_API_KEY"]
HEADERS = {"Authorization": "Bearer " + API_KEY}
BASE = "https://xcrop.io/api/v2"

TWEET_ID = "1893045621038174208"
PROJECT_USERNAME = "your_project"
MIN_TAGS = 3

# List of participants (from your entry collection system)
participants = ["alice_crypto", "bob_defi", "charlie_nft"]  # ... thousands more

def verify_participant(username):
    """Check all conditions for a single participant."""
    result = {"username": username, "passed": False}

    # A 503 means the upstream read could not be completed, NOT that the user did nothing. Retry it
    # rather than reading a missing "data" key, or one bad minute disqualifies real entrants.
    def get(path, params, tries=3):
        for attempt in range(tries):
            resp = requests.get(BASE + path, headers=HEADERS, params=params)
            if resp.status_code == 503:
                time.sleep(int(resp.headers.get("Retry-After", 5)))
                continue
            resp.raise_for_status()
            return resp.json()["data"]
        raise RuntimeError("upstream busy for " + path)

    # 1. Check retweet
    result["retweeted"] = get(
        "/tweets/" + TWEET_ID + "/check-retweet", {"username": username}
    )["retweeted"]

    # 2. Check reply with friend tags
    reply = get(
        "/tweets/" + TWEET_ID + "/check-reply",
        {"username": username, "min_tags": MIN_TAGS}
    )
    result["replied"] = reply["replied"]
    result["tags_met"] = reply.get("tags_met", False)

    # 3. Check follow
    result["follows"] = get(
        "/users/check-follow", {"source": username, "target": PROJECT_USERNAME}
    )["source_follows_target"]

    # All conditions met?
    result["passed"] = (
        result["retweeted"]
        and result["replied"]
        and result["tags_met"]
        and result["follows"]
    )

    return result

# Verify all participants
verified = []
for i, user in enumerate(participants):
    try:
        result = verify_participant(user)
        verified.append(result)
        status = "PASS" if result["passed"] else "FAIL"
        print("[" + str(i + 1) + "/" + str(len(participants)) + "] @" + user + ": " + status)
    except Exception as e:
        print("[" + str(i + 1) + "] @" + user + ": ERROR - " + str(e))
    time.sleep(0.1)  # Be gentle with rate limits

# Results
winners = [r for r in verified if r["passed"]]
print("\nTotal checked:", len(verified))
print("Qualified:", len(winners))
print("Disqualified:", len(verified) - len(winners))

# Save results
with open("airdrop_results.json", "w") as f:
    json.dump({"winners": winners, "all": verified}, f, indent=2)
</code></pre>
<h2>Tag Verification: Prevent Fake Entries</h2>
<p>A common giveaway rule is "Reply and tag 3 friends." The <code>check-reply</code> and <code>check-quote</code> endpoints support the <code>min_tags</code> parameter to verify this automatically:</p>
<pre><code class="language-python"># Require at least 3 friend tags in the reply
response = requests.get(
    BASE + "/tweets/" + TWEET_ID + "/check-reply",
    headers=HEADERS,
    params={"username": "alice_crypto", "min_tags": 3}
).json()

data = response["data"]
print("Replied:", data["replied"])
print("Tags required:", data["tags_required"])  # 3
print("Tags found:", data["tags_found"])         # 4
print("Tags met:", data["tags_met"])             # True
</code></pre>
<p>The tag count <strong>excludes the original tweet author</strong>. So if your tweet is from <code>@project</code> and Alice replies "<code>@project</code> <code>@bob</code> <code>@carol</code> <code>@dave</code>", the tag count is 3 (bob, carol, dave), not 4</p>
<h2>Whitelist Verification at Submission Time</h2>
<p>Checking everyone after the deadline suits a giveaway. NFT whitelists usually work the other way: a participant connects a wallet, enters an X handle and expects a pass or fail on the spot. The same endpoints cover that flow, called from your backend when the form is submitted:</p>
<pre><code class="language-javascript">// Run this in your form handler on the server. Calling XCROP from the browser would expose your API key.
async function checkWhitelistTasks(handle) {
  const headers = { Authorization: "Bearer " + process.env.XCROP_API_KEY };
  const base = "https://xcrop.io/api/v2";

  // 503 = the upstream read did not complete. It is not a "no", so it must not read as one.
  const get = async (url) =&gt; {
    const r = await fetch(url, { headers });
    const body = await r.json();
    // 503 = read did not complete, retry. 422 = the account itself cannot be read (protected, suspended,
    // withheld), so retrying never helps. Neither is billed, and neither means "the user did nothing".
    if (!r.ok) throw new Error(body.code || ("HTTP " + r.status));
    return body.data;
  };

  const [follow, retweet, reply] = await Promise.all([
    get(base + "/users/check-follow?source=" + handle + "&amp;target=your_project"),
    get(base + "/tweets/" + TWEET_ID + "/check-retweet?username=" + handle),
    get(base + "/tweets/" + TWEET_ID + "/check-reply?username=" + handle + "&amp;min_tags=2"),
  ]);

  // Report each task separately so the user knows what to fix.
  return {
    follows: follow.source_follows_target,
    retweeted: retweet.retweeted,
    replied: reply.verified, // replied AND met min_tags
  };
}
</code></pre>
<p>A few things matter once a real person is waiting on the answer:</p>
<ul>
<li><strong>Use a timeout and retry once.</strong> Most checks return in under 3 seconds, but the odd one is slower. One quiet retry is better than showing a failure</li>
<li><strong>Say which task is missing.</strong> "You still need to retweet" gets a resubmission. A bare "not eligible" gets a support ticket</li>
<li><strong>Re-check before the snapshot.</strong> Some people unfollow right after they are approved. Run the bulk script above once more before you lock the list</li>
<li><strong>Plan for launch day.</strong> The Pro plan allows 600 requests per minute, which is about 200 three-task submissions a minute</li>
</ul>
<h2>JavaScript / Node.js Example</h2>
<pre><code class="language-javascript">const API_KEY = process.env.XCROP_API_KEY;
const BASE = "https://xcrop.io/api/v2";
const TWEET_ID = "1893045621038174208";

async function checkInteractions(username) {
  const headers = { Authorization: "Bearer " + API_KEY };

  // 503 = the upstream read did not complete. It is not a "no", so it must not read as one.
  const get = async (url) =&gt; {
    const r = await fetch(url, { headers });
    const body = await r.json();
    // 503 = read did not complete, retry. 422 = the account itself cannot be read (protected, suspended,
    // withheld), so retrying never helps. Neither is billed, and neither means "the user did nothing".
    if (!r.ok) throw new Error(body.code || ("HTTP " + r.status));
    return body.data;
  };

  const [retweet, reply, relationship] = await Promise.all([
    get(BASE + "/tweets/" + TWEET_ID + "/check-retweet?username=" + username),
    get(BASE + "/tweets/" + TWEET_ID + "/check-reply?username=" + username + "&amp;min_tags=3"),
    get(BASE + "/users/check-follow?source=" + username + "&amp;target=your_project"),
  ]);

  return {
    username,
    retweeted: retweet.retweeted,
    replied: reply.replied,
    tags_met: reply.tags_met,
    follows: relationship.source_follows_target,
    qualified: retweet.retweeted &amp;&amp; reply.replied &amp;&amp; reply.tags_met &amp;&amp; relationship.source_follows_target,
  };
}

// Verify participants in parallel (batches of 10)
async function verifyAll(participants) {
  const results = [];
  for (let i = 0; i &lt; participants.length; i += 10) {
    const batch = participants.slice(i, i + 10);
    const batchResults = await Promise.all(batch.map(checkInteractions));
    results.push(...batchResults);
    console.log("Checked " + results.length + "/" + participants.length);
  }
  return results;
}
</code></pre>
<h2>Cost Estimation</h2>
<p>Each interaction check costs <strong>50 credits</strong> (the median views check is the exception: 200 to 400 credits by posts read). Here's what a typical campaign costs:</p>
<table>
<thead>
<tr>
<th>Campaign size</th>
<th>Checks per user</th>
<th>Total requests</th>
<th>Credits</th>
<th>Cost (Pro)</th>
</tr>
</thead>
<tbody><tr>
<td>1,000 users</td>
<td>3 (RT + Reply + Follow)</td>
<td>3,000</td>
<td>150K</td>
<td>$0.75</td>
</tr>
<tr>
<td>5,000 users</td>
<td>3</td>
<td>15,000</td>
<td>750K</td>
<td>$3.75</td>
</tr>
<tr>
<td>5,000 users</td>
<td>2 (RT + Reply)</td>
<td>10,000</td>
<td>500K</td>
<td>$2.50</td>
</tr>
<tr>
<td>10,000 users</td>
<td>3</td>
<td>30,000</td>
<td>1.5M</td>
<td>$7.50</td>
</tr>
</tbody></table>
<p>That works out to about <strong>$0.25 per 1,000 checks</strong> on Pro (50,000 credits), or about $0.35 on Basic</p>
<p>With the <strong>Pro plan</strong> ($9.90/month or $95.04/yr if you pay yearly, includes 2M credits), you can verify ~13,000 users with all 3 checks included in your monthly allowance</p>
<p><strong>Pay as You Go</strong> credit packs start at $2.90 for 400K credits (~2,600 full verifications)</p>
<h2>Best Practices</h2>
<ol>
<li><strong>Batch with delays</strong>: Add 100ms between requests to stay within rate limits</li>
<li><strong>Run checks in parallel</strong>: Use <code>Promise.all</code> (JS) or <code>asyncio</code> (Python) for 3 checks per user simultaneously</li>
<li><strong>Cache results</strong>: Store verification results to avoid re-checking the same user</li>
<li><strong>Set a deadline</strong>: Run verification after the campaign ends, not during. This ensures all entries are captured</li>
<li><strong>Use min_tags wisely</strong>: Set it to match your campaign rules exactly. Don't over-require</li>
<li><strong>Handle edge cases</strong>: Some users change usernames or go private after entering. Catch errors gracefully</li>
<li><strong>Export results</strong>: Save to JSON/CSV for transparency and dispute resolution</li>
</ol>
<h2>FAQ</h2>
<p><strong>How do I check if a user retweeted a tweet with an API?</strong></p>
<p>Call GET /v2/tweets/:tweetId/check-retweet with the username. It returns retweeted as true or false and costs 50 credits. Replies (check-reply), quotes (check-quote) and follows (check-follow) work the same way</p>
<p><strong>Can I use this to verify an NFT whitelist?</strong></p>
<p>Yes. Call the checks from your backend when someone submits their X handle, tell them which task is still missing, and run the checks again before the final snapshot, since some people unfollow after they are approved</p>
<p><strong>How much does giveaway verification cost?</strong></p>
<p>Each check costs 50 credits, about $0.25 per 1,000 checks on the Pro plan. Verifying 1,000 entrants on retweet, reply and follow is 150,000 credits, roughly $0.75</p>
<p><strong>Can the API check likes?</strong></p>
<p>No. X made likes private in June 2024, so no API can verify them reliably. Use retweet, reply, quote and follow checks instead</p>
<hr />
<p><em>Originally published on the <a href="https://xcrop.io/blog/interaction-check-airdrop-verification">XCROP blog</a>.</em></p>
]]></content:encoded></item><item><title><![CDATA[How to Search Tweets with twitter-api-v2 in Node.js (2026)]]></title><description><![CDATA[Searching tweets with the twitter-api-v2 Node.js library: client.v2.search(), the tweets.data.data gotcha, pagination, operators and rate limits]]></description><link>https://xcrop.hashnode.dev/how-to-search-tweets-with-twitter-api-v2-in-node-js-2026</link><guid isPermaLink="true">https://xcrop.hashnode.dev/how-to-search-tweets-with-twitter-api-v2-in-node-js-2026</guid><category><![CDATA[api]]></category><category><![CDATA[Tutorial]]></category><category><![CDATA[#TwitterAPI ]]></category><category><![CDATA[Node.js]]></category><dc:creator><![CDATA[XCROP]]></dc:creator><pubDate>Fri, 20 Nov 2026 06:57:49 GMT</pubDate><content:encoded><![CDATA[<h2>Searching Tweets with twitter-api-v2</h2>
<p><a href="https://github.com/PLhery/node-twitter-api-v2"><code>twitter-api-v2</code></a> 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 <em>paginator</em>, not a plain array, so getting to the actual tweets (<code>tweets.data.data</code>) and paging through results trips up newcomers constantly</p>
<p>This guide walks through searching tweets with <code>twitter-api-v2</code> end to end: authenticating, calling <code>client.v2.search()</code>, 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</p>
<h2>Installing and Authenticating</h2>
<pre><code class="language-bash">npm install twitter-api-v2
</code></pre>
<p>Recent tweet search is app-only, so all you need is a <strong>Bearer token</strong> from the X developer portal. No user OAuth flow required:</p>
<pre><code class="language-js">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;
</code></pre>
<p>Two things to know up front:</p>
<ul>
<li><strong>Recent search covers the last 7 days only.</strong> The full-archive endpoint requires an elevated (Pro/Enterprise or Academic) access level</li>
<li>Your <strong>access tier</strong> determines your rate limits and how many tweets you can pull per month</li>
</ul>
<h2>Your First Search: client.v2.search()</h2>
<pre><code class="language-js">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
});
</code></pre>
<p>The first argument is your query string (operators covered below). The options object mirrors the API's query params: <code>tweet.fields</code>, <code>user.fields</code>, <code>expansions</code>, <code>start_time</code>, <code>end_time</code>, and <code>max_results</code> (capped at 100 per request)</p>
<h2>Reading the Results: the tweets.data.data Gotcha</h2>
<p><code>client.v2.search()</code> does <strong>not</strong> return an array of tweets. It returns a <code>TweetSearchRecentV2Paginator</code>. There are three correct ways to read it, and mixing them up is the single most common source of confusion:</p>
<pre><code class="language-js">// 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);
}
</code></pre>
<p>Why does <code>results.data.data</code> have a double <code>.data</code>? The paginator's <code>.data</code> property is the <em>raw API response</em>, shaped like <code>{ data: Tweet[], meta: {...}, includes: {...} }</code>. So <code>.data.data</code> is the tweet array nested inside that response. Stick with <code>results.tweets</code> in application code, and reach for <code>results.data.data</code> only when you need the raw page exactly as the API returned it</p>
<p><strong>Guard against empty results.</strong> When a search matches nothing, <code>result_count</code> is <code>0</code> and <code>results.data.data</code> can be <code>undefined</code>:</p>
<pre><code class="language-js">if (!results.meta.result_count) {
  console.log('No tweets matched.');
} else {
  for (const tweet of results.tweets) console.log(tweet.text);
}
</code></pre>
<h2>Pagination: Getting More Than One Page</h2>
<p>Each request returns at most 100 tweets. The paginator handles the rest for you:</p>
<pre><code class="language-js">// 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);
</code></pre>
<p>The async iterator (<code>for await ... of results</code>) pages automatically. That's convenient, but it will happily burn through your rate limit on a broad query, so cap it yourself</p>
<h2>Search Query Operators Worth Knowing</h2>
<p>The query string is where most of the power lives:</p>
<table>
<thead>
<tr>
<th>Operator</th>
<th>Matches</th>
</tr>
</thead>
<tbody><tr>
<td><code>from:username</code></td>
<td>Tweets from a specific account</td>
</tr>
<tr>
<td><code>to:username</code></td>
<td>Replies directed at an account</td>
</tr>
<tr>
<td><code>#hashtag</code></td>
<td>A hashtag</td>
</tr>
<tr>
<td><code>"exact phrase"</code></td>
<td>An exact phrase</td>
</tr>
<tr>
<td><code>-keyword</code></td>
<td>Excludes a keyword</td>
</tr>
<tr>
<td><code>lang:en</code></td>
<td>A specific language</td>
</tr>
<tr>
<td><code>-is:retweet</code></td>
<td>Excludes retweets</td>
</tr>
<tr>
<td><code>is:reply</code> / <code>-is:reply</code></td>
<td>Only / no replies</td>
</tr>
<tr>
<td><code>has:media</code> / <code>has:links</code></td>
<td>Tweets containing media / links</td>
</tr>
<tr>
<td><code>url:"github.com"</code></td>
<td>Tweets linking a domain</td>
</tr>
</tbody></table>
<p>Combine them freely: <code>from:vitalikbuterin (ethereum OR rollup) -is:retweet has:links</code></p>
<h2>Rate Limits and the Cost Problem</h2>
<p>This is where teams get stuck. Recent search on the X API v2 is rate-limited per 15-minute window <em>and</em> capped by a monthly tweet-pull quota tied to your plan. In practice:</p>
<ul>
<li>The <strong>Basic</strong> tier runs <strong>$200/month</strong> and still caps how many tweets you can retrieve</li>
<li>Recent search only reaches back <strong>7 days</strong>; historical work needs the pricier full-archive access</li>
<li>Hitting the ceiling means <code>429</code> responses and building backoff, queueing, and quota tracking around them</li>
</ul>
<p>For a detailed breakdown see our guides on <a href="https://xcrop.io/blog/x-api-pricing-comparison-2026">X API pricing</a> and <a href="https://xcrop.io/blog/twitter-api-rate-limits-2026">rate limits</a></p>
<h2>Other Recipes You Will Need Next</h2>
<p>Search is rarely the only call. These are the four that follow it in almost every project</p>
<h3>Pull a user's timeline</h3>
<pre><code class="language-js">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);
</code></pre>
<p>Note that <code>userTimeline</code> takes a numeric <strong>user id</strong>, not a handle. Resolving the handle first costs you an extra call</p>
<h3>Resolve handles to ids</h3>
<pre><code class="language-js">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']);
</code></pre>
<h3>Read followers</h3>
<pre><code class="language-js">const followers = await roClient.v2.followers('44196397', {
  max_results: 1000,
  'user.fields': ['public_metrics'],
  asPaginator: true,
});
</code></pre>
<p>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</p>
<h3>Filter by engagement, and why it silently fails</h3>
<p>This is the trap that costs people the most time:</p>
<pre><code class="language-js">// Looks right. Does NOT work on API v2.
const results = await roClient.v2.search('solana min_faves:100');
</code></pre>
<p><code>min_faves:</code>, <code>min_retweets:</code> and <code>min_replies:</code> work in the web search box but are <strong>silently ignored</strong> 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</p>
<h2>Common Errors and Fixes</h2>
<ul>
<li><strong><code>401 Unauthorized</code></strong>: bad or missing Bearer token, or your app lacks read access. Regenerate the token and double-check the project's permissions</li>
<li><strong><code>403 Forbidden</code></strong>: your access tier can't use this endpoint (recent search needs Basic+, full-archive needs Pro/Academic)</li>
<li><strong><code>429 Too Many Requests</code></strong>: you're rate-limited. Read the <code>x-rate-limit-reset</code> header and back off with jitter</li>
<li><strong><code>results.data.data</code> is <code>undefined</code></strong>: the search matched nothing, so check <code>results.meta.result_count</code> before indexing</li>
</ul>
<h2>A Simpler Alternative: XCROP</h2>
<p>If the developer-app setup, the 7-day window, and the $200/month floor are more than your project needs, <a href="https://xcrop.io/">XCROP</a> exposes the same tweet-search capability behind a <strong>single API key</strong>. No OAuth app, no Bearer-token juggling, and credit-based pricing that costs <a href="https://xcrop.io/blog/x-api-pricing-comparison-2026">a fraction of the official API</a></p>
<pre><code class="language-bash">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"}'
</code></pre>
<p>The response is plain JSON: a <code>data</code> array of tweets plus a <code>meta</code> object with the cursor, so there is no paginator and no <code>.data.data</code> to unwrap:</p>
<pre><code class="language-js">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);
</code></pre>
<p>You can sort by <code>latest</code>, <code>engagement</code>, or <code>media</code>, filter by <code>min_likes</code> / <code>min_retweets</code> / <code>lang</code>, and request up to 1,000 results in a single call. <a href="https://xcrop.io/endpoints">See every parameter</a> in the interactive builder</p>
<h2>Which Should You Use?</h2>
<table>
<thead>
<tr>
<th></th>
<th>twitter-api-v2 (official)</th>
<th>XCROP</th>
</tr>
</thead>
<tbody><tr>
<td>Setup</td>
<td>Developer app + Bearer token</td>
<td>One API key</td>
</tr>
<tr>
<td>Auth</td>
<td>OAuth / app-only token</td>
<td>Bearer key in a header</td>
</tr>
<tr>
<td>Results shape</td>
<td>Paginator (<code>.tweets</code> / <code>.data.data</code>)</td>
<td>Plain JSON (<code>data</code> array + <code>meta</code>)</td>
</tr>
<tr>
<td>Search window</td>
<td>7 days (recent tier)</td>
<td>Recent + trending coverage</td>
</tr>
<tr>
<td>Per-request cap</td>
<td>100 tweets</td>
<td>Up to 1,000</td>
</tr>
<tr>
<td>Pricing</td>
<td>From $200/mo (Basic)</td>
<td>Free tier, then credit-based</td>
</tr>
<tr>
<td>Best for</td>
<td>Deep X-native integrations</td>
<td>Fast data pulls without the API-tier tax</td>
</tr>
</tbody></table>
<p>If you're building a product deeply tied to the X platform, the official <code>twitter-api-v2</code> 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 <code>curl</code></p>
<h2>FAQ</h2>
<p><strong>What is tweets.data.data in twitter-api-v2?</strong></p>
<p>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</p>
<p><strong>Why is data.data undefined after a search?</strong></p>
<p>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</p>
<p><strong>How far back can client.v2.search() go?</strong></p>
<p>Seven days. Recent search only covers the last week; anything older needs full-archive search, which sits behind the Pro or Academic access tier</p>
<p><strong>How many tweets can you get per call?</strong></p>
<p>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</p>
<p><strong>Does twitter-api-v2 handle rate limits for you?</strong></p>
<p>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</p>
<p><strong>Why does min_faves not work in API v2 search?</strong></p>
<p>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</p>
<hr />
<p><em>Originally published on the <a href="https://xcrop.io/blog/search-tweets-twitter-api-v2-nodejs">XCROP blog</a>.</em></p>
]]></content:encoded></item></channel></rss>