Threads 關鍵字搜尋 API
參數依 2026-10-25 規格快照;回應資料列依 2026-11-21 實際 API 回應
快速解答
POST /threads/search/task 會建立一個非同步任務,以單一關鍵字搜尋 Threads 的公開貼文,可用 account_username、start_date 與 end_date(皆含當日)、max_scroll 縮小範圍。輪詢 GET /threads/search/task/{task_id},回應除了任務狀態與計數,也在 data 帶回目前已蒐集的貼文,total_count 為筆數。每則貼文有網址、原生貼文 ID、作者、內文、時間戳記、按讚、回覆與分享數、媒體網址,以及是否為回覆或引用貼文的標記。認證用的是大數軟體核發的 API 金鑰,不是 Threads 的存取權杖。資料以網路爬蟲蒐集 Threads 公開發布的內容。
常見用途
- 追蹤品牌、產品或公共議題在 Threads 上的討論,並取出聲量升高時背後的貼文。
- 為市場研究或學術研究建立特定主題、帶日期的貼文資料集,並用互動數排序。
- 把貼文網址交給回覆與 reactions 端點,了解單則貼文得到的回應。
端點一覽
Base URL 為 https://api.infominer.io/api/v2,每個請求以 auth-header 標頭帶 API 金鑰。
| 方法 | 路徑 | 說明 |
|---|---|---|
| POST | /threads/search/task |
建立關鍵字搜尋任務,可加帳號名稱、日期區間、max_scroll 與 rerun。 |
| GET | /threads/search/task/{task_id} |
輪詢搜尋任務:回傳狀態、completed、total、failed_articles、failed_pages 計數,以及 data 內已蒐集的貼文與 total_count。 |
請求參數
POST /threads/search/task
| 參數 | 位置 | 型別 | 必填 | 預設值/可用值 | 說明 |
|---|---|---|---|---|---|
keyword |
body | string | 是 | 搜尋關鍵字。 | |
account_username |
body | string | 否 | 選填。Threads 帳號名稱。 | |
end_date |
body | string | 否 | 日期區間迄日,含當日(YYYY-MM-DD)。沒有 start_date 時會被忽略。 | |
mask_author |
body | boolean | 否 | false |
設為 true 時,該次回應會移除作者身分欄位。要遮蔽回傳的資料列,請在每次 GET 輪詢時帶上。 |
max_scroll |
body | integer | 否 | 爬取時的捲動上限,不可為負數的整數。 | |
rerun |
body | boolean | 否 | 布林值;重新執行蒐集。 | |
start_date |
body | string | 否 | 日期區間起日,含當日(YYYY-MM-DD)。 |
GET /threads/search/task/{task_id}
| 參數 | 位置 | 型別 | 必填 | 預設值/可用值 | 說明 |
|---|---|---|---|---|---|
task_id |
path | string | 是 | 建立任務時回傳的任務 ID。 | |
mask_author |
query | boolean | 否 | false |
設為 true 時,該次回應會移除作者身分欄位。要遮蔽回傳的資料列,請在每次 GET 輪詢時帶上。 |
回應欄位
| 資料 | 欄位 | 端點 |
|---|---|---|
| 貼文 | id, post_id, url, root_post_id, root_post_url, parent_id, parent_url, author, author_id, author_name, content, tm, tm_crawler, like_count, reaction_count, comment_count, share_count, is_reply, is_quote, reply_to_author, metadata_img, metadata_videos, tag, keyword, source | GET /threads/search/task/{task_id} |
程式碼範例
curl:建立任務
curl -X POST https://api.infominer.io/api/v2/threads/search/task \
-H "auth-header: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"keyword": "登山步道", "start_date": "2026-06-01", "end_date": "2026-06-30", "max_scroll": 5, "mask_author": false}'
curl:以任務 ID 輪詢
curl "https://api.infominer.io/api/v2/threads/search/task/$TASK_ID?page=1&per_page=1000" \
-H "auth-header: YOUR_API_KEY"
Python(requests):建立、輪詢、讀取
import time
import requests
BASE_URL = "https://api.infominer.io/api/v2"
HEADERS = {"auth-header": "YOUR_API_KEY"}
# 1. Create the task
resp = requests.post(
f"{BASE_URL}/threads/search/task",
headers=HEADERS,
json={
"keyword": "登山步道",
"start_date": "2026-06-01",
"end_date": "2026-06-30",
"max_scroll": 5,
"mask_author": False,
},
timeout=30,
)
resp.raise_for_status()
task = resp.json()
# 2. Poll until the task leaves INIT / RUNNING
for _ in range(120):
resp = requests.get(
f"{BASE_URL}/threads/search/task/{task['id']}",
headers=HEADERS,
params={
"page": 1,
"per_page": 1000,
},
timeout=30,
)
resp.raise_for_status()
result = resp.json()
status = result.get("status") or result.get("task", {}).get("status")
if status not in ("INIT", "RUNNING"):
break
time.sleep(15)
else:
raise SystemExit("task still running; poll it again later")
if status == "FAILED":
raise SystemExit("task failed")
if status != "DONE":
print("task ended with status", status, "- results may be incomplete")
# 3. Read the records (use page / per_page to fetch further pages)
for row in result.get("data", []):
print(row.get("url"), (row.get("content") or "")[:60])
示意回應樣本
以下為人工撰寫的示意資料:帳號為 sample_user_n,ID 明顯為假值。欄位名稱取自 2026-11-21 實際的 API 回應,範例只列出部分欄位。
任務完成後的輪詢回應(示意資料)
{
"id": "00000000-0000-4000-8000-000000000001",
"keyword": "登山步道",
"status": "DONE",
"start_date": "2026-06-01",
"end_date": "2026-06-30",
"total": 2,
"completed": 2,
"partial": false,
"timed_out": false,
"failed_articles": 0,
"failed_pages": 0,
"total_count": 2,
"data": [
{
"id": "00000000-0000-4000-8000-000000000003",
"source": "threads",
"keyword": "登山步道",
"post_id": "00000000001",
"url": "https://www.threads.com/@sample_user_1/post/00000000001",
"root_post_id": "00000000001",
"root_post_url": "https://www.threads.com/@sample_user_1/post/00000000001",
"author": "sample_user_1",
"author_id": "0000000001",
"content": "週末走了一條不太熱門的步道,沿途視野很開闊,建議早點出發避開人潮",
"tm": 1781056800,
"tm_crawler": 1781143200,
"like_count": 34,
"reaction_count": 34,
"comment_count": 4,
"share_count": 1,
"is_reply": false,
"is_quote": false,
"reply_to_author": "",
"metadata_img": [],
"metadata_videos": [],
"tag": ""
},
{
"id": "00000000-0000-4000-8000-000000000004",
"source": "threads",
"keyword": "登山步道",
"post_id": "00000000002",
"url": "https://www.threads.com/@sample_user_2/post/00000000002",
"root_post_id": "00000000001",
"root_post_url": "https://www.threads.com/@sample_user_1/post/00000000001",
"parent_id": "00000000001",
"parent_url": "https://www.threads.com/@sample_user_1/post/00000000001",
"author": "sample_user_2",
"author_id": "0000000002",
"content": "請問這條步道雨天好走嗎?下週想安排家人一起去",
"tm": 1781060400,
"tm_crawler": 1781143200,
"like_count": 3,
"reaction_count": 3,
"comment_count": 1,
"share_count": 0,
"is_reply": true,
"is_quote": false,
"reply_to_author": "sample_user_1",
"metadata_img": [],
"metadata_videos": [],
"tag": ""
}
]
}
限制與注意事項
- start_date 與 end_date 皆含當日。只給 end_date 而沒有 start_date 時,上游會忽略這個日期並套用預設區間。
- max_scroll 必須是不為負的整數。
- 輪詢回應會帶回目前已蒐集的資料,任務還在 RUNNING 時就能讀取 data。
- 輪詢回應以分頁回傳:在 GET 請求帶 page 與 per_page(per_page 預設與上限皆為 1000)。回應會標示 page、per_page 與 total_count(目前已蒐集的總筆數),依 total_count 繼續讀取後續頁面。
- 搜尋可回溯的期間、每個任務的筆數與更新頻率,依專案範圍確認。
更多 Threads API 頁面
申請試用
填寫下方申請表單時,請註明 Threads,並說明要搜尋的關鍵字或帳號、是否需要回覆與 reactions,以及是否需要遮蔽作者欄位。我們會確認範圍,並回覆試用與 API 金鑰的安排。
填寫表單申請試用,專人確認範圍後回覆試用與介接安排。
填寫申請表單常見問題
- 這和 Meta 官方 Threads API 的關鍵字搜尋有什麼不同?
- Meta 官方 Threads API 的關鍵字搜尋要以 Threads 使用者的存取權杖呼叫,並需要 threads_keyword_search 權限;這項權限通過 Meta 的應用程式審查之前,只能搜尋授權帳號自己的貼文。本端點是另一項服務:回傳的是大數軟體以網路爬蟲蒐集的公開貼文,用大數軟體核發的 API 金鑰呼叫。
- 搜尋結果會包含回覆嗎?
- 會。搜尋結果的資料列若是回覆,is_reply 為 true,並帶有 reply_to_author,以及指向被回覆貼文與所屬討論串的 parent_id、parent_url、root_post_id、root_post_url。
- 結果可以不帶作者資訊嗎?
- 作者欄位可以。在每次 GET 輪詢請求帶 mask_author=true,該次回應會移除 author、author_id、author_name 與 reply_to_author。url 會保留,而 Threads 貼文網址本身含有帳號名稱;若不能留存帳號名稱,請一併捨棄 url。
- 資料是怎麼蒐集的?這是 Threads 官方的 API 嗎?
- 資料以網路爬蟲蒐集 Threads 公開發布的內容。大數軟體與 Meta、Threads 沒有隸屬或合作關係,這也不是 Meta 提供的 Threads API。是否適用於您的用途,依用途與法域由買方法務評估,我們可提供來源與蒐集方式說明。