X 資料 API
X 主頁、貼文、回覆、追蹤圖譜與趨勢，透過一個 REST 介面回傳規範化 JSON。
- 10 個能力族
- 10 個文件化端點
按能力族分組的端點彙總
帳號身份：主頁查詢，回應含簡介、認證與粉絲欄位的規範化 JSON。
| 方法 | 路徑 | 能力 |
|---|---|---|
| GET | /v1/x/users/{username} | x.profile |
發佈與動態流：帳號、主題標籤或音樂頁發佈過的內容，按序回傳。
| 方法 | 路徑 | 能力 |
|---|---|---|
| GET | /v1/x/users/{username}/posts | x.user_posts |
單內容查詢：一則內容及其附屬資料——留言、按讚者、媒體——全部規範化回傳。
| 方法 | 路徑 | 能力 |
|---|---|---|
| GET | /v1/x/posts/{id}/comments | x.comments |
搜尋與趨勢：內容與帳號的關鍵字搜尋、熱搜榜與趨勢話題。
| 方法 | 路徑 | 能力 |
|---|---|---|
| GET | /v1/x/search/posts | x.search_posts |
關係圖譜：追隨者與追蹤清單，以分頁的規範化 JSON 回傳。
| 方法 | 路徑 | 能力 |
|---|---|---|
| GET | /v1/x/users/{username}/followers | x.user_followers |
關係圖譜：追隨者與追蹤清單，以分頁的規範化 JSON 回傳。
| 方法 | 路徑 | 能力 |
|---|---|---|
| GET | /v1/x/users/{username}/following | x.user_following |
發佈與動態流：帳號、主題標籤或音樂頁發佈過的內容，按序回傳。
| 方法 | 路徑 | 能力 |
|---|---|---|
| GET | /v1/x/users/{username}/replies | x.user_replies |
單內容查詢：一則內容及其附屬資料——留言、按讚者、媒體——全部規範化回傳。
| 方法 | 路徑 | 能力 |
|---|---|---|
| GET | /v1/x/users/{username}/media | x.user_media |
常見問題
關於X資料 API
什麼是X資料 API？
X資料 API 是 FetchPI 面向X的讀取介面：一組有文件的 REST 端點，把公開可得的X資料以結構化 JSON 回傳。你不需要解析頁面，也不需要維護專門的爬蟲——呼叫一個端點，讀取欄位名穩定的規範化回應，其 schema 形態與所有 FetchPI 平台一致。全部 10 個文件化端點按能力族組織，每個能力族都有獨立的參考頁、參數表與範例。
X資料 API 能取得哪些資料？
API 涵蓋上表列出的X能力族：共 10 個能力族、10 個端點，每個都有參數與回應 schema 文件。典型場景包括主頁資料補充、貼文與留言採集、粉絲圖譜分析、關鍵字監控與趨勢追蹤。每個能力族回傳的具體欄位見其能力頁——契約之外的資料類型，API 一概不承諾。
X目前已發布的能力族：
- profile
- user_posts
- post
- comments
- search_posts
- user_followers
- user_following
- user_replies
- user_media
- trends
如何使用X資料 API
從零到第一次拿到回應，只需三步：
第 1 步——註冊免費帳號
在控制台註冊。系統會自動建立工作區，註冊贈送的點數可用於最初幾次呼叫。
第 2 步——取得 API 金鑰
在控制台建立金鑰，之後每個請求都透過標準的 Authorization: Bearer 標頭攜帶它。
第 3 步——呼叫端點
從一個有文件的端點開始，例如 GET /v1/x/users/{username}，然後從回應中讀取規範化 JSON。下面的範例可直接複製，使用契約自帶的示範值：
curl -H "Authorization: Bearer $FETCHPI_API_KEY" \
"https://fetchpi.com/v1/x/users/newdev"資料新鮮度如何運作
每個端點都接受整個資料 API 統一的 freshness 參數：cache 直接回應儲存快照、不觸及上游；live 擷取較新的資料，可能產生額外點數費用；max_age 以秒為單位限定可接受的資料年齡。回應 meta 區塊會報告產生每個答案的模式、資料年齡與服務層，讓下游系統基於事實處理新鮮度，而不是靠猜。API 不承諾上游的即時狀態——meta 區塊就是你實際拿到什麼的如實報告。
X資料 API 與自建爬蟲的比較
自建X爬蟲意味著順利路徑歸你，其餘一切也歸你：頁面結構會變、反爬措施會收緊，每個解析修復都要排進你的時程。資料 API 把這些維護工作變成一紙契約——有文件的請求與回應 schema、為查無資料與限流場景發布的錯誤碼，以及所有 FetchPI 平台共用的同一套整合形態。邊界對雙方都保持誠實：API 只提供公開可得的資料，從不要求你的帳號憑證，它也不是X官方產品。
為什麼團隊用 FetchPI 取得X資料
三個理由，都體現在整合過程裡，而不只是宣傳裡：
- 統一的規範化 schema——X回應與所有 FetchPI 平台使用同一套欄位結構，多平台管線只需解析一次。
- 新鮮度透明——每個回應都報告自己的新鮮度模式、資料年齡與服務層；每次請求你自行選擇 cache 或 live，並按此付費。
- 按量計費——按次計點數，每個能力價格公開，沒有席位費也沒有固定套餐；meta 區塊報告每次呼叫的實際消耗。
費用與限制
按次以點數計費：每個能力都有公開的單次呼叫價格，快取命中比即時擷取便宜，儲值自助完成。端點有速率限制——觸發限流的呼叫會回傳文件中定義的 RATE_LIMIT_EXCEEDED 錯誤，而不是靜默失敗——每個回應的 meta 區塊也會報告本次消耗的點數。各能力的目前價格見定價頁；錯誤碼與限流的完整參考見文件。