結論
X API(旧Twitter API)は、2026年11月18日時点で「クレジットを先に買い、使った分だけ減る」従量課金です。開発者コンソール(console.x.com)でアプリを作って鍵を受け取り、読むだけなら Bearer Token、投稿するならユーザーの文脈のトークンを使います。
この記事でわかること
- 公式の単価表と、使い方別の月の費用をPythonで計算した結果
- 鍵の種類と認証の選び方(Bearer・OAuth 2.0 PKCE・OAuth 1.0a)
- 模擬サーバーで動かした投稿・取得・429の待ち方と公式SDKの挙動
この記事で実際に動かしたもの:127.0.0.1 で動かした X API v2 の模擬サーバー(自作)に対する、requests と公式 Python SDK(xdk)での取得・投稿・ページ送り・429 の処理、PKCE の値の計算、料金の試算。本物の X には接続していません。
どの鍵を使うかは、「何をしたいか」と「誰として動くか」で決まります。
flowchart TD
A{何をしたい?} -->|公開の投稿を読む| B[Bearer Token<br>アプリ専用]
A -->|投稿する| C{誰として?}
C -->|自分の<br>アカウント| D[Access Token<br>OAuth 1.0a]
C -->|許可をくれた<br>利用者| E[Client ID<br>OAuth 2.0 PKCE]
よく調べられることの答えを先にまとめます。
| 知りたいこと | 答え | 詳しい節 |
|---|---|---|
| X API とは | X の公開の会話をプログラムから読み書きする仕組み。今の版は v2 | X APIとは |
| X API の料金 | 従量課金。投稿の読み取り1件 $0.005、投稿1回 $0.015(URL付きは $0.200) | X APIの料金 |
| X API は無料で使える? | 公式の料金表に無料の枠の記載は無い。初回の支払い登録で $20 分のクレジット | X APIの料金 |
| API キーの取得方法 | console.x.com で開発者登録→「New App」→鍵が1回だけ表示される | X APIの始め方 |
| Bearer Token と Access Token の違い | Bearer はアプリ専用で公開データを読むだけ。投稿はユーザーの文脈が要る | 鍵の種類と認証の選び方 |
| Python で投稿する | POST https://api.x.com/2/tweets に {"text": "..."} を送る | Pythonで投稿する |
| 429 Too Many Requests | x-rate-limit-reset(UNIX 秒)まで待ってからやり直す | レート制限と429 |
| Twitter API との違い | 同じもの。名前が X API になり、URL は api.x.com が使われている | X APIとは |
確認環境:Ubuntu 24.04.5 LTS の上で、Python 3.13.18 の venv に requests 2.34.2 と、X の公式 Python SDK である xdk 0.10.6(pydantic 2.14.3)を入れました。X API v2 の一部(ユーザーの取得・最近の投稿の検索・投稿の作成)を真似た模擬サーバーを Python の標準ライブラリ(http.server)で作り、127.0.0.1 の自分のポートで動かして、送るヘッダー・JSON、401・403・429 の応答の扱い、SDK のページ送りを確かめています。X にはログインしておらず、アカウントも作らず、本物の API には1回も接続していません。模擬サーバーの応答の形は公式ドキュメントの記載に合わせましたが、本物の応答そのものではありません。料金・レート制限・認証・エラーの一覧・開発者ポリシーは、X の公式ドキュメント(docs.x.com)と公式の変更履歴で確かめ、取得した文面は一部を要約で読んでいます。PKCE の計算は RFC 7636 の例の値と照合しました。図は mermaid 11.16.0 で描画を確かめています(確認日 2026年11月18日)。
本記事の内容は、ご自由にお使いください。
ご利用の際は、出典として本ページへのリンクを記載いただけますようお願いします。
(記載例)出典:株式会社RJC「X API(旧Twitter API)の使い方|料金・キーの取得・Pythonで投稿」
X APIとは(旧Twitter APIとの関係・できること)
この節では、X API で何ができるのかと、v2 と v1.1 の違いが分かります。
X API は、X の公開の会話にプログラムからアクセスするための仕組みです。以前は Twitter API と呼ばれていたものと同じで、公式ドキュメントのリクエスト例は https://api.x.com/2/... の URL を使っています。公式は、次のことができると説明しています。
投稿を読む
検索・取得・リアルタイムのストリーミング。
最近7日の検索は全開発者
投稿する
投稿・返信・スレッドの作成。
ユーザーの文脈のトークンが要る
ユーザーを扱う
参照・ブロック・ミュートなど。
フォローはセルフサーブから外れた
分析・連携
指標・トレンド、DM、リスト、スペース。
DM は読み取り単価が高め
| 版 | 公式の位置づけ | 新しく作るなら |
|---|---|---|
| X API v2 | 今の版。新しいエンドポイントと機能はすべてここ。従量課金の料金体系 | こちらを使う(公式の推奨) |
| X API v1.1 | 以前の版。サポートは限られる。一部のメディアのアップロードなどが残る | v2 に無い機能だけ |
| Enterprise | 大量のデータや、セルフサーブで使えない機能(引用の投稿など)向け | 月の上限を超えるとき |
2026年に入ってから、できることの範囲も変わっています。公式の変更履歴には、2026年4月16日に「フォロー・いいね・引用の投稿」がセルフサーブのすべての層の API から外れたこと、2026年2月23日から POST /2/tweets での返信は元の投稿の作者から呼び出された場合に限られる(セルフサーブの層が対象)ことが書かれています。以前の記事のコードがそのまま動かないことがあるのは、このためです。
X APIの料金(2026年11月18日時点の従量課金)
この節では、公式の単価表と、使い方ごとの月の費用の目安が分かります。
X API v2 は従量課金で、サブスクリプションも最低の利用額もありません。開発者コンソールでクレジットを先に買い、リクエストのたびに残高から引かれます。公式の料金ページの主な単価は次のとおりです(米ドル、2026年11月18日時点)。
| 操作(公式の名前) | 単価 | 数え方 |
|---|---|---|
| Posts: Read(投稿の読み取り) | $0.005 | 返ってきた投稿1件ごと |
| User: Read(ユーザーの読み取り) | $0.010 | 1件ごと |
| Following/Followers: Read | $0.010 | 1件ごと |
| DM Event: Read | $0.010 | 1件ごと |
| 自分のデータの読み取り(Owned Reads) | $0.001 | 1件ごと(対象の12のエンドポイント) |
| Post: Create(投稿) | $0.015 | 1リクエストごと |
| Post: Create (with URL)(URL付きの投稿) | $0.200 | 1リクエストごと |
| Post: Create (summoned)(呼び出された返信) | $0.010 | 1リクエストごと |
| DM Interaction: Create | $0.015 | 1リクエストごと |
- 読み取りは「返ってきた件数」で数えます。1回の検索で100件返れば、100件分($0.50)です。
- 重複の除外:UTC の24時間の中で同じものをもう一度取っても、追加の課金はありません。ただし公式は「ソフトな保証」としていて、障害のときなどは除外されないことがあります。
- 月の上限:従量課金のプランでは、投稿の読み取りは請求の期間あたり300万件まで。超える量は Enterprise の案内になります。
- 止まる条件:残高がマイナスになると、補うまでリクエストは止まります。自分で決めた支出の上限に届くと、次の請求の期間まで止まります。
- 自動チャージ:残高がしきい値を下回ると決めた額を補充します。5分に1回までで、残高がゼロ以下の間は止まります。
無料で使えるか・Basic と Pro の扱い
公式の料金ページには、無料の枠(Free)や Basic・Pro の料金表は載っていません。載っているのは次の特典です。
- カードを登録して最初の購入をすると、$20 分の X API のクレジット(公式の変更履歴 2026年10月2日によると、付与から3か月で失効)。
- 最初の自動チャージに対して、最大 $50 分の上乗せ。
- 請求の期間の購入額に応じた xAI のクレジットの還元($200〜$499 で10%、$500〜$999 で15%、$1,000 以上で20%)。
Basic と Pro については、従量課金が始まった2026年2月6日の変更履歴に「Basic と Pro のプランは引き続き使え、契約中の人は従量課金に切り替えられる」と書かれ、以前の Free の層で最近使っていた人に一度だけ $10 分の引換券を出すとあります。いま自分の契約で何が使えるかは、開発者コンソールの表示で確かめるのが確実です。
使い方別の月の費用(Pythonで計算)
公式の単価で、よくある使い方の月の費用を Python で計算しました(30日で計算。為替や手数料は含めない)。
P = {"posts_read": 0.005, "user_read": 0.010, "post_create": 0.015,
"post_create_url": 0.200, "owned_read": 0.001}
cases = [
("1日10件を投稿(URLなし)×30日", 10*30*P["post_create"]),
("1日10件を投稿(URLあり)×30日", 10*30*P["post_create_url"]),
("検索で投稿を1日1,000件読む×30日", 1000*30*P["posts_read"]),
("ユーザー情報を1日100件読む×30日", 100*30*P["user_read"]),
("自分の投稿を1日500件読む(Owned Reads)×30日", 500*30*P["owned_read"]),
]
for n, c in cases: print(f"{n}: ${c:,.2f}")
1日10件を投稿(URLなし)×30日: $4.50
1日10件を投稿(URLあり)×30日: $60.00
検索で投稿を1日1,000件読む×30日: $150.00
ユーザー情報を1日100件読む×30日: $30.00
自分の投稿を1日500件読む(Owned Reads)×30日: $15.00
月300万件を30日で割ると 1日 100000 件 / 31日: 96774
300万件を読むと $15,000.00
同じ100件を24回取得:重複排除が効けば $0.50 /効かなければ $12.00
費用を大きく左右するのは「URL を入れるか」と「検索で何件読むか」です。告知の投稿にリンクを入れるだけで単価が13倍以上になるため、自動投稿を作る前に試算しておくと安心です。
X APIの始め方(開発者コンソールでアプリを作る)
この節では、API キーを受け取るまでの流れが分かります。
入口は開発者コンソール(console.x.com)です。公式の「Getting access」の手順は次の3段階です。
開発者アカウントを作る
console.x.com の「Developer Console」に X のアカウントでサインインし、開発者契約とポリシーに同意して、API の使い道をプロフィールに書く。
アプリを作る
ダッシュボードの「New App」から、名前・説明・用途を入れる。コンソールが鍵とトークンを作る。
鍵をすぐに保存する
鍵は1回しか表示されない。パスワード管理ツールなどに保存する。なくしたら作り直しになり、前の鍵は使えなくなる。
クレジットを用意する
従量課金なので、リクエストの前にクレジットの残高が要る。支出の上限もここで決めておく。
最初のリクエストを送る
公式の例は、Bearer Token で GET /2/users/by/username/xdevelopers を呼ぶもの。読み取りの単価がかかる。
画面の名前は版によって変わることがあるため、上の「」はいずれも公式ドキュメントに出ていた語だけにしています。
APIキーとトークンの種類と認証の選び方
この節では、コンソールで受け取る4種類の鍵の役割と、どの認証を使えばよいかが分かります。
| 公式の名前 | 役割 | 使う場面 |
|---|---|---|
| API Key & Secret | アプリを識別する | OAuth 1.0a の署名など |
| Bearer Token | アプリ専用。公開データの読み取りだけ | 検索・投稿やユーザーの取得 |
| Access Token & Secret | アプリを持つアカウントとして動く | 自分のアカウントで投稿する |
| Client ID & Secret | OAuth 2.0 のユーザーの文脈の認証 | ほかの利用者の許可を得て動く |
アプリ専用(Bearer Token)
公開されている投稿・ユーザーを読む
ヘッダーは Authorization: Bearer トークン
投稿の作成には使えない
ユーザーの文脈(OAuth 1.0a・2.0)
投稿する・自分の情報を読む
そのアカウントの許可で動く
OAuth 2.0 はスコープで範囲を絞れる
OAuth 2.0(認可コード+PKCE)の要点
公式の説明では、OAuth 2.0 の認可の URL は https://x.com/i/oauth2/authorize、トークンの URL は https://api.x.com/2/oauth2/token です。
- アクセストークンは2時間で切れます(
offline.accessのスコープを付けたときだけリフレッシュトークンが出る)。 - 認可コードは受け取ってから30秒以内にトークンと交換する。
- 投稿の作成に要るスコープは
tweet.write・tweet.read・users.read。 - Web アプリ・ボットは client secret を持つ「機密クライアント」、ネイティブアプリと SPA は「公開クライアント」。
code_challenge_methodは S256 か plain。
S256 の code_challenge は、code_verifier の SHA-256 を URL で使える Base64 にして末尾の「=」を除いたものです。手元で RFC 7636 の付録 B の例を計算し、RFC の値と一致することを確かめました。
import base64, hashlib, secrets
v = "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk" # RFC 7636 付録 B の例
ch = base64.urlsafe_b64encode(hashlib.sha256(v.encode()).digest()).rstrip(b"=").decode()
print("challenge:", ch, ch == "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM")
nv = secrets.token_urlsafe(64)[:64] # 本番では毎回作る(43〜128文字)
print("新しい verifier の長さ:", len(nv))
challenge: E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM True
新しい verifier の長さ: 64
OAuth 2.0 そのものの考え方は、関連記事「OAuth 2.0とOpenID Connectの違いをわかりやすく解説」で扱っています。
X API v2の主なエンドポイント(投稿・取得・検索)
この節では、よく使うエンドポイントと、そのレート制限の公式の値が分かります。
まず覚えるのは、投稿の作成・投稿の取得・最近の投稿の検索・ユーザーの取得の4つです。レート制限の値は公式の「Rate limits」の表のとおりで、特に書いていなければ15分あたりです。
| エンドポイント | できること | アプリあたり | ユーザーあたり |
|---|---|---|---|
| POST /2/tweets | 投稿する | 10,000/24時間 | 100/15分 |
| GET /2/tweets/:id | 投稿を1件取る | 450/15分 | 900/15分 |
| GET /2/tweets | 投稿をまとめて取る | 3,500/15分 | 5,000/15分 |
| GET /2/tweets/search/recent | 最近7日の投稿を検索 | 450/15分 | 300/15分 |
| GET /2/users/me | 認証したユーザー自身 | — | 75/15分 |
| GET /2/users/by/username/:username | ユーザー名で取る | 300/15分 | 900/15分 |
| GET /2/users/:id/tweets | あるユーザーの投稿 | 10,000/15分 | 900/15分 |
| 検索 | 範囲 | 使える人 | クエリの長さ | 1回の件数 |
|---|---|---|---|---|
| 最近の検索(/search/recent) | 最近7日 | すべての開発者 | 512文字 | 最大100件 |
| 全期間の検索(/search/all) | 2006年から | 従量課金と Enterprise | 1,024文字 | 最大500件 |
Enterprise ではどちらもクエリが4,096文字まで使えます。検索のクエリに入れる from: などの書き方は、記事「Twitter(X)検索コマンド一覧|公式・非公式を分けた表と検索式作成ツール」で、公式のものとそうでないものを分けて扱っています。
投稿の作成(POST /2/tweets)の本文で使える主な項目は、text(メディアが無いときは必須)、reply.in_reply_to_tweet_id、media.media_ids(1〜4件)、poll.options(2〜4件、各1〜25文字)と poll.duration_minutes(5〜10080)です。quote_tweet_id(引用)は、公式の説明で Enterprise のプランが必要とされています。
Pythonでデータを取得する(requests)
この節では、Bearer Token でユーザーを取得する最小のコードと、そのとき送られるものが分かります。
宛先の URL は環境変数で切り替えられるようにし、鍵もコードに書かず環境変数から読みます。手元では X_API_BASE を模擬サーバー(http://127.0.0.1:18615)に向けて動かしました。本物に向けるときは、この変数を外せば既定の https://api.x.com になります。
import os, json
import requests
BASE = os.environ.get("X_API_BASE", "https://api.x.com")
def bearer_headers(token):
return {"Authorization": f"Bearer {token}"}
def get_user(username):
token = os.environ["X_BEARER_TOKEN"] # 鍵はコードに書かず環境変数から読む
return requests.get(f"{BASE}/2/users/by/username/{username}",
headers=bearer_headers(token), timeout=10)
r = get_user("example_dev")
print(r.status_code, r.headers["content-type"])
print(json.dumps(r.json(), ensure_ascii=False))
模擬サーバーに対して、正しいトークン・違うトークン・環境変数なしの3通りで実行した結果です。
$ X_BEARER_TOKEN=(正しい値) python client_requests.py user
200 application/json
{"data": {"id": "1000000000000000001", "name": "見本アカウント", "username": "example_dev"}}
$ X_BEARER_TOKEN=wrong python client_requests.py user
401 application/problem+json
{"title": "Unauthorized", "detail": "Unauthorized", "type": "about:blank"}
$ python client_requests.py user # 環境変数を設定していない
KeyError: 'X_BEARER_TOKEN'
401 の本文は模擬サーバーで作ったもので、本物の文言ではありません(形は公式のエラーの説明に合わせています)。模擬サーバーの記録には、送られたヘッダーが次のように残りました(トークンは先頭だけ)。
{"method": "GET", "path": "/2/users/by/username/example_dev", "authorization": "Bearer dummy-...", "content-type": null, "user-agent": "python-requests/2.34.2", "body": null}
- 取り出す項目を増やすには
user.fields=created_at,description,public_metricsのようにクエリに足します(公式の例)。 - 公式の例には、投稿の取得
/2/tweets/:id?tweet.fields=created_at,public_metrics、検索/2/tweets/search/recent?query=from:xdevelopersもあります。
タイムアウトや例外の扱いは、関連記事「Pythonのrequestsの使い方|タイムアウト・エラー処理・再試行まで」で扱っています。
Pythonで投稿する(POST /2/tweets)
この節では、投稿のリクエストの形と、Bearer Token で投稿しようとしたときに何が起きるかが分かります。
投稿は JSON で {"text": "..."} を送り、トークンはユーザーの文脈のものを使います。公式のトラブルシューティングにも「一部のエンドポイントはユーザーの文脈の認証(OAuth 1.0a か 2.0)が要る」とあります。
def create_post(text):
token = os.environ["X_USER_ACCESS_TOKEN"] # 投稿はユーザーの文脈のトークン
return requests.post(f"{BASE}/2/tweets", headers=bearer_headers(token),
json={"text": text}, timeout=10)
$ X_USER_ACCESS_TOKEN=(アプリ専用の値) python client_requests.py post
403 application/problem+json
{"title": "Forbidden", "detail": "模型:アプリ専用のトークンでは投稿できない", "type": "https://api.x.com/2/problems/client-forbidden"}
$ X_USER_ACCESS_TOKEN=(ユーザーの値) python client_requests.py post
201 application/json
{"data": {"id": "3000000000000000001", "text": "X API の模擬サーバーへの投稿テスト", "edit_history_post_ids": ["3000000000000000001"]}}
403 の本文は模擬サーバーで作ったもので、本物の文言ではありません。形(type・title・detail)は公式のエラーの説明に合わせています。成功のときの edit_history_post_ids は、公式の仕様と xdk 0.10.6 の型の定義にある名前です。サーバーに届いた本文は次のとおりでした。
{"method": "POST", "path": "/2/tweets", "authorization": "Bearer dummy-...", "content-type": "application/json", "user-agent": "python-requests/2.34.2", "body": {"text": "X API の模擬サーバーへの投稿テスト"}}
鍵の置き場所
公式も環境変数と .gitignore を勧めている
公式Python SDK(xdk)の使い方と注意点
この節では、公式の SDK でのコードの書き方と、手元で分かった「ページ送り」と「429」の挙動が分かります。
公式の SDK は Python の xdk(pip install xdk、Python 3.8 以上)と TypeScript の @xdevplatform/xdk です。Tweepy などのコミュニティのライブラリも公式の一覧に載っていますが、「X が保守しているものではない」と書かれています。xdk の Client は base_url を受け取れるので、模擬サーバーに向けて動かしました。
import os
from xdk import Client
base = os.environ["X_API_BASE"]
c = Client(base_url=base, bearer_token=os.environ["X_BEARER_TOKEN"])
u = c.users.get_by_username(username="example_dev")
pages = 0; posts = 0
for page in c.posts.search_recent(query="from:example_dev", max_results=10):
pages += 1; posts += len(page.data or [])
print(f"page {pages}: {len(page.data)}件 next_token={page.meta.next_token if page.meta else None}")
print("合計", pages, "ページ", posts, "件")
try:
c.posts.create(body={"text": "bearer だけで投稿"})
except Exception as e:
print(type(e).__name__ + ":", e)
c2 = Client(base_url=base, access_token=os.environ["X_USER_ACCESS_TOKEN"])
print("create:", c2.posts.create(body={"text": "xdk から模擬サーバーへ"}).data)
page 1: 10件 next_token=1
page 2: 10件 next_token=2
page 3: 10件 next_token=None
合計 3 ページ 30 件
ValueError: Authentication required for this endpoint. Required schemes: ['OAuth2UserToken', 'UserToken']. Available: []
create: id='3000000000000000001' text='xdk から模擬サーバーへ' edit_history_post_ids=['3000000000000000001']
1for で回すと最後のページまで取る
search_recent は1ページずつ返しながら、続きがある限り自動で次を取った。模擬サーバーには pagination_token=1、2 の要求が届いた。読み取りは件数で課金されるので、要る件数で break する。
2Bearer だけでは送る前に止まる
投稿の作成は OAuth 2.0 のユーザーのトークンか OAuth 1.0a が要る作りで、Bearer だけのときは ValueError になり、サーバーには何も届かなかった。
3429 では待たずに例外
手元の 0.10.6 では、検索の途中で429が返ると requests の HTTPError がそのまま上がった。待ってやり直す処理は自分で書く(次の節)。
429 のときに実際に出た例外と、応答のヘッダー・本文です。
HTTPError: 429 Client Error: Too Many Requests for url: http://127.0.0.1:18615/2/tweets/search/recent?query=from%3Aexample_dev&max_results=10
reset: 1794962608 remaining: 0
body: {"errors": [{"code": 88, "message": "Rate limit exceeded"}]}
公式の「最初のリクエスト」のページは SDK について「認証・ページ送り・レート制限を自動で扱う」と説明していますが、xdk 0.10.6 のソースでは、待ってやり直す処理はストリーミング(streaming.py)の側にあり、通常の取得は raise_for_status() で例外を上げる作りでした。版が上がると変わる可能性があるため、自分の入れた版で確かめるのが確実です。
レート制限と429 Too Many Requestsの待ち方
この節では、レート制限のヘッダーの読み方と、429 のときに待ってやり直すコードが分かります。
応答の x-rate-limit-reset は「窓が戻る時刻」の UNIX 秒です。公式は、429 を受けたらこの時刻まで待ち、必要なら指数バックオフを使うよう勧めています。
| ヘッダー | 意味(公式) |
|---|---|
| x-rate-limit-limit | 窓の中で送れる最大の回数 |
| x-rate-limit-remaining | 窓の中で残っている回数 |
| x-rate-limit-reset | 窓が戻る時刻(UNIX タイムスタンプ) |
import time
def get_with_rate_limit(url, params, token, max_wait=900):
"""429 なら x-rate-limit-reset(UNIX 秒)まで待って1回だけやり直す"""
for attempt in (1, 2):
r = requests.get(url, params=params, headers=bearer_headers(token), timeout=10)
print(f" 試行{attempt}: {r.status_code} remaining={r.headers.get('x-rate-limit-remaining')} reset={r.headers.get('x-rate-limit-reset')}")
if r.status_code != 429:
return r
reset = int(r.headers.get("x-rate-limit-reset", time.time() + 60))
wait = max(reset - time.time(), 0) + 1 # 時計のずれに1秒足す
if wait > max_wait:
raise RuntimeError(f"{wait:.0f}秒待つ必要がある。あとで実行する")
print(f" 429 のため {wait:.1f} 秒待つ")
time.sleep(wait)
return r
模擬サーバーは、確かめやすいように「4秒の窓で3回まで」にしてあります(本物の窓は15分か24時間)。5回続けて検索した結果です。
試行1: 200 remaining=2 reset=1794962562
1回目 → 200(開始から 0.0 秒)
試行1: 200 remaining=1 reset=1794962562
2回目 → 200(開始から 0.0 秒)
試行1: 200 remaining=0 reset=1794962562
3回目 → 200(開始から 0.0 秒)
試行1: 429 remaining=0 reset=1794962562
429 のため 4.4 秒待つ
試行2: 200 remaining=2 reset=1794962567
4回目 → 200(開始から 4.4 秒)
試行1: 200 remaining=1 reset=1794962567
5回目 → 200(開始から 4.4 秒)
- remaining が0になった次の1回が429になり、reset の時刻を過ぎてから送り直すと200に戻りました。
- 本物の窓は15分なので、待ち時間が長くなります。
max_waitを決め、長すぎるときは処理を後に回すほうが扱いやすくなります。 - 公式の開発者ポリシーは、レート制限を「超えたり回避したりしてはいけない」としています。鍵を増やして分散させるような作りにはしません。
待ち方の考え方(固定・指数バックオフ・トークンバケットなど)は、関連記事「レート制限の実装アルゴリズム|6方式を同じ条件で動かして比較」と関連記事「LLM APIの429・529エラー対処|リトライ実装とエラー一覧」で扱っています。
X APIのエラーコード一覧(400・401・403・429)
この節では、HTTP のステータスごとの意味と、エラーの本文の type の読み方が分かります。
| コード | 公式の説明 | まず確かめること |
|---|---|---|
| 400 Bad Request | JSON が不正・クエリの形が違う・必須のパラメーターが無い | 本文の JSON と必須の項目 |
| 401 Unauthorized | 認証情報が無い・無効 | トークンを作り直していないか、ヘッダーが「Bearer 値」の形か |
| 403 Forbidden | 認証は正しいが、その操作の権限が無い | ユーザーの文脈が要る操作か、アプリの権限 |
| 404 Not Found | 存在しない・削除された | ID と URL |
| 409 Conflict | ストリームにルールが無い(フィルタのストリームだけ) | ストリームのルール |
| 429 Too Many Requests | レート制限か利用の上限を超えた | x-rate-limit-reset・残高・支出の上限 |
| 500・503 | サーバー側の問題・混雑 | 待ってやり直す。状態のページを見る |
エラーの本文には type(種類を表す URI)・title・detail が入ります。公式に載っている主な type は次のとおりです。
| type(https://api.x.com/2/problems/ の後ろ) | 意味 |
|---|---|
| invalid-request | リクエストの形やパラメーターが不正 |
| resource-not-found | 対象が存在しない |
| not-authorized-for-resource | 非公開・保護された内容にアクセスできない |
| client-forbidden | アプリが登録されていない、または必要なアクセスが無い |
| usage-capped | 利用の上限を超えた |
| rate-limit-exceeded | レート制限を超えた |
429 は「レート制限」と「利用の上限」の両方で返るため、ヘッダーの remaining が残っているのに429なら、残高や支出の上限を先に見ると切り分けが早くなります。ステータスコード全体の意味は、関連記事「HTTPステータスコード 一覧|全コードの原因と対処・curl実例つき」で扱っています。
利用規約・開発者ポリシーで確かめること
この節では、作り始める前に開発者ポリシーのどこを読むとよいかが分かります。
X API を使う人は、開発者契約と開発者ポリシーに同意して使います。ここでは提供元の説明の一部を紹介します。自分の用途で使えるかどうかは、この記事では言い切りません。最新の規約とポリシーを提供元の文面で確かめ、機密の情報や個人の情報を扱うときは所属先の決まりも事前に確かめると確実です。
- 1ボットであることを示すAPI で動くボットのアカウントは、何のアカウントで誰が責任を持つかをはっきり示す、とある
- 2保存した内容を最新に保つX の内容を保存するなら、X 側で削除・変更されたら手元も削除・変更する
- 3レート制限を超えない・回避しないポリシーに明記されている
- 4非公開の情報には明示の同意DM などの非公開の内容を保存するには、本人の明示の同意が要る
- 5表示するときは内容を変えない公開して見せる X の内容は、元のまま保つ
ポリシーには、ほかに「スパム・ボット・自動化」「投稿の公開表示」「内容の再配布」などの節があります。自動投稿や収集した投稿の再利用を考えているときは、その節を先に読んでおくと手戻りが減ります。
うまくいかないときの症状表と判断表
この節では、よくあるつまずきの原因と、どの方法を選ぶかの目安が分かります。
| 症状 | 原因 | 確かめ方 | 直し方 |
|---|---|---|---|
| 401 Unauthorized | トークンが違う・作り直して前の値が無効 | ヘッダーが Authorization: Bearer 値 か | コンソールの最新の値に替える |
| 投稿で403 | Bearer Token(アプリ専用)で投稿した | 使っている鍵の種類 | Access Token か OAuth 2.0 のユーザーのトークン |
| xdk で ValueError: Authentication required | その操作に合う認証情報を Client に渡していない | Required schemes の表示 | access_token か OAuth 1.0a を渡す |
| 429 が続く | 窓の回数を使い切った・利用の上限 | x-rate-limit-remaining と残高 | reset まで待つ・支出の上限を見直す |
| 急に全部止まった | 残高がマイナス・支出の上限に届いた | コンソールの使用状況 | クレジットを補う・上限を変える |
| フォロー・いいね・引用ができない | 2026年4月にセルフサーブから外れた | 公式の変更履歴 | Enterprise の案内を確かめる |
| 返信が投稿できない | 呼び出されていない投稿への返信(2026年2月〜) | 元の投稿の作者からの呼び出し | 公式の返信の条件を確かめる |
| OAuth 2.0 が2時間で切れる | offline.access を付けていない | 認可のときのスコープ | offline.access を足してリフレッシュする |
| 以前の記事のコードが動かない | v1.1 の書き方・api.twitter.com のまま | URL と版 | v2 のエンドポイントに書き直す |
何を使うかは、次の順に当てはめると決めやすくなります。
- 1公開の投稿を読むだけ → Bearer Token最近7日の検索・ユーザーの取得
- 2自分のアカウントで投稿する → Access Token & Secret(OAuth 1.0a)アプリを作ったアカウントとして動く
- 3ほかの利用者の代わりに動く → OAuth 2.0 PKCEスコープで範囲を絞る。2時間で切れる
- 47日より前の投稿 → 全期間の検索従量課金か Enterprise
- 5月300万件を超える・引用の投稿 → Enterpriseセルフサーブの範囲を超える
| やりたいこと | requests で直接 | xdk(公式 SDK) |
|---|---|---|
| 1回だけ試す・中身を見たい | 向いている(送るものが見える) | 使える |
| ページ送りを任せたい | next_token を自分で回す | for で自動。件数で止める |
| OAuth 2.0 PKCE・トークンの更新 | 自分で書く | 公式は対応と説明 |
| 429 で待ってやり直す | 自分で書く | 0.10.6 では自分で書いた |
よくある質問
この節では、X API について検索の多い疑問に短く答えます。
Q. X API と Twitter API は違うものですか。
同じものです。サービス名が X になり、公式ドキュメントは X API と呼び、例の URL は api.x.com を使っています。
Q. X API は無料で使えますか。
2026年11月18日時点の公式の料金ページは従量課金で、無料の枠の記載はありません。初回の支払い登録で $20 分のクレジット、最初の自動チャージに最大 $50 の上乗せがあります。
Q. 月額いくらですか。
月額の固定料金はなく、使った分だけです。1日10件の投稿(URLなし)なら30日で $4.50、URL付きなら $60.00 でした(本文の試算)。
Q. API キーはどこで取得しますか。
開発者コンソール(console.x.com)で開発者登録をし、「New App」でアプリを作ると表示されます。表示は1回だけなので、その場で保存します。
Q. Bearer Token で投稿できないのはなぜですか。
Bearer Token はアプリ専用で、公開データの読み取り向けだからです。投稿にはユーザーの文脈(OAuth 1.0a の Access Token か OAuth 2.0 のユーザーのトークン)が要ります。
Q. 100件の投稿を検索するといくらですか。
投稿の読み取りは1件 $0.005 なので、100件返れば $0.50 です。UTC の24時間の中で同じ投稿を取り直した分は、原則として課金されません。
Q. 429 が出たら何秒待てばよいですか。
応答の x-rate-limit-reset(UNIX 秒)から今の時刻を引いた秒数です。本文の関数では、時計のずれに1秒足しています。
Q. Python のライブラリは何を使えばよいですか。
公式の SDK は xdk(pip install xdk)です。Tweepy はコミュニティのライブラリとして公式の一覧に載っています。最初は requests で1回送り、送るものを確かめてから SDK に移ると、挙動の違いに気づきやすくなります。
Q. 何年前の投稿まで検索できますか。
最近の検索は7日まで、全期間の検索は2006年からです。全期間の検索は従量課金と Enterprise で使えます。
Q. 鍵が漏れたらどうしますか。
コンソールで作り直します。作り直すと前の鍵は使えなくなります。
まとめ
この節では、記事の要点を5つに絞って振り返ります。
- X API v2 は従量課金。投稿の読み取り1件 $0.005、投稿1回 $0.015、URL付きは $0.200(2026年11月18日時点)。
- 鍵は console.x.com の「New App」で1回だけ表示。環境変数に置き、.gitignore に入れ、漏れたら作り直す。
- 読むだけなら Bearer Token、投稿はユーザーの文脈。OAuth 2.0 のトークンは offline.access が無いと2時間で切れる。
- 429 は x-rate-limit-reset まで待つ。xdk 0.10.6 は待たずに例外を上げたので、待つ処理は自分で書く。
- SDK の for はページを最後まで取る。読み取りは件数で課金されるため、要る件数で止め、支出の上限も決めておく。
参考・出典
確認日はいずれも 2026年11月18日です。
- X Developer Platform「About the X API」:https://docs.x.com/ja/x-api/getting-started/about-x-api
- X Developer Platform「Pricing」:https://docs.x.com/x-api/getting-started/pricing
- X Developer Platform「Getting access」:https://docs.x.com/x-api/getting-started/getting-access
- X Developer Platform「Make your first request」:https://docs.x.com/x-api/getting-started/make-your-first-request
- X Developer Platform「Rate limits」:https://docs.x.com/x-api/fundamentals/rate-limits
- X Developer Platform「Response codes and errors」:https://docs.x.com/x-api/fundamentals/response-codes-and-errors
- X Developer Platform「Create Post」:https://docs.x.com/x-api/posts/create-post
- X Developer Platform「Search introduction」:https://docs.x.com/x-api/posts/search/introduction
- X Developer Platform「Authentication overview」:https://docs.x.com/fundamentals/authentication/overview
- X Developer Platform「OAuth 2.0 Authorization Code Flow with PKCE」:https://docs.x.com/fundamentals/authentication/oauth-2-0/authorization-code
- X Developer Platform「Tools and libraries」:https://docs.x.com/x-api/tools-and-libraries/overview
- X Developer Platform「Python XDK」:https://docs.x.com/xdks/python/overview
- X Developer Platform「Changelog」:https://docs.x.com/changelog
- X「Developer Policy」:https://docs.x.com/developer-terms/policy
- IETF「RFC 7636 Proof Key for Code Exchange by OAuth Public Clients」:https://www.rfc-editor.org/rfc/rfc7636
本記事の内容は、ご自由にお使いください。
ご利用の際は、出典として本ページへのリンクを記載いただけますようお願いします。
(記載例)出典:株式会社RJC「X API(旧Twitter API)の使い方|料金・キーの取得・Pythonで投稿」
株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。
WE ARE HIRING
RJCで一緒に開発しながら、
成長を楽しみませんか?
RJCは、Web・モバイル・AIを活用した開発プロジェクトで、テックリードやPM・PMOも活躍するシステム開発会社です。会社を知る、待遇を確かめる、話を聞いてみる。気になるところ見てみてください!
- 127日年間休日
- 12時間平均残業時間
- 毎日ガチャ遊びココロも大切にする福利厚生。アマギフなどの賞品ラインナップ!
ほかにも、チケットレストラン、書籍読み放題、2年ごとの慰労報奨(休暇 or 金一封)、11期連続の黒字決算。