twitterapi.io（唯讀）

此為 twitterapi.io 團隊維護的唯讀技能。它僅涵蓋公開的 X/Twitter 資料：絕不登入 X 帳號、絕不處理 cookies、密碼或代理伺服器，也絕不發文、按讚、追蹤或傳送訊息。

twitterapi.io 是一個獨立第三方公開 X 資料 REST API，與 X Corp 無關。如果您需要 X 官方 API，請至 https://developer.x.com。

使用時機

使用 X 搜尋運算子搜尋貼文（from:、since_time:、min_faves:、lang: …）
查詢使用者個人資料、粉絲、追蹤中
取得使用者的近期貼文、回覆、引用貼文、轉推者、討論串上下文
趨勢、列表、社群
建立公開資料的儀表板、研究資料集或監控任務

核心資訊


基礎網址	`https://api.twitterapi.io`
認證標頭	`x-api-key: YOUR_KEY`（從 https://twitterapi.io/dashboard 取得）
文件	https://docs.twitterapi.io
定價	按次計費，詳見 https://twitterapi.io/pricing
託管 MCP 伺服器	`https://mcp.twitterapi.io/mcp`（12 個唯讀工具）

安全性

從環境變數 TWITTERAPI_IO_KEY 讀取 API 金鑰。絕不硬編碼、列印或提交它。如果缺少該金鑰，請要求使用者在儀表板上建立一個。

最小範例

curl -s "https://api.twitterapi.io/twitter/user/info?userName=jack" \
  -H "x-api-key: $TWITTERAPI_IO_KEY"

import os, requests

BASE = "https://api.twitterapi.io"
HEADERS = {"x-api-key": os.environ["TWITTERAPI_IO_KEY"]}

r = requests.get(f"{BASE}/twitter/tweet/advanced_search",
                 headers=HEADERS,
                 params={"query": "from:jack", "queryType": "Latest"},
                 timeout=30)
r.raise_for_status()
for t in r.json().get("tweets", []):
    print(t["createdAt"], t["text"][:80])

唯讀端點

每個端點的參數名稱可能不同（部分為 camelCase，部分為 snake_case）。請完全按照表格所示複製。

功能	方法	路徑與關鍵參數
依使用者名稱查詢使用者	GET	`/twitter/user/info?userName=`
擴充個人資料	GET	`/twitter/user_about?userName=`
依 ID 批次查詢使用者	GET	`/twitter/user/batch_info_by_ids?userIds=`
搜尋使用者	GET	`/twitter/user/search?query=`
近期貼文	GET	`/twitter/user/last_tweets?userName=`（或 `userId=`）
提及	GET	`/twitter/user/mentions?userName=`
粉絲	GET	`/twitter/user/followers?userName=&pageSize=200`
追蹤中	GET	`/twitter/user/followings?userName=`
依 ID 查詢貼文	GET	`/twitter/tweets?tweet_ids=`
回覆	GET	`/twitter/tweet/replies?tweetId=`
引用貼文	GET	`/twitter/tweet/quotes?tweetId=`
轉推者	GET	`/twitter/tweet/retweeters?tweetId=`
討論串上下文	GET	`/twitter/tweet/thread_context?tweetId=`
進階搜尋	GET	`/twitter/tweet/advanced_search?query=&queryType=Latest`
趨勢	GET	`/twitter/trends?woeid=1`
列表貼文	GET	`/twitter/list/tweets?listId=`
列表成員	GET	`/twitter/list/members?list_id=`
社群貼文	GET	`/twitter/community/tweets?community_id=`
帳戶餘額	GET	`/oapi/my/info`

使用模式

分頁

列表端點會回傳 has_next_page 和 next_cursor。將 next_cursor 作為 cursor 傳入；當 has_next_page 為 false 時停止。請務必設定頁數限制，以免錯誤導致無限分頁。

錯誤處理

400 → 缺少必要參數或搜尋查詢無效（回應中的 detail 會說明如何修正）
401 / 403 → 缺少或錯誤的 x-api-key
402 → 額度不足；停止並告知使用者充值（不要重試）
429 → 達到速率限制；以退避方式重試
5xx → 暫時性錯誤；以退避方式重試

成本意識

每次呼叫都會計費。在可能執行較長時間的迴圈之前（例如取得大型帳號的所有粉絲、數月的搜尋結果），請估算呼叫次數並與使用者確認。

反模式

不要標準化參數名稱；請從表格中直接複製
不要在 402 錯誤時重試
不要記錄或提交 API 金鑰

twitterapi-io-read