TweetAPI ドキュメント

開発者向けの扱いやすい REST API から、包括的な公開 Twitter/X データにアクセスできます。

最初の API リクエストを送る

初回限定の無料リクエスト100回で試せます。上限は1分あたり10回です。クレジットカードや有料プランは不要で、無料枠に有効期限はありません。

TweetAPI アカウント（英語で表示されるページ）を作成します。無料の API 利用枠が自動で準備されます。
API Keys（英語で表示されるページ）で Create Key を選び、名前を付けてキー全体を保存します。キー全体が表示されるのは作成時のみです。保存し忘れた場合は、新しいキーを作成してください。
下の入力済みリクエストを開き、キーを選んで Try It! を押すと、公開プロフィールを取得できます。このリクエストに別途 X アカウントの認証は必要ありません。
ステータス 200 と、data を含む JSON オブジェクトを確認します。Playground は実際の API を呼び出し、リクエスト利用枠を消費します。
自分のアプリケーションで使うには、以下の環境変数を設定して、いずれかの例を実行します。

入力済みの Playground を開く（Playground は英語で提供されています。）

同じリクエストをローカルで実行する

YOUR_API_KEY を保存したキー全体に置き換えてください。コードを実行するターミナルで環境変数を設定します。キーはサーバー側で管理し、フロントエンドのコードに埋め込んだり Git にコミットしたりしないでください。

macOS / Linux:

export TWEETAPI_API_KEY='YOUR_API_KEY'

PowerShell:

$env:TWEETAPI_API_KEY = 'YOUR_API_KEY'

cURL (Bash)

curl --fail-with-body \
  'https://api.tweetapi.com/tw-v2/user/by-username?username=elonmusk' \
  -H "X-API-Key: ${TWEETAPI_API_KEY:?Set TWEETAPI_API_KEY first}"

Python SDK

pip install tweetapi で SDK をインストールします。以下を quickstart.py に保存し、python quickstart.py を実行します。

import os
from tweetapi import TweetAPI

client = TweetAPI(api_key=os.environ["TWEETAPI_API_KEY"])
user = client.user.get_by_username(username="elonmusk")
print(user["data"])

Node.js SDK（Node.js 18 以降）

npm install tweetapi-node で SDK をインストールします。以下を quickstart.mjs に保存し、node quickstart.mjs を実行します。

import TweetAPI from "tweetapi-node";

const apiKey = process.env.TWEETAPI_API_KEY;
if (!apiKey) throw new Error("Set TWEETAPI_API_KEY first");
const client = new TweetAPI({ apiKey });
const user = await client.user.getByUsername({ username: "elonmusk" });
console.log(user.data);

最初のリクエストが失敗した場合

環境変数が未設定、または 401 が返る場合：キー一覧のマスク表示ではなく、キー全体を TWEETAPI_API_KEY に設定してください。
アカウントの準備が終わらない場合：設定画面の Check again を選んでください。引き続き利用できない場合はサポートへご連絡ください。
429：code フィールドを確認してください。RATE_LIMITED の場合は Retry-After ヘッダーの秒数だけ待ってから再試行します。QUOTA_EXHAUSTED または SUBSCRIPTION_INACTIVE の場合は Billing（英語で表示されるページ）を確認してください。
503：サービスが一時的に利用できません。Retry-After がある場合は従い、再試行の回数を制限してください。

ベース URL

すべての API リクエストは次の URL に送信します。

https://api.tweetapi.com/tw-v2/

認証

API キーを X-API-Key ヘッダーに含めます。

headers: {
  'X-API-Key': 'YOUR_API_KEY'
}

API を呼び出す前に

レスポンスは JSON 形式です。
プラン制限は API キーごとに適用され、リクエスト利用枠と 1 分あたりのリクエスト上限があります。
コレクション系エンドポイントでは、利用可能な場合にカーソルベースのページネーションを使います。
投稿、エンゲージメント、プロフィール、DM、X Chat の各エンドポイントでは、TweetAPI キーに加えて、アカウント操作を認可するためのフィールドが必要になることがあります。正確な必須パラメータは各エンドポイントのページで確認してください。
プランの制限による 429 には、理由を示す code が含まれます。RATE_LIMITED（1 分あたりの上限を超えた場合。Retry-After ヘッダーで上限がリセットされるまでの秒数がわかります）、QUOTA_EXHAUSTED（利用枠と前払い残高を使い切った場合）、SUBSCRIPTION_INACTIVE（サブスクリプションの期限切れまたは無効）のいずれかです。後の 2 つは再試行しても解決しません。code のない 429 は一時的なものなので、回数を制限したバックオフで再試行してください。X-RateLimit-* ヘッダーは返しません。

