Threads キーワード検索 API

パラメータは 2026-10-25 の仕様スナップショット、レスポンスの行は 2026-11-21 の実レスポンスで確認

要点

POST /threads/search/task は、1 つのキーワードで Threads の公開投稿を検索する非同期タスクを開始します。account_username、start_date と end_date(いずれも当日を含む)、max_scroll で絞り込めます。GET /threads/search/task/{task_id} をポーリングすると、タスクのステータスと件数に加えて、その時点までに収集した投稿が data に、件数が total_count に返ります。各投稿には URL、ネイティブの投稿 ID、投稿者、本文、タイムスタンプ、いいね・返信・シェアの件数、メディア URL、返信・引用のフラグが含まれます。認証には Threads のアクセストークンではなく、LargitData の API キーを使います。データは Threads で公開されているコンテンツをウェブクローラーで収集したものです。

主な用途

  • ブランド、製品、社会的な話題が Threads でどう語られているかを追い、急増の背景にある投稿を取り出す。
  • 市場調査や学術研究のために、あるテーマの投稿を日付付きで集め、エンゲージメント数で並べる。
  • 投稿 URL を返信 API と reactions API に渡し、1 件の投稿がどう受け止められたかを確認する。

エンドポイント

Base URL は https://api.infominer.io/api/v2 です。API キーは auth-header リクエストヘッダーで送信します。

メソッドパス説明
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 — クロール時のスクロール上限(0 以上の整数)。
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 は当日を含みます。start_date なしで end_date だけを指定すると、上流側はその指定を無視して既定の期間を適用します。
  • max_scroll は 0 以上の整数です。
  • ポーリングレスポンスにはその時点までに収集した行が含まれるため、タスクが RUNNING の間も data を読み取れます。
  • ポーリングレスポンスはページ単位で返ります。GET リクエストで page と per_page を指定します(per_page は既定値・上限とも 1000)。レスポンスには page、per_page と、その時点までの総件数 total_count が示されるので、total_count 件に達するまで次のページを読み取ってください。
  • 遡れる期間、1 タスクあたりの件数、更新頻度はプロジェクトの範囲に応じて確認します。
収集方法:各プラットフォームで公開されているコンテンツをウェブクローラーで収集しています。ご利用目的に適するかどうかは、用途と法域に応じて買い手側の法務部門でご判断ください。収集元と収集方法の説明はご提供できます。

ほかの Threads API ページ

トライアルの申し込み

下の申込フォームに Threads と明記し、キーワードやアカウント、返信と reactions の要否、投稿者フィールドを伏せる必要があるかをお知らせください。範囲を確認し、トライアルと API キーの進め方についてご連絡します。

フォームにご記入のうえ、トライアルをお申し込みください。担当者が範囲を確認のうえ、トライアルと連携の進め方をご返信します。

申込フォームに記入する

よくある質問

Meta の Threads API のキーワード検索とは何が違いますか?
Meta の Threads API のキーワード検索は Threads ユーザーのアクセストークンで呼び出し、threads_keyword_search 権限が必要です。この権限が Meta のアプリレビューで承認されるまでは、認証したユーザー自身の投稿しか検索できません。本エンドポイントは別のサービスで、LargitData のウェブクローラーが収集した公開投稿を、LargitData が発行する 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 にはアカウント名が含まれるため、アカウント名を保持できない場合は url も破棄してください。
データはどのように収集していますか?Threads の公式 API ですか?
Threads で公開されているコンテンツをウェブクローラーで収集しています。当社は Meta および Threads と提携しておらず、Meta が提供する Threads API ではありません。ご利用目的に適するかどうかは、用途と法域に応じて買い手側の法務部門でご判断ください。収集元と収集方法の説明はご提供できます。