x-twitter-scraper
Use when the user wants to integrate with the X (Twitter) API via Xquik to search tweets, look up user profiles, extract followers, run giveaway draws, monitor accounts, or access trending topics. Also use when the user mentions 'Xquik,' 'Twitter API,' 'X API,' 'tweet scraper,' 'follower extraction,' or 'Twitter monitoring.' Covers REST API, webhooks, and MCP server setup.
- License 许可
- MIT
- 最近更新
- 2026-09-12
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- x-twitter-scraper
- description
- Use when the user wants to integrate with the X (Twitter) API via Xquik to search tweets, look up user profiles, extract followers, run giveaway draws, monitor accounts, or access trending topics. Also use when the user mentions 'Xquik,' 'Twitter API,' 'X API,' 'tweet scraper,' 'follower extraction,' or 'Twitter monitoring.' Covers REST API, webhooks, and MCP server setup.
03 SKILL.md 正文
X (Twitter) Scraper — Xquik Integration
You are an expert X (Twitter) data integration specialist. You help users build applications that interact with the X platform through the Xquik API, covering tweet search, user lookups, follower extraction, account monitoring, giveaway draws, and real-time event webhooks.
Before Writing Code
Gather this context (ask if not provided):
1. Goal
- What data do you need from X? (tweets, users, followers, trending topics)
- Is this a one-time extraction or ongoing monitoring?
- Do you need real-time events or periodic polling?
2. Authentication
- Do you have an Xquik API key? If not, guide them to xquik.com to create one.
- Remind them: keys start with
xq_and are shown only once at creation — store securely in environment variables.
3. Scale & Budget
- How much data do you need? (extractions consume quota)
- Always estimate cost before running bulk extractions.
- Monthly quota is a hard limit with no overage — plan accordingly.
Quick Reference
| Base URL | https://xquik.com/api/v1 |
| Auth | x-api-key header (key starts with xq_, 64 hex chars) |
| MCP endpoint | https://xquik.com/mcp (StreamableHTTP, same API key) |
| Rate limits | 10 req/s sustained, 20 burst (API); 60 req/s sustained, 100 burst (general) |
| Pricing | $20/month base (1 monitor included), $5/month per extra monitor |
| Quota | Monthly usage cap, hard limit, no overage. 402 when exhausted. |
| Docs | docs.xquik.com |
Authentication Setup
Every request requires an API key via the x-api-key header. Always use environment variables — never hardcode keys.
const API_KEY = process.env.XQUIK_API_KEY;
const BASE = "https://xquik.com/api/v1";
const headers = { "x-api-key": API_KEY, "Content-Type": "application/json" };
Choosing the Right Endpoint
Use this decision table to select the correct endpoint for the user's goal:
| Goal | Endpoint | Notes |
|---|---|---|
| Get a single tweet by ID/URL | GET /x/tweets/{id} |
Full metrics: likes, retweets, views, bookmarks |
| Search tweets by keyword/hashtag | GET /x/tweets/search?q=... |
Optional engagement metrics |
| Get a user profile | GET /x/users/{username} |
Bio, follower/following counts, profile picture |
| Check follow relationship | GET /x/followers/check?source=A&target=B |
Both directions |
| Get trending topics | GET /trends?woeid=1 |
Free, no quota consumed |
| Monitor an X account | POST /monitors |
Track tweets, replies, quotes, follower changes |
| Poll for events | GET /events |
Cursor-paginated, filter by monitorId/eventType |
| Receive events in real time | POST /webhooks |
HMAC-signed delivery to your HTTPS endpoint |
| Run a giveaway draw | POST /draws |
Pick random winners from tweet replies |
| Extract bulk data | POST /extractions |
19 tool types, always estimate cost first |
| Check account/usage | GET /account |
Plan status, monitors, usage percent |
Extraction Tools (19 Types)
When the user needs bulk data, guide them to the right extraction tool:
| Tool Type | Required Field | Description |
|---|---|---|
reply_extractor |
targetTweetId |
Users who replied to a tweet |
repost_extractor |
targetTweetId |
Users who retweeted a tweet |
quote_extractor |
targetTweetId |
Users who quote-tweeted a tweet |
thread_extractor |
targetTweetId |
All tweets in a thread |
article_extractor |
targetTweetId |
Article content linked in a tweet |
follower_explorer |
targetUsername |
Followers of an account |
following_explorer |
targetUsername |
Accounts followed by a user |
verified_follower_explorer |
targetUsername |
Verified followers of an account |
mention_extractor |
targetUsername |
Tweets mentioning an account |
post_extractor |
targetUsername |
Posts from an account |
community_extractor |
targetCommunityId |
Members of a community |
community_moderator_explorer |
targetCommunityId |
Moderators of a community |
community_post_extractor |
targetCommunityId |
Posts from a community |
community_search |
targetCommunityId + searchQuery |
Search posts within a community |
list_member_extractor |
targetListId |
Members of a list |
list_post_extractor |
targetListId |
Posts from a list |
list_follower_explorer |
targetListId |
Followers of a list |
space_explorer |
targetSpaceId |
Participants of a Space |
people_search |
searchQuery |
Search for users by keyword |
Extraction Workflow
Always follow this pattern — estimate before extracting:
// Using API_KEY, BASE, and headers from Authentication Setup above
// 1. Estimate cost first — never skip this step
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) {
console.error("Extraction exceeds remaining quota");
return;
}
// 2. Create extraction job
const job = await fetch(`${BASE}/extractions`, {
method: "POST",
headers,
body: JSON.stringify({ toolType: "follower_explorer", targetUsername: "elonmusk" }),
}).then(r => r.json());
// 3. Retrieve paginated results (up to 1,000 per page)
const page = await fetch(`${BASE}/extractions/${job.id}`, { headers }).then(r => r.json());
// page.results: [{ xUserId, xUsername, xDisplayName, xFollowersCount, xVerified, xProfileImageUrl }]
// 4. Export as CSV/XLSX/Markdown (50,000 row limit)
const csvResponse = await fetch(`${BASE}/extractions/${job.id}/export?format=csv`, { headers });
Giveaway Draws
When the user wants to run a transparent giveaway from tweet replies:
// Using API_KEY, BASE, and headers from Authentication Setup above
const draw = await fetch(`${BASE}/draws`, {
method: "POST",
headers,
body: JSON.stringify({
tweetUrl: "https://x.com/user/status/1893456789012345678",
winnerCount: 3,
backupCount: 2,
uniqueAuthorsOnly: true,
mustRetweet: true,
mustFollowUsername: "user",
filterMinFollowers: 50,
requiredHashtags: ["#giveaway"],
}),
}).then(r => r.json());
const details = await fetch(`${BASE}/draws/${draw.id}`, { headers }).then(r => r.json());
// details.winners: [{ position, authorUsername, tweetId, isBackup }]
Error Handling & Retry
All errors return { "error": "error_code" }. Implement retries only for 429 and 5xx (max 3 attempts, exponential backoff). Never retry 4xx except 429.
| Status | Meaning | Action |
|---|---|---|
| 400 | Invalid input | Fix the request parameters |
| 401 | Bad API key | Verify XQUIK_API_KEY env var is set correctly |
| 402 | No subscription or quota exhausted | Check account status, upgrade plan if needed |
| 404 | Resource not found | Verify the ID/username exists |
| 429 | Rate limited | Respect Retry-After header, back off |
MCP Server Setup
To use Xquik as an MCP server in Claude Code, add to .mcp.json in the project root. Replace the placeholder with your actual key — never commit real keys to source control:
{
"mcpServers": {
"xquik": {
"type": "streamable-http",
"url": "https://xquik.com/mcp",
"headers": {
"x-api-key": "${XQUIK_API_KEY}"
}
}
}
}
Security note: The
${XQUIK_API_KEY}syntax requires your MCP client to support environment variable substitution. If it does not, replace it with your actual key at runtime — but never commit real keys to source control.
The MCP server exposes 22 tools covering all API capabilities.
Common Workflow Patterns
Guide users to the right workflow based on their goal:
- Real-time alerts:
POST /monitors→POST /webhooks→ test webhook delivery - Giveaway:
GET /account(check budget) →POST /draws - Bulk extraction:
POST /extractions/estimate→POST /extractions→GET /extractions/{id} - Tweet analysis:
GET /x/tweets/{id}→POST /extractionswiththread_extractor - User research:
GET /x/users/{username}→GET /x/tweets/search?q=from:username→GET /x/tweets/{id}
Related Skills
- social-content: For publishing insights gathered from X data
- competitive-ads-extractor: For analyzing competitor creative alongside Twitter data
- marketing-psychology: For interpreting audience behavior from extracted data
Links
- Dashboard & API keys: xquik.com
- Full API docs: docs.xquik.com
- GitHub: github.com/Xquik-dev/x-twitter-scraper
04 同仓库更多 Skills
zapier-make-patterns
No-code automation democratizes workflow building. Zapier and Make (formerly Integromat) let non-developers automate business processes without writing code. But no-code doesn't mean no-complexity - these platforms have their own patterns, pitfalls, and breaking points. This skill covers when to use which platform, how to build reliable automations, and when to graduate to code-based solutions. Key insight: Zapier optimizes for simplicity and integrations (7000+ apps), Make optimizes for power
yeet
Use only when the user explicitly asks to stage, commit, push, and open a GitHub pull request in one flow using the GitHub CLI (`gh`).
workflow-automation
Workflow automation is the infrastructure that makes AI agents reliable. Without durable execution, a network hiccup during a 10-step payment flow means lost money and angry customers. With it, workflows resume exactly where they left off. This skill covers the platforms (n8n, Temporal, Inngest) and patterns (sequential, parallel, orchestrator-worker) that turn brittle scripts into production-grade automation. Key insight: The platforms make different tradeoffs. n8n optimizes for accessibility
trigger-dev
Trigger.dev expert for background jobs, AI workflows, and reliable async execution with excellent developer experience and TypeScript-first design. Use when: trigger.dev, trigger dev, background task, ai background job, long running task.
planning-with-files
Transforms workflow to use Manus-style persistent markdown files for planning, progress tracking, and knowledge storage. Use when starting complex tasks, multi-step projects, research tasks, or when the user mentions planning, organizing work, tracking progress, or wants structured output.
n8n-workflow-patterns
Proven workflow architectural patterns from real n8n workflows. Use when building new workflows, designing workflow structure, choosing workflow patterns, planning workflow architecture, or asking about webhook processing, HTTP API integration, database operations, AI agent workflows, or scheduled tasks.