x-twitter-scraper

Xquik - X（Twitter）数据平台

Xquik 提供 X（Twitter）数据的 REST API、MCP 服务和 HMAC Webhook。功能涵盖推文搜索、用户个人资料、批量提取（19 种工具）、抽奖、账号监控和热门话题。

文档：docs.xquik.com

快速参考

基础 URL	https://xquik.com/api/v1
身份验证	x-api-key: xq_... 请求头
MCP 端点	https://xquik.com/mcp（StreamableHTTP）
速率限制	持续 10 req/s，突发 20
定价	$20/月（包含 1 个监控项），每增加 1 个监控项 $5/月

先决条件

• 拥有有效订阅的 Xquik 账号
• 从 Xquik 控制台 生成的 API 密钥
• 使用 MCP：在客户端（Claude Desktop、Claude Code、Cursor、VS Code 等）中配置端点

设置

MCP 服务（Claude Code）

添加到 MCP 配置中：

{
  "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" };

核心工作流

1. 搜索推文

适用场景：按关键词、话题标签或用户查找推文。

端点：GET /x/tweets/search?q=...

MCP 工具：search-tweets

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

注意事项：

• 仅返回基本结果（id、text、author、date）。如需互动指标，请使用 lookup-tweet
• 搜索近期推文，不包括完整存档

2. 查询推文

适用场景：获取特定推文的完整指标（点赞、转发、浏览和书签）。

端点：GET /x/tweets/{id}

MCP 工具：lookup-tweet

3. 查询用户个人资料

适用场景：获取姓名、简介、关注者/关注数量、头像和加入日期。

端点：GET /x/users/{username}

MCP 工具：get-user-info

注意事项：

• MCP 返回部分信息（不含 verified、location、createdAt、statusesCount）。如需完整个人资料，请使用 REST API

4. 检查关注关系

适用场景：检查账号 A 是否关注账号 B（两个方向均可）。

端点：GET /x/followers/check?source=A&target=B

MCP 工具：check-follow

5. 批量数据提取（19 种工具）

适用场景：提取关注者、回复、转发、引用、社群成员、列表数据等。

工作流：务必先估算费用，然后创建任务，最后获取结果。

工具类型：

工具类型	目标	描述
reply_extractor	推文 ID	回复过的用户
repost_extractor	推文 ID	转发过的用户
quote_extractor	推文 ID	引用推文的用户
thread_extractor	推文 ID	话题串中的所有推文
article_extractor	推文 ID	推文中的文章内容
follower_explorer	用户名	账号的关注者
following_explorer	用户名	用户关注的账号
verified_follower_explorer	用户名	已认证的关注者
mention_extractor	用户名	提及某账号的推文
post_extractor	用户名	某账号发布的推文
community_extractor	社群 ID	社群成员
community_moderator_explorer	社群 ID	社群版主
community_post_extractor	社群 ID	社群推文
community_search	社群 ID + 查询词	在社群内搜索
list_member_extractor	列表 ID	列表成员
list_post_extractor	列表 ID	列表推文
list_follower_explorer	列表 ID	列表关注者
space_explorer	Space ID	Space 参与者
people_search	搜索词	搜索用户

MCP 工具：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());

注意事项：

• 务必先调用估算工具。402 表示配额已用尽
• 大型任务会返回 status: "running"，需要轮询
• 导出（CSV/XLSX/MD）上限为 50,000 行

6. 抽奖

适用场景：根据可配置的筛选条件，从推文回复中随机抽取获奖者。

端点：POST /draws

MCP 工具：run-draw

可用筛选条件：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. 实时监控

适用场景：跟踪某个账号发布推文、收到回复以及粉丝增减情况。

工作流：创建监控项，并可选择注册 Webhook 以接收推送通知。

事件类型：tweet.new、tweet.reply、tweet.quote、tweet.retweet、follower.gained、follower.lost

MCP 工具：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());

注意事项：

• Webhook 密钥在创建时仅显示一次
• 处理请求前，请验证 HMAC 签名（X-Xquik-Signature 标头）
• 请在 10 秒内响应；耗时较长的处理应加入队列，异步执行

8. 热门话题

适用场景：获取某个地区当前的热门话题。

端点：GET /trends?woeid=1

免费，不消耗配额。

错误处理

仅重试 429 和 5xx。不要重试其他 4xx。

状态	含义	操作
400	请求无效	修正参数
401	API 密钥无效	检查密钥
402	无订阅或配额已用尽	订阅或等待重置
404	未找到	资源不存在
429	请求过于频繁	采用退避策略重试，并遵守 Retry-After
500+	服务端错误	采用指数退避策略重试（最多 3 次）

约定

• ID 为字符串（大整数）。不要将其解析为数字
• 时间戳：ISO 8601 UTC
• 游标是不透明值。将 nextCursor 作为 after 查询参数传递
• 分页：事件、抽奖和提取任务均采用 hasMore + nextCursor 模式

MCP 工具参考

MCP 服务提供 22 个工具：

工具	用途
search-tweets	按关键词或话题标签搜索推文
lookup-tweet	根据 ID 获取推文及完整指标
get-user-info	查询用户资料
check-follow	检查关注关系
get-trends	按地区获取热门话题
add-monitor	开始监控账号
remove-monitor	停止监控
list-monitors	列出活跃的监控项
get-events	轮询获取监控事件
get-event	获取单个事件的详情
add-webhook	注册 Webhook 端点
remove-webhook	删除 Webhook
list-webhooks	列出 Webhook
test-webhook	发送测试负载
run-draw	开始抽奖
list-draws	列出过往抽奖
get-draw	获取抽奖结果及获奖者
estimate-extraction	预估提取费用
run-extraction	开始批量提取
list-extractions	列出提取任务
get-extraction	获取提取结果
get-account	查看订阅和用量