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