x-twitter-scraper · davepoon — Claude Code skill: X data extraction and monitoring
x-twitter-scraper — a skill for extracting X (Twitter) data via Xquik API: tweet search, user profiles, followers, trends, account monitoring with webhooks. 22 MCP tools included.
MIT 107 installs ★ 3,785 updated 2026-10-25
npx skills add davepoon/buildwithclaude --skill x-twitter-scraper -a claude-codeWhat x-twitter-scraper does
x-twitter-scraper wraps Xquik, a platform for X data access. You can search tweets by keyword or hashtag, fetch full metrics (likes, retweets, views), look up user profiles, and check follow relationships. Bulk extraction is the core feature: pull followers, reply authors, retweets, quotes, community members, list data, and Space participants. All operations run through MCP tools or REST API.
You need a Xquik account with an active subscription, starting at $20/month plus $5 per additional monitor. Account monitoring sends events over webhooks—new tweets, replies, follower changes. Built-in giveaway tool picks random winners from tweet replies with filters for engagement, account age, and language. Rate limits: 10 requests per second sustained, 20 in burst. Large extractions return paginated results and require polling.
What it helps with
- search tweets by keyword or from a specific account
- extract a list of followers or users who replied to a tweet
- monitor an account for new tweets in real time
- run a giveaway draw with eligibility filters
- fetch current trending topics by region
Example prompts for the agent
- Find recent tweets about AI from authors with over 100,000 followers
- List everyone who replied to this tweet and check if they follow @elonmusk
- Set up monitoring for @technewstoday and send me a webhook when a new tweet appears
How to install x-twitter-scraper
1Skills CLI (Vercel)
npx skills add davepoon/buildwithclaude --skill x-twitter-scraper -a claude-code2Manually: put the files in place
~/.claude/skills/x-twitter-scraper/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/x-twitter-scraper/
1Skills CLI (Vercel)
npx skills add davepoon/buildwithclaude --skill x-twitter-scraper -a codex2Manually: put the files in place
.agents/skills/x-twitter-scraper/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add davepoon/buildwithclaude --skill x-twitter-scraper -a cursor2Manually: put the files in place
.cursor/skills/x-twitter-scraper/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install davepoon/buildwithclaude plugins/all-skills/skills/x-twitter-scraper2Manually: put the files in place
.github/skills/x-twitter-scraper/SKILL.md1Skills CLI (Vercel)
npx skills add davepoon/buildwithclaude --skill x-twitter-scraper -a gemini-cli2Platform CLI
gemini skills install https://github.com/davepoon/buildwithclaude --path plugins/all-skills/skills/x-twitter-scraperManually: put the files in place
.devin/skills/x-twitter-scraper/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add davepoon/buildwithclaude --skill x-twitter-scraper -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about x-twitter-scraper
How do I install x-twitter-scraper in Claude Code?
Run npx skills add davepoon/buildwithclaude --skill x-twitter-scraper -a claude-code, then edit the MCP config at ~/.claude/skills/x-twitter-scraper/SKILL.md. Add your Xquik API key to the x-api-key header.
What do I need to get started?
A Xquik account with an active subscription (from $20/month). Generate an API key in your Xquik dashboard and add it to your MCP configuration.
What's the difference between searching tweets and looking up a specific tweet?
Search returns basic data (ID, text, author, date) without engagement metrics. To get likes, retweets, and views, use lookup-tweet with a tweet ID. Search also covers only recent tweets, not the full archive.
Source text
SKILL.md · MIT
---
name: x-twitter-scraper
category: social-media
description: "X (Twitter) data extraction and monitoring via Xquik: tweet search, user lookup, follower extraction, giveaway draws, trending topics, account monitoring with webhooks, reply/retweet/quote extraction, community and Space data, follow checks. 22 MCP tools + REST API."
---
# 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](https://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](https://xquik.com)
- 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:
```json
{
"mcpServers": {
"xquik": {
"type": "streamable-http",
"url": "https://xquik.com/mcp",
"headers": {
"x-api-key": "xq_YOUR_KEY_HERE"
}
}
}
}
```
### REST API
```javascript
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`
```javascript
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`
```javascript
// 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`.
```javascript
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`
```javascript
// 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 |
© davepoon · MIT · davepoon/buildwithclaude
Similar skills
All skills for Browser and scraping →x-twitter-scraper by other authors comes first.