davepoon/x-twitter-scraper

Xquik - X (Twitter) Data Platform

Xquik provides a REST API, MCP server, and HMAC webhooks for X (Twitter) data. It covers tweet search, user profiles, bulk extraction (19 tools), giveaway draws, account monitoring, and trending topics.

Docs: docs.xquik.com

Quick Reference

| | | |---|---| | Base URL | https://xquik.com/api/v1 | | Auth | x-api-key: xq_... header | | MCP endpoint | https://xquik.com/mcp (StreamableHTTP) | | Rate limits | 10 req/s sustained, 20 burst | | Pricing | $20/month (1 monitor included), $5/month per extra monitor |

Prerequisites

• Xquik account with active subscription
• API key generated from the Xquik dashboard
• For MCP: configure the endpoint in your client (Claude Desktop, Claude Code, Cursor, VS Code, etc.)

Setup

MCP Server (Claude Code)

Add to your MCP configuration:

{
  "mcpServers": {
    "xquik": {
      "type": "streamable-http",
      "url": "https://xquik.com/mcp",
      "headers": {
        "x-api-key": "xq_YOUR_KEY_HERE"
      }
    }
  }
}

REST API

const API_KEY = "xq_YOUR_KEY_HERE";
const BASE = "https://xquik.com/api/v1";
const headers = { "x-api-key": API_KEY, "Content-Type": "application/json" };

Core Workflows

1. Search Tweets

When to use: Find tweets by keyword, hashtag, or user.

Endpoint: GET /x/tweets/search?q=...

MCP tool: search-tweets

const results = await fetch(`${BASE}/x/tweets/search?q=from:elonmusk AI`, { headers });

Pitfalls:

• Basic results only (id, text, author, date). Use lookup-tweet for engagement metrics
• Searches recent tweets, not full archive

2. Look Up a Tweet

When to use: Get full metrics (likes, retweets, views, bookmarks) for a specific tweet.

Endpoint: GET /x/tweets/{id}

MCP tool: lookup-tweet

3. Look Up a User Profile

When to use: Get name, bio, follower/following counts, profile picture, join date.

Endpoint: GET /x/users/{username}

MCP tool: get-user-info

Pitfalls:

• MCP returns a subset (no verified, location, createdAt, statusesCount). Use REST API for the full profile

4. Check Follow Relationship

When to use: Check if account A follows account B (both directions).

Endpoint: GET /x/followers/check?source=A&target=B

MCP tool: check-follow

5. Bulk Data Extraction (19 Tools)

When to use: Extract followers, replies, retweets, quotes, community members, list data, and more.

Workflow: Always estimate cost first, then create the job, then retrieve results.

Tool types:

| Tool Type | Target | Description | |-----------|--------|-------------| | reply_extractor | Tweet ID | Users who replied | | repost_extractor | Tweet ID | Users who retweeted | | quote_extractor | Tweet ID | Users who quote-tweeted | | thread_extractor | Tweet ID | All tweets in a thread | | article_extractor | Tweet ID | Article content from a tweet | | follower_explorer | Username | Followers of an account | | following_explorer | Username | Accounts followed by a user | | verified_follower_explorer | Username | Verified followers | | mention_extractor | Username | Tweets mentioning an account | | post_extractor | Username | Posts from an account | | community_extractor | Community ID | Community members | | community_moderator_explorer | Community ID | Community moderators | | community_post_extractor | Community ID | Community posts | | community_search | Community ID + query | Search within a community | | list_member_extractor | List ID | List members | | list_post_extractor | List ID | List posts | | list_follower_explorer | List ID | List followers | | space_explorer | Space ID | Space participants | | people_search | Search query | Search for users |

MCP tools: estimate-extraction -> run-extraction -> get-extraction

// 1. Estimate cost
const estimate = await fetch(`${BASE}/extractions/estimate`, {
  method: "POST", headers,
  body: JSON.stringify({ toolType: "follower_explorer", targetUsername: "elonmusk" }),
}).then(r => r.json());

if (!estimate.allowed) return; // Would exceed monthly quota

