socialcrawl

SocialCrawl API

ソーシャル、コマース、リサーチのデータを、1つの API キーと1つのレスポンス形式で利用できます。リストは { items, next_cursor?, total? } 形式です。変換パイプラインをスキップするには、?format=raw を追加してください。以下のファイルはすべて references/ にあります。タスクに必要なファイルだけを開いてください。

API キー

ライブ API の呼び出しが必要な場合に限り、API キーを確認してください。ドキュメント、機能、料金、コード生成に関する質問にはキーは必要ありません。

内容を表示せず、次の順に確認してください。

1. 環境変数： SOCIALCRAWL_API_KEY が sc_ で始まり、サンプル用のプレースホルダーではない場合は、その値を使用します。
2. 設定ファイル： 環境変数が設定されていない場合は、~/.config/socialcrawl/api_key を現在のプロセスの SOCIALCRAWL_API_KEY に読み込みます。POSIX シェルでは、SOCIALCRAWL_API_KEY="$(<"$HOME/.config/socialcrawl/api_key")"; export SOCIALCRAWL_API_KEY を使用します。PowerShell では、$env:SOCIALCRAWL_API_KEY = (Get-Content -LiteralPath "$HOME/.config/socialcrawl/api_key" -Raw).Trim() を使用します。
3. キーがない場合： https://socialcrawl.dev/dashboard でキーを作成またはローテーションし、SOCIALCRAWL_API_KEY として、または ~/.config/socialcrawl/api_key に設定するようユーザーに伝えます。チャットにシークレットを貼り付けるよう求めてはいけません。設定したとユーザーが伝えるまで、ライブ API を呼び出さずに待ちます。

キーを表示、貼り付け、ログ出力、返却してはいけません。生成するコード、コマンド、URL、エラーメッセージ、保存するトランスクリプトに、キーの値を直接記載してはいけません。例では、変数参照として $SOCIALCRAWL_API_KEY（POSIX）または $env:SOCIALCRAWL_API_KEY（PowerShell）を使用してください。キーがチャットまたは出力に含まれていた場合は、ダッシュボードでキーを無効化し、新しいキーを作成するようユーザーに伝えてください。

最初のライブ API 呼び出し

セッション中に最初のライブ API を呼び出す前に、次の手順を実施してください。

1. 上記の手順で API キーを確認します。キーがない場合、またはプレースホルダーの場合は、呼び出しを行わずに中止します。
2. 無料の残高エンドポイント（クレジット消費なし）でキーを検証します。

   curl -s -H "x-api-key: $SOCIALCRAWL_API_KEY" "https://www.socialcrawl.dev/v1/credits/balance"
   

3. 成功した場合は残高を表示し、ユーザーのリクエストに進みます。
4. 失敗した場合は、リクエストヘッダーやキーを含めずにエラーを報告し、references/errors.md に従ってください。

最新性の確認（セッションごとに1回実施）

このファイルは、次のフィンガープリントを持つレジストリのスナップショットです。

registry_fingerprint: 61a90b6d5dadcc038c3e4d4165f85f74177c77c5c5dfc9c2b7712c2f5d4ddaa4
generated_at: 2026-10-07

残高の確認に加えて、無料の呼び出しを1回行います。

curl -s -H "x-api-key: $SOCIALCRAWL_API_KEY" "https://www.socialcrawl.dev/v1/utility/endpoints?fingerprint=1" | head -c 400