TweetAPI SDK

TweetAPI は、完全な型サポート、自動再試行、組み込みページネーションを備えた Python および Node.js 向けのメンテナンス済み SDK を提供しています。バージョン 2.5.0 以降では、code フィールドを error.code として公開し、Retry-After に自動で従います。

Python

pip install tweetapi

from tweetapi import TweetAPI

client = TweetAPI(api_key="YOUR_API_KEY")
user = client.user.get_by_username(username="elonmusk")
print(user["data"]["followerCount"])

GitHub で見る

Node.js / TypeScript

npm install tweetapi-node

import TweetAPI from "tweetapi-node";

const client = new TweetAPI({ apiKey: "YOUR_API_KEY" });
const user = await client.user.getByUsername({ username: "elonmusk" });
console.log(user.data.followerCount);

GitHub で見る

開発者向けリソース

コード生成、API ツール、コントラクトを認識する統合向けの OpenAPI 仕様（英語で表示されるページ）
ドキュメント化された 83 オペレーションをすべて含む Postman 完全版コレクション（英語で表示されるページ）
公開プロフィール、検索、ツイート詳細のリクエストで安全に導入できる読み取り専用 Postman クイックスタート（英語で表示されるページ）

これらのリソースは現在英語で提供されています。

主な機能

公開データへのアクセス: ユーザープロフィール、ツイート／投稿、フォロワー、エンゲージメント指標
操作機能: ツイートの投稿、いいね、リツイート、ブックマーク、ダイレクトメッセージの管理
検索: ドキュメント化されたクエリパラメータによるツイート、ユーザー、メディアの検索
リクエスト時に最新データを取得（英語で表示されるページ）: アプリケーションからリクエストした時点の投稿、プロフィール、指標を取得（英語ドキュメント）
ページネーション: コレクション系エンドポイントでのカーソルベースのページネーション
メディア対応: 画像、動画、GIF に完全対応

利用できるエンドポイント

ユーザーエンドポイント

ユーザー名によるユーザー取得
ID によるユーザー取得
複数 ID によるユーザー一括取得
フォロワーとフォロー一覧
ユーザーのツイートと返信
サブスクリプション情報

ツイートエンドポイント

ツイート詳細と会話スレッド
引用ツイートとリツイート
ツイート翻訳
エンゲージメント指標

操作エンドポイント

投稿の作成、返信、削除
ツイートへのいいねとブックマーク
リツイートと引用ツイート
リスト管理

リスト・コミュニティエンドポイント

リストの詳細とメンバー
コミュニティ情報
タイムラインのツイート

検索エンドポイント

ツイート、ユーザー、メディアの検索
高度な検索演算子
フィルターと並び替えオプション

プラン制限

現在の公開プランにおける 1 分あたりのリクエスト上限は次のとおりです。

Free: 1 分あたり 10 リクエスト
Pro: 1 分あたり 60 リクエスト
Ultra: 1 分あたり 120 リクエスト
Mega: 1 分あたり 180 リクエスト
Giga: 1 分あたり 300 リクエスト
Tera: 1 分あたり 500 リクエスト

非公開、レガシー、カスタムプランの上限は異なる場合があります。1 分あたりの上限による 429（RATE_LIMITED）には、Retry-After の秒数だけ待ち、同時実行数を下げて対応してください。プランのリクエスト利用枠を使い切った場合（QUOTA_EXHAUSTED）は短時間の再試行では解決しないため、ダッシュボードで現在の使用量とサブスクリプションの選択肢を確認してください。

従量課金（PAYG）の予備残高

Billing では、10,000 ユニットを $5 USD、20,000 ユニットを $10 USD、40,000 ユニットを $20 USD、100,000 ユニットを $50 USD で手動の都度購入として追加できます。トップアップは自動更新されません。TweetAPI は利用可能な無料プランまたはサブスクリプションの利用枠を先に消費し、その後で有効な PAYG 残高を自動的に使います。サブスクリプションを解約しても、有効な PAYG ユニットは引き続き利用できます。PAYG 単独の利用は 1 分あたり 60 リクエストに制限されますが、それより高いレート上限の有効なプランがある場合は高い方の上限が維持されます。

