> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sorsa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# ツイート検索

> X（Twitter）のツイートをキーワードと演算子で検索するPOSTエンドポイント。

`/search-tweets`は、X（Twitter）の公開検索インデックスに対してキーワードや演算子を使った検索を実行し、一致するツイートを投稿者の完全なプロフィールとエンゲージメント指標付きで返します。

一連の実装パターン、検索条件のテンプレート、実行可能なコードは、ブログの[APIでツイートを検索する方法](https://api.sorsa.io/blog/twitter-search-api)を参照してください。

## エンドポイント

```text theme={null}
POST https://api.sorsa.io/v3/search-tweets
```

## 認証

`ApiKey`ヘッダーでAPIキーを渡します。HTTPヘッダー名の大文字・小文字は区別されませんが、キーの値は発行されたものと一致する必要があります。

```text theme={null}
ApiKey: YOUR_API_KEY
```

詳しくは[認証](https://docs.sorsa.io/ja/authentication)を参照してください。

## リクエスト本文

| パラメーター        | 型      | 必須  | 説明                                            |
| :------------ | :----- | :-- | :-------------------------------------------- |
| `query`       | string | はい  | 検索キーワードと演算子。Xのネイティブ検索演算子すべてに対応。               |
| `order`       | string | いいえ | `"popular"`（デフォルト）は「話題」タブに相当。`"latest"`は時系列順。 |
| `next_cursor` | string | いいえ | 前のレスポンスで返されたページネーションカーソル。最初のリクエストでは省略。        |

### リクエストの例

```bash theme={null}
curl -X POST https://api.sorsa.io/v3/search-tweets \
  -H "ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "artificial intelligence lang:en",
    "order": "latest"
  }'
```

## レスポンス

```json theme={null}
{
  "tweets": [
    {
      "id": "2029914600217473314",
      "full_text": "The latest breakthroughs in AI are reshaping automation.",
      "created_at": "2026-03-06T13:38:49Z",
      "lang": "en",
      "conversation_id_str": "2029914600217473314",
      "likes_count": 142,
      "retweet_count": 38,
      "reply_count": 12,
      "quote_count": 5,
      "view_count": 28400,
      "bookmark_count": 19,
      "is_reply": false,
      "is_quote_status": false,
      "entities": [],
      "user": {
        "id": "1422280682240450563",
        "username": "tech_insider",
        "display_name": "Tech Insider",
        "followers_count": 84200,
        "verified": true
      }
    }
  ],
  "next_cursor": "DAABCgABGSmiaxkAAgoAAgjEJ..."
}
```

各ツイートには投稿者の完全なプロフィールが含まれます。ユーザー情報を付けるために別のリクエストを送る必要はありません。

> 全フィールドの説明は[レスポンス形式](https://docs.sorsa.io/ja/response-format)を参照してください。

## 検索演算子

`query`には、次のようなXのネイティブ検索演算子をすべて指定できます。

* **キーワードと完全一致フレーズ：** `"climate change"`
* **ユーザーフィルター：** `from:`、`to:`、`@mention`
* **エンゲージメントフィルター：** `min_faves:`、`min_retweets:`、`min_replies:`
* **内容のフィルター：** `filter:media`、`filter:images`、`filter:videos`、`filter:links`（先頭に`-`を付けると除外）
* **言語と日付：** `lang:en`、`since:2026-01-01`、`until:2026-03-01`
* **論理演算：** `OR`、グループ化の丸括弧、除外の`-`

> 全演算子のリファレンス：[検索演算子](https://docs.sorsa.io/ja/search-operators)。

## ページネーション

レスポンスには`next_cursor`が含まれます。次のページを取得するには、同じリクエストにその値を`next_cursor`として指定します。`next_cursor`が`null`または存在しなければ、すべての結果を取得済みです。

> カーソルを使った実装パターンと例外的なケースは、[ページネーション](https://docs.sorsa.io/ja/pagination)を参照してください。

## レート制限

すべてのプランで、APIキーごとに毎秒20リクエストです。超過すると`429 Too Many Requests`が返されます。[レート制限](https://docs.sorsa.io/ja/rate-limits)を参照してください。

## エラーコード

| コード   | 意味                                  |
| :---- | :---------------------------------- |
| `200` | 成功                                  |
| `400` | 不正なリクエスト（無効なパラメーター）                 |
| `401` | 認証失敗（APIキーがない、または無効）                |
| `403` | アクセス拒否（割り当て量を消費済み、またはサブスクリプション期限切れ） |
| `429` | リクエスト過多（レート制限超過）                    |
| `500` | 内部サーバーエラー                           |

> 全一覧は[エラーコード](https://docs.sorsa.io/ja/error-codes)を参照してください。

## 関連エンドポイント

* [メンションの追跡](https://docs.sorsa.io/ja/api-reference/search/search-mentions)：本文でより多くのフィルターを指定できる、`@handle`追跡専用の機能
* [ユーザーのツイート](https://docs.sorsa.io/ja/api-reference/tweets/user-tweets)：単一ユーザーのタイムライン
* [ユーザー検索](https://docs.sorsa.io/ja/api-reference/search/search-users)：キーワードによるアカウント検索