• data.fingerprint が上記の registry_fingerprint と一致する場合 — 同梱ファイルを使用して先に進みます。
• 一致しない場合 — このコピーとライブ API の内容に差異があります（スキルまたはサーバーが新しくなっている可能性があります）。料金、パラメーター、またはエンドポイントが変更されています。ライブレジストリを信頼できる情報源として扱い、ファイルで確認できないことは /v1/utility/*（すべて無料）で確認します。ユーザーには一度だけ、簡潔に次のように伝えます：「この SocialCrawl スキルはライブ API と一致していません。更新するには npx skills update socialcrawl --yes を実行してください。」その後、ユーザーの質問に回答します。繰り返し伝えたり、許可を求めたりしてはいけません。
• data.fingerprint がない場合（404、または古いサーバーが通常のリストを返す場合） — 件数に基づいて判断します。references/index.md の冒頭にある合計件数と、/v1/utility/endpoints の data.stats.platforms および data.stats.endpoints を比較します。ライブ側の数値のほうが大きい場合は、上記と同様に対応します。
• 呼び出しに失敗した場合（キーがない、オフライン、200 以外） — 何も伝えずにスキップします。この確認によってリクエストを止めてはいけません。

ワークフロー

1. まず呼び出し先を探します（無料、0 クレジット、実行なし）。 GET /v1/utility/find?task=<the job in plain words> は、その作業に適したエンドポイントを順位付けし、それぞれに method、path、params_filled（入力した語句から取得）、missing、estimated_credits を返します。uncertain が false の場合は、results[0] をそのまま呼び出します。method、path、params はすぐに使える呼び出し内容です（不足している missing パラメーターを追加してから、コストルールを適用してください）。uncertain が true の場合は、選択肢を提示します。複数の呼び出しが必要な作業（プロフィール、投稿、コメントの順に取得する場合や、ブランドを監視する場合）では、GET /v1/utility/plan?query=<the job> が、パラメーター、料金、各ステップの入力元となるステップを含む呼び出し順を返します。書き込みまたは課金に関するリクエストは結果を返しません。
2. オフラインの場合、find または plan が 404 を返した場合（古いサーバーの場合は既存のフローにフォールバック）、または uncertain が true の場合は、同梱ファイルを参照してください。 下記のよくある作業に従うか、references/index.mdを grep してください。そこには、作業とレシピの対応表と、各エンドポイントの行（grep -i transcript references/index.md）があります。レシピを使う場合は、そのセクションだけを読みます。grep -n '^## ' references/recipes.md で行番号を確認し、ファイル全体は開かないでください。エンドポイントを使う場合は、プラットフォームファイルの目次（先頭から最初の ## まで）を読み、その後、該当するセクションだけを読みます。grep -nE '^## (GET|POST|PUT|PATCH|DELETE) /v1/<platform>/<resource> - ' references/<platform>.md を実行し、その行から次の ## までを読みます。このセクションには、正確なコスト、キャッシュ TTL、ページネーション、すべてのパラメーター、レスポンスフィールド、課金前に確認する制約が記載されています。
3. 見積もります。 正確なリクエストを組み立て、以下のコストゲートを適用します（少額の定額呼び出しは1行で、大量または従量課金の呼び出しはreferences/cost-gate.mdの完全な事前確認を行います）。見出しの数値は、リクエスト全体の合計ではなく、行単位またはページ単位の料金である場合があります。
4. 呼び出します。 キーを解決してから、HTTP メソッドと本文の形式を維持し、セクションに示されたとおりにリクエストを実行します。ユーザーがこの有料リクエストの実行をすでに依頼している場合は、コストの開示だけで十分です。ただし Ask レベルでは常に確認してください（Cost rule のゲートを参照）。それ以外の場合は、ユーザーが許可していない有料呼び出し、または範囲の拡大を行う前にのみ確認します。
5. 報告します。 データを返し、続けて credits_used と credits_remaining を報告します。非同期ジョブの場合は、送信時の保留額と、完了時に確定した請求額を報告します。

よくある作業

エージェントが最もよく受ける依頼に対する最初の呼び出しです。レジストリのレシピから生成されます（{x}には値を入力してください）。findを使うと、入力した値で同じ結果が得られます。

作業	最初の呼び出し	次に行うこと
投稿へのコメントをCSVに出力	GET /v1/tiktok/post/comments?url={url}&sort=recent&scan_pages=3	paginate.pyをto_csv.py --archetype Commentにパイプで渡します。どのプラットフォームでも<platform>/post/commentsを使用します。レシピ
ニッチ分野、フォロワー数、国でクリエイターを検索	GET /v1/search/creators?query={niche}&sources=tiktok,instagram&min_followers={min_followers}	search/creatorsには国のフィルターがありません。 レシピ。特定の国の場合：レシピ。予算が限られている場合：レシピ
複数の小売店における商品のレビュー	GET /v1/prism/product-reviews?query={product}	Amazon、Google Shopping、Trustpilotのレビューに対応しています。Walmart、Target、Home Depotの場合は<retailer>/reviewsを使用します。レシピ
株価とニュース	GET /v1/finance/ticker-search?keyword={company}	次にfinance/quote（quote.price.current）とfinance/newsを使用します。レシピ
YouTubeの文字起こし	GET /v1/youtube/video/transcript?url={url}	レシピ
新しい投稿や変更の通知	POST /v1/monitors（本文はrecipe: instagram/profile/posts）	GET /v1/utility/estimate?id=monitorsが200を返す場合に限り、作成せずに検証と料金の見積もりを行うため、最初に?dry_run=1を送信します。それ以外の場合は依頼内容を説明し、ユーザーの同意を得るまで何も作成しません。ページの場合はweb/monitorsを使用します。レシピ
投稿URLのリストに対する統計	POST /v1/prism/post-stats（JSON本文はurls）	URLのファイルの場合はbatch.py --urlsを使用します。レシピ
韓国語／Naver検索	GET /v1/naver/brief?query={keyword}&corpora=news,blog,cafearticle	1つのコーパスの場合はnaver/blog/search、naver/news/searchを使用します。レシピ
プロフィールの検索	GET /v1/tiktok/profile?handle={handle}	どのプラットフォームでも<platform>/profileを使用します。複数のハンドルの場合はprism/profilesを使用します。レシピ
Webページのスクレイピング	GET /v1/web/scrape?url={url}	構造化フィールドの場合はweb/extractを使用します。サイト全体の場合はweb/crawlを使用します。
Web全体でのブランドへの言及	GET /v1/prism/brand-mentions?keyword={brand}&date_from={start_date}&include=digest	レシピ
複数のプラットフォームで1つのトピックを検索	GET /v1/search/multi?query={topic}&platforms=tiktok,instagram,youtube&relevance=filter	レシピ

ヘルパー

scripts/ に同梱されたスクリプト（Python 3）です。キーは SOCIALCRAWL_API_KEY または ~/.config/socialcrawl/api_key から読み込み、出力することはありません。詳細は各スクリプトの --help をご覧ください。

python3 scripts/sc.py tiktok/profile handle=nike          # one call; JSON to stdout, credits_used to stderr
python3 scripts/paginate.py tiktok/post/comments --items 500 --max-credits 20 url=<post_url> > rows.jsonl   # page to N rows within a budget
python3 scripts/to_csv.py --archetype Comment --in rows.jsonl --out comments.csv   # rows to CSV with stable columns
python3 scripts/batch.py --urls links.txt > stats.jsonl   # stats for a file of post URLs (prism/post-stats, or one prism/jobs job past 500)
python3 scripts/estimate.py tiktok/post/comments --items 500 --offline url=<post_url>   # quote offline from assets/endpoints.json

コードのリクエスト： セクションとコストゲートを確認し、課金単位を明記したコメントを含めて、環境変数から SOCIALCRAWL_API_KEY を読み込むスニペットを書き、実行せずに提示してください。

機能や料金に関する質問： インデックスと references/pricing.md（コスト、ティア、パック、返金、無料エンドポイントの一覧）を参照して回答してください。認証、エンベロープ、ページネーション、ラベル、キャッシュ、冪等性については references/api-overview.md を参照してください。無料の /v1/utility/* 呼び出しについては、ライブレジストリを参照して回答してください。endpoints（?platform=、?search= で絞り込み）、endpoint?id=tiktok/profile（1 つのエンドポイントと、実測されたフィールド入力率）、plan?query=、quickstart があります。

プラットフォームが不明確な場合： ユーザーがプラットフォームを指定せずに「@nikeのプロフィールを取得して」と言った場合は、どのプラットフォームか尋ねてください。

参照先

必要な情報	開くファイル
個別のプラットフォーム（ソーシャル、コマース、レビューと場所、アプリストア、検索／ニュース／金融、リサーチと開発、リンクインバイオ）	index.md に各プラットフォームのファイルとエンドポイント数がすべて記載されています。references/<platform>.md を開いてください
複数のプラットフォームをまたぐ 1 回の呼び出し：Prism 合成、search/multi、search/everywhere	prism.md、search.md
Webhook 配信を伴う定期的な再実行	monitors.md
「自分のアカウント一覧のうち、X について投稿したのはどれか」（リスニングではなく Cohorts）	cohorts.md
リクエスト 1 件またはページネーションを含む一連の取得全体のコスト	cost-gate.md、pricing.md
呼び出しの失敗	errors.md

この表だけを根拠に「サポートされていない」と回答しないでください。 この表はこのファイルと同じ時点の情報にすぎず、行が欠けている場合は、実際の未対応ではなく、古いコピーであることがはるかに多いです。プラットフォーム、エンドポイント、機能が存在しないとユーザーに伝える前に、無料のライブレジストリを確認してください。

curl -s -H "x-api-key: $SOCIALCRAWL_API_KEY" \
  "https://www.socialcrawl.dev/v1/utility/endpoints?search=douyin"

各行には path、method、credits_label、required_params、one_of、optional_params、paginated、cache_ttl_seconds が含まれており、このファイルを参照しなくても呼び出しを実行するのに十分な情報が得られます。検索結果の total: 0 の場合に限り、未対応と回答してください。

小売業者間での商品を比較する場合： Amazon、Walmart、Target、eBay、Home Depot は、標準の Product／Review／Seller スキーマを共有しているため、行を並べて比較できます。各小売業者固有の検索で商品 ID（ASIN、item id、TCIN など）を特定してから、各小売業者で商品詳細とレビューを取得してください。/v1/prism/product-reviews は Amazon、Google Shopping、Trustpilot のレビューのみを対象とする 1 つの合成呼び出しです。Walmart、Target、Home Depot については <retailer>/reviews を呼び出してください。

複数のプラットフォームを一度に処理する場合： /v1/search/multi は、複数のプラットフォーム固有の検索に対して 1 つのクエリを実行します（各プラットフォームのページ料金が適用され、結果の行を返したプラットフォームに対してのみ課金されます）。/v1/search/everywhere（20 クレジット）は、最大 17 のソースを対象に計画、順位付け、クラスタリングを行います。複数のプロフィールまたは投稿 URL については、POST /v1/prism/profiles／POST /v1/prism/post-stats、またはバックグラウンドジョブの POST /v1/prism/jobs を使用してください。

呼び出しの実行方法

ベース URL は https://www.socialcrawl.dev です。ほとんどのエンドポイントは GET とクエリパラメーターを使用します（値は URL エンコードしてください）。

curl -s -H "x-api-key: $SOCIALCRAWL_API_KEY" \
  "https://www.socialcrawl.dev/v1/{platform}/{resource}?{param}={value}"

メソッドを決めつけないでください。 各エンドポイントのセクションには、実際の HTTP メソッドと実行可能な curl が記載されています。バッチ読み取り、Prism ジョブ、ウェブジョブ、モニター、コホートでは、content-type: application/json を指定した POST、PATCH、PUT、DELETE を使用します（web/parse は multipart です）。ストリーミング（Accept: text/event-stream）や、先行する呼び出しで取得した ID が必要な 2 段階エンドポイントと併せた一覧は、api-overview.md を参照してください。レート制限は、キーごとに 1 分あたり 600 リクエスト、同時実行 50 件です。どちらの制限も超えると Retry-After とともに 429 が返され、課金されることはありません。一部のエンドポイントはタスクのポーリングが必要で、完了まで 10～45 秒かかります。タイムアウトは 60 秒に設定してください。

レスポンスの読み方

詳細は api-overview.md を参照してください。最初の呼び出しを行う前に、次の 5 つのルールを確認してください。

• 配置。 pagination（next_cursor、has_more、page_size）と任意の meta.hint はエンベロープのルートにあります。dropped、_warnings、各ページのレポート（labels、relevance、label_share、hydration、walk など）は data 内にあります。data._warnings を確認してください。無視されたパラメーター（count was ignored; use limit (page size)）や、別のアカウントに解決されたハンドル（resolved_to_different_handle）は、エラーではなくここに報告されます。
• ページ送り。 pagination.next_cursor を cursor として送り返し、短いページや total ではなく、has_more: false になったら終了してください。該当する結果がないリストは、クレジット消費なしで items: [] を含む 200 が返されます。
• デフォルトの判定は無料です。 コメント、投稿、レビュー、キーワード検索の各行にはラベル（computed.labels）が、検索結果の行には関連性スコア（computed.relevance）が追加料金なしで付与されます。judgments=off を指定すると、これらは除外されます。オプトインのプリセット（label=spam|toxic|low_quality|quality|injection|mention、relevant_to=）を指定すると、新たに判定された行 25 件ごとに 1 クレジットが追加されます。クエリに対する relevance=filter は無料です。
• 消費量の制御。 クリエイターの投稿一覧では、stop_at_id／since を指定すると、ポーリング時に新しいページだけが課金対象になります（pagination.stopped_at に停止理由が示されます）。キーワード検索では、min_views、max_age_days、country／exclude_country、sort_rows=views、seen=<id>（重複分は返金されます）、max_pages（1～5、ページごとに課金）を指定できます。
• meta.hint には、より少ない手順で同じ処理を行う別の呼び出しが 1 つ示されます。その呼び出しの費用が高い場合は、メッセージに料金が記載されます。ユーザーが許可した範囲内でのみ従ってください。

include= によるハイドレーションでは、行を関連するエンドポイントに結合します。ページ料金に加えて 行ごとに課金されるため、ハイドレーションを含む呼び出しを、見出しに記載された基本料金だけで案内しないでください。上限は cost-gate.md、注意点は api-overview.md を参照してください。

コストルール

キャッシュヒット、冪等性のあるリプレイ、すべての /v1/utility/* エンドポイント、/v1/credits/balance の利用は、クレジットを消費しません。失敗した呼び出しは返金されます。また、不正なパラメーター、最終ページを超えたページ、レート制限によって拒否されたリクエストでは、クレジットは差し引かれません。従量課金のエンドポイントでは、事前に上限分を確保し、実際に行われた処理に応じて返金されるため、レスポンスの credits_used が実際の請求額です。エンドポイントの基本料金や単価ではなく、リクエスト全体の正確な料金を見積もってください。呼び出しに応じて確認手順を調整します。

呼び出し	確認手順
定額が 5 クレジット以下で、ユーザーが希望している	1 行で表示します：≈ N credits
従量課金、複数ページ、バッチ、モニター／コホート、または 25 クレジット超	estimate.py / utility/estimate で事前に詳細を確認します
事前確保額（最大額）が 500 クレジット超、または予算（ユーザーが提示した予算）を超える	呼び出す前に確認します

これらのいずれにも該当しない場合、または料金やパラメーターが不明な場合は、無料の GET /v1/utility/estimate?id=<platform/resource>&<params> で事前に見積もってください。404 以外の応答が返った場合は、現在のサーバーを使用しています（5xx またはネットワーク障害は応答なしとして扱い、見積もりを再試行してください）。返された見積もりを使い、その後はどのエンドポイントでも dry_run=1 を無料で使用できます（検証のみを行い、データは取得しません）。404 または ENDPOINT_NOT_FOUND が返った場合は、古いサーバーを使用しています。この場合、dry_run=1 は送信しないでください（エンドポイントのドキュメントに明記されたドライランを除き、通常の呼び出しとして課金されます）。scripts/estimate.py（オフライン、assets/endpoints.json）または該当セクションの Pricing 行で見積もってください。どの場合も、処理後に credits_used を報告してください。

タスクリスト全体が必要な場合は、最初のページを取得する前に、全ページを取得する場合の料金を見積もってください。 最後までページを取得すると、ページ数に応じてページ単価が加算されます。見出しに表示されるのは 1 ページ分の料金だけです。instagram/followers と instagram/following の coverage=full は極端な例です。1 ページあたり 10 クレジットで、1 ページにつき約 50 アカウントが対象となるため、2,600 アカウントのリストでは合計約 520 クレジットです。合計額を提示し、開始前に同意を得てください（複数ページの取得）。

エラー：再試行する前に、references/errors.md を参照して分類してください。クレジットと残高：GET /v1/credits/balance（0 クレジット）。台帳：GET /v1/credits/transactions?limit=50（0 クレジット）。