X の投稿とプロフィールの JSON、フィールド別: エージェント向けリファレンス
更新日
UnifAPI の無料 X エンドポイントが投稿、プロフィール、ページ、レート制限、エラーで返す全フィールドを、型と扱うべきエッジケース付きで解説。
要点: UnifAPI の X エンドポイント（ログイン不要で無料、訪問者ごとのレート制限付き）は、3 つのレコード（
post、profile、リストを包むpage）と、1 つのエラー形式、3 つのレート制限ヘッダーを返します。フィールド名は camelCase、id は文字列（2^53 を超えるため）、日付は UTC の ISO 8601、カウントは整数で、X が報告しないものはゼロではなく欠落します。このページでは、すべてのフィールドを型と、プログラムが扱うべきケースとともに列挙します。元の投稿にrepostedByを添えたリポスト、1 段だけネストする引用、カウントは返すが投稿は返さない保護されたアカウント、そして X がほとんどの投稿で報告するがすべてではないviewsです。
モデルは、見たことのある JSON を読むのが得意です。データソースを正しく使うエージェントと、フィールド名を推測するエージェントの違いは、リファレンスがコンテキストにあったか、学習データにあったかです。これがそのリファレンスです。人向けのビューアページが描画しているのと同じモデルなので、/tools/x-profile-viewer で見えるものは、/tools/x/profile?handle=… が返すものそのものです。
規約
- id は文字列。 X の id は 64 ビットで、JSON の数値は 2^53 を超えると精度を失います。URL やカーソルの中も含め、すべての
idは文字列です。 - 日付は ISO 8601、UTC。
createdAtとjoinedAtは2026-10-05T22:33:56.000Zのような形です。 - カウントは整数。 整形済みの文字列でも null でもありません。X が報告しなかったカウントは 0 にはならず、省かれます。
- optional は欠落を意味する。 optional と記したフィールドは、値がないときオブジェクトから消えます。
=== 0ではなく"views" in post.metricsで判定してください。 - URL は正規の x.com URL。
post.urlはhttps://x.com/<handle>/status/<id>で、メディア URL は X の CDN を指し、再ホストされることはありません。
post
/tools/x/post が（post として）返すほか、profile、media、search の posts.items の各要素、replies の replies.items の各要素として返されます。
| フィールド | 型 | 意味 |
|---|---|---|
id | string | 投稿 ID |
text | string | 全文。長文投稿（ノート）は全文が返り、メディアが添付されているときは末尾のメディア短縮リンクが取り除かれる |
createdAt | string（ISO 8601） | 公開時刻 |
language | string（optional） | X が検出した BCP-47 コード（en、ja、…） |
conversationId | string（optional） | この投稿が属するスレッドのルート投稿の id |
inReplyToPostId | string（optional） | 返信の場合、返信先の投稿 |
possiblySensitive | boolean | X 自身のフラグ |
url | string | 正規の x.com URL |
author | profile または null | 著者。null になるのは X が伏せた場合のみ |
metrics | object | 下記参照 |
media | media の配列 | ない場合は空 |
repostedBy | object または null | このエントリがリポストのときにセットされる。リポストしたアカウントの { id, handle, name }。レコードの残りは元の投稿 |
quoted | post または null | 引用投稿の場合、引用元の投稿。1 段だけネストする（引用の中の引用は展開されない） |
metrics
| フィールド | 型 | 意味 |
|---|---|---|
likes | integer | |
reposts | integer | リポスト（リツイート）。引用は含まない |
replies | integer | X の返信数。読める公開返信の数を上回ることがある |
quotes | integer | 引用投稿 |
bookmarks | integer | |
views | integer（optional） | インプレッション。X はほとんどの投稿で報告するが、しない場合は欠落 |
media
| フィールド | 型 | 意味 |
|---|---|---|
kind | photo | video | animated_gif | |
url | string（optional） | フルサイズの画像。動画と GIF ではポスターフレーム |
previewUrl | string（optional） | 現在は url と同じ。小さいレンディション用に予約 |
width, height | integer（optional） | 元の寸法 |
durationMs | integer（optional） | 動画の長さ |
videoUrl | string（optional） | X が公開する最高ビットレートの MP4、X の CDN 上 |
profile
/tools/x/profile、/tools/x/media、/tools/x/followers が（profile として）返すほか、post.author として、また followers の users.items の各要素として返されます。
| フィールド | 型 | 意味 |
|---|---|---|
id | string | ユーザー ID |
handle | string | @ なし、X 側の大文字小文字のまま（NASA） |
name | string | 表示名 |
verified | boolean | 何らかの認証（青、政府、ビジネス） |
verifiedType | string（optional） | X が種類を示す場合の Government、Business、… |
protected | boolean | 投稿が非公開。エンドポイントはカウントを返すが投稿は返さない |
bio | string | 空のこともある |
location | string | 自由記述、空のこともある |
website | string（optional） | 展開済みの URL。t.co の短縮リンクではない |
joinedAt | string（ISO 8601） | |
avatarUrl | string（optional） | 400×400 のレンディション |
bannerUrl | string（optional） | |
followers | integer | |
following | integer | |
posts | integer | 累計投稿数 |
listed | integer（optional） | アカウントが掲載されているリストの数。報告される場合 |
pinnedPostId | string（optional） | |
url | string | https://x.com/<handle> |
/tools/x/profile は engagementRate を追加します。ページ内のオリジナル投稿 1 件あたりのいいね、返信、リポスト、引用の平均をフォロワー数で割り、有効数字 4 桁のパーセンテージにしたものです。リポストは平均から除外されます。フォロワー 9,000 万のアカウントでは小さな数値（0.0058）になりますが、それはバグではなく正しい値です。
page
リストはすべて次の形で包まれます。
{ "items": [ … ], "hasMore": true, "nextCursor": "DAAHCgABHUAq3YL__-wLAAIAAAATMj…" }
| フィールド | 型 | 意味 |
|---|---|---|
items | array | post レコード、followers では profile レコード、または community レコード |
hasMore | boolean | nextCursor がセットされているときだけ true |
nextCursor | string または null | 不透明。cursor= としてそのまま返すと次のページを取得できる |
ページサイズ: profile は投稿 10 件、media は 12 件、replies、search、communities は 20 件、followers は 50 件、トレンドは 30 件。カーソルは不透明で、20@ のようなものもあれば、X 自身の DAAH… 文字列のようなものもあります。決してパースしないでください。
トレンドとコミュニティ
/tools/x/trends は { woeid, locationSlug, generatedAt, trends: [ { rank, name, postCount?, url } ] } を返します。postCount は X が投稿量を報告するトレンドにだけ存在し、現在ほとんどの地域ではひとつもないので、optional として扱ってください。url は x.com 上のライブ検索です。
/tools/x/communities は { query, communities: page } を返し、各要素は { id, name, description, memberCount?, access?, joinPolicy?, createdAt?, url } です。
レート制限ヘッダー
成功でもエラーでも、すべてのレスポンスに付きます。
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 17
X-RateLimit-Reset: 1791357984
Reset は、現在の 10 分ウィンドウが終わる Unix 秒です。検索は 2 ユニット、それ以外は 1 ユニットを消費します。429 には秒単位の Retry-After が加わります。
エラー
2xx 以外のレスポンスはすべて次の形です。
{ "error": { "type": "not_found", "message": "X user not found: @nobody_here_123" } }
type | HTTP | 発生条件 |
|---|---|---|
validation_error | 400 | 入力の欠落または不正（Missing handle: pass ?handle=…） |
not_found | 404 | 該当するアカウントや投稿がない。凍結されたアカウントはメッセージにその旨が書かれる |
rate_limited | 429 | 無料の上限に到達。本文に retryAfterSeconds と upgrade が加わる |
upstream_error | 502 | X のデータレイヤーがエラーで応答した |
upstream_unavailable | 503 | タイムアウトまたは到達不能 |
not_configured | 503 | デプロイに上流の認証情報がない |
分岐は type で行ってください。message は人向けで、変わることがあります。
Markdown モード
任意のエンドポイントに format=md を付けるか Accept: text/markdown を送ると、同じレコードが Markdown として描画されます。著者を含む見出し、テキスト、指標の行、メディアリンク、URL、そして次のカーソルを示すフッターです。著者オブジェクト内の生の id を除く上記のすべてのフィールドを含み、プロフィールやスレッドをモデルのコンテキストに入れる最も安上がりな方法です。
サンプルの置き場所
各ツールの Markdown ページには、そのエンドポイントで実際に取得したレスポンスが、数件分に刈り込んで載っています。/tools/x-profile-viewer/index.md、/tools/x-post-viewer/index.md、/tools/x-search/index.md などです。/llms.txt には 8 つすべてが例の URL 付きで掲載されています。従量課金の X / Twitter API はワークスペースキーの背後で同じフィールド名を使うので、無料エンドポイント向けに書いたコードは修正なしで移行できます。