Threads データ API の使い方：Throk API クイックスタート

1. API キーを取得する

Throk 開発者プラットフォームにログインし、APIキー ページで キーを作成 を押します。キーは sk-throk- で始まります。このドキュメントの例ではすべて sk-throk-... と表記しているので、実際に使うときはご自身のキーに置き換えてください。

API を呼び出すには、有効な API プランが必要です。すべてのキーで、アカウントのクレジットを共有します。

注意

API キーはアカウントのクレジットそのものです。フロントエンドのコード、公開リポジトリ、スクリーンショットには絶対に含めないでください。

2. 最初のリクエストを送信する

すべてのリクエストは https://premium-api.throk.ai に送信し、ヘッダーに Authorization: Bearer <あなたのキー> を付けます。

次のリクエストは、直近 24 時間以内に「ダイエット」に言及した日本語の投稿を検索し、いいね数の多い順に並べて上位 10 件を取得します。

curl -G 'https://premium-api.throk.ai/post/search' \
  -H 'Authorization: Bearer sk-throk-...' \
  --data-urlencode 'keywords=ダイエット' \
  --data-urlencode 'language=ja' \
  --data-urlencode 'max_age_hours=24' \
  --data-urlencode 'sort=like:desc' \
  --data-urlencode 'size=10'

日本語の投稿には language=ja が必要です

language のデフォルトは zh（すべての中国語の投稿）です。日本語の投稿を検索するときは language=ja を付けてください。繁体字中国語（zh-Hant）、広東語（yue）、英語（en）、韓国語（ko）などに絞りたい場合も、同じように language を指定します。付けないと、日本語のキーワードでも、たまたまその語を含む少数の中国語の投稿にしかヒットしません。たとえば直近 7 日間の ダイエット の検索では、language なしだと 59 件、language=ja では 10,000 件以上が見つかりました。詳しくは投稿の言語をご覧ください。

レスポンス（抜粋）：

{
  "content": [
    {
      "post": {
        "url": "https://threads.com/post/DaXXXXXX",
        "code": "DaXXXXXX",
        "caption": "ダイエット中でも罪悪感なしで食べられる夜ごはん……",
        "like_count": 44210,
        "reply_count": 312,
        "post_timestamp": 1790000000
      },
      "user": null
    }
  ],
  "metadata": {
    "total_count": 2815,
    "current_page": 1,
    "page_size": 10,
    "total_pages": 282,
    "credits_consumed": 10
  }
}

total_count の表示は最大 10,000 です。該当する投稿が 10,000 件を超えても total_count は 10,000 のままで、total_pages もそれに合わせて頭打ちになります。言及量を知りたい場合はキーワードトレンドを使ってください。

デフォルトの検索対象は直近 7 日

/post/search で期間を指定しない場合、直近 7 日の投稿を検索します。ほかの期間を対象にするには、max_age_hours（最大 2160、つまり 90 日）または from_timestamp を指定してください。どの期間指定でも遡れるのは最大 90 日です。詳しくは検索ルールをご覧ください。

3. 残りのクレジットを確認する

開発者プラットフォームの概要または クレジット使用履歴 ページで、残高と消費の明細を 1 件ずつ確認できます。API で照会することもでき、その場合もクレジットは消費されません。

curl 'https://premium-api.throk.ai/balance' \
  -H 'Authorization: Bearer sk-throk-...'

{ "credits": 48210 }

呼び出しごとに消費したクレジットは、レスポンスの credits_consumed フィールドに含まれます。消費履歴は GET /balance/history で照会できます。

よくあるエラー

HTTP ステータス	メッセージ	原因
401	Invalid API key	キーの入力ミス、削除済みのキー、またはヘッダーに Bearer プレフィックスがない
402	Insufficient credits	クレジット不足。照会の前に費用を見積もり、クレジットが足りない場合は実行しません
400	その他のメッセージ	パラメータの不足・形式の誤り・範囲外。どのパラメータかはメッセージに書かれます。例：期間が遡れる日数の上限を超えている

エラーレスポンスの形式は常に {"detail": "エラーメッセージ"} です。

次のステップ

• まず検索ルールを読んで、キーワードの照合方法を理解しておくと、無駄な試行錯誤を大きく減らせます。
• Claude、ChatGPT、Codex、Cursor から直接データを調べたい場合は、AI アシスタントで使う（MCP）をご覧ください。
• API プランと料金を比べたい場合は、Throk API プランをご覧ください。