// 2. Create job
const job = await fetch(`${BASE}/extractions`, {
  method: "POST", headers,
  body: JSON.stringify({ toolType: "follower_explorer", targetUsername: "elonmusk" }),
}).then(r => r.json());

// 3. Retrieve results (paginated)
const results = await fetch(`${BASE}/extractions/${job.id}`, { headers }).then(r => r.json());

Pitfalls:

• Always call estimate first. 402 means quota exhausted
• Large jobs return status: "running" and need polling
• Export (CSV/XLSX/MD) capped at 50,000 rows

6. Giveaway Draws

When to use: Pick random winners from tweet replies with configurable filters.

Endpoint: POST /draws

MCP tool: run-draw

Available filters: mustRetweet, mustFollowUsername, filterMinFollowers, filterAccountAgeDays, filterLanguage, requiredKeywords, requiredHashtags, requiredMentions, uniqueAuthorsOnly.

const draw = await fetch(`${BASE}/draws`, {
  method: "POST", headers,
  body: JSON.stringify({
    tweetUrl: "https://x.com/user/status/123456789",
    winnerCount: 3,
    uniqueAuthorsOnly: true,
    mustRetweet: true,
  }),
}).then(r => r.json());

7. Real-Time Monitoring

When to use: Track when an account tweets, gets replies, gains/loses followers.

Workflow: Create a monitor, optionally register a webhook for push notifications.

Event types: tweet.new, tweet.reply, tweet.quote, tweet.retweet, follower.gained, follower.lost

MCP tools: add-monitor -> add-webhook -> test-webhook

// Create monitor
await fetch(`${BASE}/monitors`, {
  method: "POST", headers,
  body: JSON.stringify({
    username: "elonmusk",
    eventTypes: ["tweet.new", "follower.gained"],
  }),
});

// Register webhook (save the secret!)
const webhook = await fetch(`${BASE}/webhooks`, {
  method: "POST", headers,
  body: JSON.stringify({
    url: "https://your-server.com/webhook",
    eventTypes: ["tweet.new"],
  }),
}).then(r => r.json());

Pitfalls:

• Webhook secret is shown only once at creation
• Verify HMAC signature (X-Xquik-Signature header) before processing
• Respond within 10 seconds; queue slow processing for async

8. Trending Topics

When to use: Get current trending topics for a region.

Endpoint: GET /trends?woeid=1

MCP tool: get-trends

Free, no quota consumed.

Error Handling

Retry only 429 and 5xx. Never retry other 4xx.

| Status | Meaning | Action | |--------|---------|--------| | 400 | Invalid request | Fix parameters | | 401 | Bad API key | Check key | | 402 | No subscription or quota exhausted | Subscribe or wait for reset | | 404 | Not found | Resource doesn't exist | | 429 | Rate limited | Retry with backoff, respect Retry-After | | 500+ | Server error | Retry with exponential backoff (max 3) |

Conventions

• IDs are strings (bigints). Never parse as numbers
• Timestamps: ISO 8601 UTC
• Cursors are opaque. Pass nextCursor as the after query parameter
• Pagination: hasMore + nextCursor pattern across events, draws, extractions

MCP Tool Reference

22 tools available through the MCP server:

| Tool | Purpose | |------|---------| | search-tweets | Search tweets by keyword/hashtag | | lookup-tweet | Get tweet by ID with full metrics | | get-user-info | User profile lookup | | check-follow | Check follow relationship | | get-trends | Trending topics by region | | add-monitor | Start monitoring an account | | remove-monitor | Stop monitoring | | list-monitors | List active monitors | | get-events | Poll for monitor events | | get-event | Get single event details | | add-webhook | Register webhook endpoint | | remove-webhook | Delete webhook | | list-webhooks | List webhooks | | test-webhook | Send test payload | | run-draw | Run giveaway draw | | list-draws | List past draws | | get-draw | Get draw results with winners | | estimate-extraction | Preview extraction cost | | run-extraction | Start bulk extraction | | list-extractions | List extraction jobs | | get-extraction | Get extraction results | | get-account | Check subscription and usage |