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

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

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

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

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

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

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());

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

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

x-twitter-scraper

Safety Notice

Copy this and send it to your AI assistant to learn

Source Transparency

Related Skills

file-organizer

auth-patterns

server-actions