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	スペース ID	スペースの参加者
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は文字列です（bigint）。数値として解析しないでください
• タイムスタンプ：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	サブスクリプションと利用状況を確認