Grok X Search APIの使い方｜Xの投稿・ユーザー・スレッドをJavaScriptで検索

Grok X Search APIを使うと、X上の投稿、ユーザー、スレッドをGrokに検索させ、要約と引用元を取得できます。

この記事では、一般Webを調べるWeb Searchとの違い、JavaScript実装、日付・アカウントの絞り込み、画像・動画理解、Webアプリへ組み込む際の注意点を解説します。

情報確認日：2026年7月11日（日本時間）

結論：X SearchはWeb検索とは分け、期間・アカウント・引用元を必ず指定する

Grok X Search APIとは？

X Searchは、GrokがX上の公開情報を検索するためのサーバー側ツールです。単純な文字列検索だけでなく、意味の近い投稿、特定ユーザー、スレッド全体を調べ、回答と参照元を返せます。

一般Webを調べるweb_searchとは別のツールです。製品の公式ページや技術記事はWeb Search、ユーザー反応や速報、X上の会話はX Searchというように分けます。

事前準備

Node.jsプロジェクトを作る

mkdir grok-x-search-demo
cd grok-x-search-demo
npm init -y
npm install ai @ai-sdk/xai dotenv

APIキーを.envへ入れる

XAI_API_KEY=xai-your-api-key

node_modules/
.env

JavaScriptでX Searchを実行する

x-search.mjsを作成します。

import 'dotenv/config';
import { xai } from '@ai-sdk/xai';
import { generateText } from 'ai';

if (!process.env.XAI_API_KEY) {
  throw new Error('XAI_API_KEY is not set');
}

const { text, sources } = await generateText({
  model: xai.responses('grok-4.5'),
  prompt: [
    '2026年7月1日以降のX上の投稿を調べてください。',
    '対象はWeb開発者が報告しているGrok Buildの使用感です。',
    '肯定的な意見、問題報告、具体的な利用例を分け、',
    '各主張の元投稿が分かるようにしてください。',
  ].join('\n'),
  tools: {
    x_search: xai.tools.xSearch({
      fromDate: '2026-07-01',
      toDate: '2026-07-11',
    }),
  },
});

console.log(text);
console.log(JSON.stringify(sources, null, 2));

node x-search.mjs

モデル名、ツール仕様、料金は変更される可能性があります。実行時点の公式モデル一覧とX Searchドキュメントを確認してください。

sourcesをWebアプリで表示する

検索結果は、回答文だけでは検証できません。APIレスポンスのsourcesを、タイトルやURLと一緒に表示します。値の形はSDKのバージョンで変わり得るため、型と実レスポンスを確認してください。

function normalizeSources(sources = []) {
  return sources
    .map((source) => ({
      url: source.url ?? '',
      title: source.title ?? source.url ?? 'X source',
    }))
    .filter((source) => source.url.startsWith('https://'));
}

const citations = normalizeSources(sources);
console.table(citations);

URLをそのままHTMLへ埋め込む場合も、スキームを検証し、rel="noopener noreferrer"を付けます。投稿本文を長く再掲載せず、要約と元投稿へのリンクを基本にします。

特定アカウントだけを検索する

allowedXHandlesには最大20件のハンドルを指定できます。公式アカウントや、調査対象として合意したアカウントに限定すると、ノイズと誤認を減らせます。

const { text, sources } = await generateText({
  model: xai.responses('grok-4.5'),
  prompt: '指定した公式アカウントの発表を時系列で整理してください。',
  tools: {
    x_search: xai.tools.xSearch({
      allowedXHandles: ['xai'],
      fromDate: '2026-07-01',
      toDate: '2026-07-11',
    }),
  },
});

allowedXHandlesとexcludedXHandlesは同じリクエストで併用できません。対象を含める方式か、ノイズを除外する方式のどちらかを選びます。

特定アカウントを除外する

const result = await generateText({
  model: xai.responses('grok-4.5'),
  prompt: '一般ユーザーによる製品の不具合報告を分類してください。',
  tools: {
    x_search: xai.tools.xSearch({
      excludedXHandles: ['xai'],
      fromDate: '2026-07-01',
      toDate: '2026-07-11',
    }),
  },
});

公式投稿を除外するだけで一般ユーザーの意見になるとは限りません。ボット、宣伝、重複投稿、引用だけの投稿も含まれるため、分類後にサンプルを確認します。