PAYG ユニットは支払いの決済成功から 365 日後に失効します。トップアップが適用されると、まだ有効なウォレット全体に、既存の有効期限と決済日から 365 日後のうち遅い方が適用されます。すでに失効したユニットは復元されません。適用が遅れてウォレットが先に失効した場合、旧期限前に支払ったことだけでは延長は保証されません。期限前に支払ったにもかかわらず適用が遅れた場合は、support@tweetapi.com に連絡し、確認された処理エラーの調査と訂正、または適切な救済を依頼してください。Billing と支払い確認には、適用後の有効期限が UTC で表示されます。

ユニットは返されたツイート数ではなく API 利用量を測るものです。ほとんどの従量制呼び出しは 1 ユニット、/tw-v2/xchat/send は 10 ユニット、/tw-v2/auth/login は 50 ユニットです。HTTP 200〜499 の従量制レスポンスは、400、401、403、409、422、429 を除いて課金対象です。課金対象となる空の結果、ページネーションのリクエスト、個別に送信した再試行や繰り返しリクエストにもユニットが使われます。パスやメソッドに一致するエンドポイントがないために返される 404 は課金されません。

残高の確認（GET /tw-v2/account/usage（英語で表示されるページ））は無料で、1 分あたりのレート制限にのみカウントされます。

返金ではユニットが比例して取り消され、整数ユニットへ切り上げられます。支払いに異議申し立てが行われると、返金ですでに取り消された分を除き、その購入に関連するすべてのユニットが取り消されます。不足残高は PAYG をロックしますが、有効なサブスクリプションには影響しません。トップアップは使用可能なユニットを追加する前に不足分へ充当されます。誤った控除、未付与のユニット、支払いに関する異議は support@tweetapi.com までお問い合わせください。救済を求める条件として追加ユニットを購入する必要はありません。利用規約と返金情報（英語で表示されるページ）（英語）もご確認ください。強行法規上の権利は制限されません。

エラー処理

TweetAPI は標準 HTTP ステータスコードで成功または失敗を示します。

一般的なエラーコード

400s Errors

400BAD_REQUESTBad Request - Invalid parameters

401UNAUTHORIZEDUnauthorized - Invalid API key

404NOT_FOUNDNot Found - Resource doesn't exist

429RATE_LIMITEDToo Many Requests - Per-minute limit

429QUOTA_EXHAUSTEDToo Many Requests - Allowance used up

429SUBSCRIPTION_INACTIVEToo Many Requests - Subscription inactive

500s Errors

500INTERNAL_ERRORInternal Server Error

エラーレスポンスの形式

すべてのエラーは共通の形式です。

{
  "statusCode": 400,
  "message": "Invalid username parameter"
}

一部のエラーには、コードで判定できる安定した理由を示す code フィールドも含まれます。

{
  "statusCode": 429,
  "message": "Rate limit quota exceeded - 60 requests per minute allowed",
  "code": "RATE_LIMITED"
}

現在のコードは、429 の RATE_LIMITED、QUOTA_EXHAUSTED、SUBSCRIPTION_INACTIVE、X アカウントが利用できなくなった場合の ACCOUNT_SUSPENDED と ACCOUNT_LOCKED、プロキシに失敗した場合の PROXY_ERROR と PROXY_TIMEOUT、およびログインページ（英語で表示されるページ）に記載されたログイン結果です。理由がないエラーには code フィールドがありません。コードは今後追加される可能性があるため、未知のコードは code のないエラーと同様に扱ってください。

ベストプラクティス

必ずレスポンスのステータスコードと、ある場合は code フィールドを確認する
デバッグ用にエラーレスポンスを記録する
再試行には回数を制限した指数バックオフを使い、Retry-After がある場合はその秒数だけ待つ
QUOTA_EXHAUSTED と SUBSCRIPTION_INACTIVE は再試行せず、Billing（英語で表示されるページ）を確認する

セキュリティのベストプラクティス

API キーを公開したり、バージョン管理へコミットしたりしないでください。
セキュリティ強化のため、キーを定期的にローテーションしてください。
アプリケーションでは環境変数に API キーを保存してください。
不審な利用を検出できるよう、ダッシュボードで使用量を監視してください。

サポート

サポートが必要な場合や質問がある場合は、次の窓口をご利用ください。

support@tweetapi.com へメール
Telegram の @tweetapi でサポートへ連絡

AI 向けドキュメント