投稿内の画像・動画も分析する

画像理解を有効にする

const result = await generateText({
  model: xai.responses('grok-4.5'),
  prompt: 'Webパフォーマンス計測画面を含む投稿を探し、数値を要約してください。',
  tools: {
    x_search: xai.tools.xSearch({
      enableImageUnderstanding: true,
      fromDate: '2026-07-01',
    }),
  },
});

動画理解を有効にする

X Searchには投稿内動画の分析オプションもあります。動画は切り取りや編集で文脈が変わりやすく、処理量も増えるため、必要な調査だけで有効にします。

const result = await generateText({
  model: xai.responses('grok-4.5'),
  prompt: 'AIに関する動画付き投稿を探し、内容と文脈を要約してください。',
  tools: {
    x_search: xai.tools.xSearch({
      enableVideoUnderstanding: true,
    }),
  },
});

実務で使える検索プロンプトの作り方

期間を明示する

「最近」ではなく、開始日と終了日をツール設定へ入れます。回答文にも検索期間を出させると、キャッシュや再実行時に比較できます。

投稿を分類する基準を先に決める

• 不具合報告：再現手順、エラー文、環境がある
• 感想：根拠となる操作や結果が少ない
• 機能要望：期待する動作が書かれている
• 公式発表：公式ハンドルまたは公式URLへのリンクがある
• 未確認情報：出典や再現情報がない

件数ではなく根拠を残す

「好意的な投稿が多い」という要約だけではなく、検索条件、代表投稿、除外条件、実行日時を保存します。同じ条件で再実行し、結論が変わるか確認できるようにします。

Webアプリへ組み込む構成例

ブラウザ
  ↓ 調査条件
自分のバックエンドAPI
  ↓ XAI_API_KEYを使って実行
Grok Responses API + x_search
  ↓ 回答 + sources
DBへ検索条件・実行日時・引用元を保存
  ↓
ブラウザへ要約と元投稿リンクを返す

検索を利用者へ開放する場合は、1回あたりの検索数、日付範囲、許可ハンドル数、最大出力、レート制限をサーバー側で固定します。利用者の入力をそのままツール設定へ渡さないようにします。

X Searchを使うときの注意点

• 削除・非公開化された投稿や、検索時点で取得できない投稿がある
• ユーザー名と表示名を混同しない
• 引用投稿と元投稿、スレッドの前後関係を確認する
• 投稿数を世論や市場全体の割合と解釈しない
• センシティブな個人情報を収集・保存しない
• 投稿の自動返信や評価を行う前に人間の確認を入れる
• ツール利用料金とモデルのトークン料金を分けて監視する

あわせて読みたい記事

• Grokとは？
• Grok Collections APIの使い方
• JavaScriptのasync/await
• JavaScriptでfetchとJSONを扱う基本

よくある質問

X SearchとX APIは同じですか？

同じではありません。X SearchはGrokが調査のために使うサーバー側ツールです。投稿の作成、削除、フォローなどXプラットフォームの操作APIとは目的が異なります。

非公開アカウントの投稿も検索できますか？

公開・取得可能な情報を前提に考えてください。アクセス権のない情報を取得する機能として使うものではありません。

特定のユーザーを何件まで指定できますか？

公式ドキュメントではallowed_x_handlesとexcluded_x_handlesはそれぞれ最大20件です。両方を同時には指定できません。

画像と動画の分析は自動で有効ですか？

必要なオプションを明示して有効にします。処理量と調査目的を考え、必要な場合だけ使います。

検索結果をそのまま記事へ掲載してよいですか？

元投稿の著作権、プライバシー、利用規約、文脈を確認してください。長文転載ではなく、自分の要約と必要最小限の引用、元投稿リンクを基本にします。

まとめ

Grok X Search APIは、X上のリアルタイムな投稿・ユーザー・スレッドを、Grokの推論と組み合わせて調査する機能です。JavaScriptではVercel AI SDKから呼び出し、ハンドル、期間、画像・動画理解を必要に応じて設定できます。

実務では、回答本文よりも検索条件と引用元を重視します。Web Searchとは情報源を分け、元投稿を人間が確認できる画面とログを用意してください。

参考リンク

• SpaceXAI X Search
• SpaceXAI Tools Overview
• SpaceXAI Pricing
• Vercel AI SDK xAI provider