> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.beatapi.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server. # ソーシャルデータ API > ソーシャルプラットフォームの公開データを取得する API の入力、レスポンス、課金、エラー処理について説明します。 # Social Data API BeatAPI Social Data は、対応するソーシャルプラットフォームの公開データを取得する、開発者向けの同期 API です。BeatAPI API キーと BeatAPI のアクション ID を使用し、アカウント、接続経路、元のレスポンスの詳細は API の内部で処理します。 ## クイックスタート [Social Data アクションカタログ](/social-data-catalog)から選び、ID とパラメーターを送信します。 ```bash curl https://api.beatapi.io/v1/social-data/call \ -H "Authorization: Bearer $BEATAPI_API_KEY" \ -H "Content-Type: application/json" \ -d '{"action":"douyin.web.fetch_one_video","params":{"aweme_id":"7364837462110"}}' ``` 公開エンドポイントは `POST /v1/social-data/call` です。操作はアクション ID で選ぶため、`model` は不要です。データ提供元固有の URL やルート名を送らないでください。 ## リクエスト | フィールド | 型 | 必須 | 説明 | | -------- | ------ | --: | ------------------------------- | | `action` | string | はい | カタログにある BeatAPI アクション ID | | `params` | object | いいえ | 選択したカタログ項目のパラメーター。パラメーターがなければ省略 | `action` は `douyin.web.fetch_one_video` など、カタログの識別子を使います。必須項目、型、許容値は `input_schema` を基準にしてください。カタログの method が `GET` の場合はパラメーター値がスカラー、`POST` の場合は `params` が JSON オブジェクトです。 本文の上限は 512 KiB です。認証は `Authorization: Bearer ` を使います。同じリクエストを再試行する可能性がある場合は `Idempotency-Key` を付けられます。同じキーを異なるリクエストに再利用すると拒否されます。 ## レスポンス 成功時には共通の BeatAPI 形式で返します。 ```json { "object": "social_data.call", "status": "succeeded", "request_id": "req_01H...", "action": "douyin.web.fetch_one_video", "data": { "aweme_id": "7364837462110" } } ``` `data` は選択したアクションの公開結果です。返却前に、データ提供元の名前、リクエスト ID、キャッシュ URL、ルーティングフィールド、生のエラー詳細を除去します。同期レスポンスのため、HTTP 成功はアクションの完了を意味します。 静的カタログは入力を説明するもので、アクション別の出力形式は公開していません。[Capabilities Inspect](/capabilities) で現在の `output_schema` と実行準備の状態を確認してください。`runnable` は実行可能でも出力形式が未公開という意味です。固定の構造を想定せず、実際のレスポンスから読み取ります。 ## クリエイターの発見 プラットフォームのカタログだけでは答えられない「似ているクリエイター」と「連絡方法」を、2 つのアクションで取得します。他のアクションと同じエンドポイント、`action` / `params` 形式を使います。 ### `creator.discover` 起点のアカウントを 1 つ指定すると、プラットフォームが類似すると判断したクリエイターを、プロフィールに公開された連絡情報とともに返します。 | パラメーター | 型 | 必須 | 説明 | | ---------- | ------- | --- | --------------------------------------------------------------------- | | `platform` | string | はい | `instagram`。読み取る関連アカウントのグラフは Instagram のもので、他プラットフォームにはこの起点からの類似検索はない | | `seed` | string | はい | ハンドルまたはプロフィール URL。例 `gymshark`、`https://www.instagram.com/gymshark/` | | `limit` | integer | いいえ | 類似クリエイターの件数。`1`–`6`、初期値 `6` | ```bash curl https://api.beatapi.io/v1/social-data/call \ -H "Authorization: Bearer $BEATAPI_API_KEY" \ -H "Content-Type: application/json" \ -d '{"action":"creator.discover","params":{"platform":"instagram","seed":"gymshark","limit":3}}' ``` 起点自身も `discovered_via: "input"` として返します。`limit` は類似クリエイターの件数なので、レスポンスはそれより 1 件多くなります。 ### `creator.contacts` 既知のクリエイターを指定すると、発見処理を行わず、それぞれの同じ形式の記録を返します。 | パラメーター | 型 | 必須 | 説明 | | ---------- | --------- | -- | ------------------------------ | | `platform` | string | はい | `instagram`、`tiktok`、`youtube` | | `handles` | string\[] | はい | ハンドルまたはプロフィール URL を 1–8 件 | ```bash curl https://api.beatapi.io/v1/social-data/call \ -H "Authorization: Bearer $BEATAPI_API_KEY" \ -H "Content-Type: application/json" \ -d '{"action":"creator.contacts","params":{"platform":"youtube","handles":["@mkbhd"]}}' ``` ### クリエイターの記録 両方のアクションは `data` に同じ形式を返します。クリエイターごとに 1 オブジェクトです。 | フィールド | 説明 | | ---------------------------------------------------------------------------------- | ------------------------------------------------ | | `platform`、`handle`、`name`、`profile_url`、`user_id` | 識別情報 | | `followers`、`following`、`posts_count`、`engagement_rate_pct`、`avg_likes` | オーディエンスと活動。推定値かどうかは `followers_estimated` が示す | | `email`、`extra_emails`、`email_status`、`email_source` | 連絡情報。未公開の場合 `email` は `null`。以下の注記を参照 | | `website`、`linkedin_url`、`instagram_url`、`tiktok_url`、`youtube_url`、`facebook_url` | プロフィールにあるリンク | | `bio`、`category`、`country`、`verified`、`is_business`、`is_private` | プロフィール属性 | | `lead_score`、`lead_grade`、`lead_tier` | 上の情報に基づく、優先度判断のための順位 | | `discovered_via` | 指定した本人は `input`、類似検索で発見した場合は `instagram_related` | > **Warning** > > `email_source` はメールアドレスの取得元を示します。プロフィールからリンクされた Web サイトのアドレスは、本人ではなく宣伝するブランドのものかもしれません。個人の連絡先として扱う前に `email_source` を確認してください。 ### クレジット この 2 つだけは、リクエスト単位ではなく**返されたクリエイター単位**で課金します。`GET /v1/social-data/pricing` の `billing_unit` は、この 2 つが `"creator"`、その他が `"request"` です。 誰も見つからなかった場合も、空の `data` 配列を持つ成功レスポンスとなり、クリエイター 1 件分のクレジットを消費します。結果の有無にかかわらず検索処理は行われたためです。`limit` と `handles` の件数でコストを制限してください。 ## エラーとクレジット 通常の BeatAPI エラー形式を使い、すべてのエラーに安定した `code` と `retryable` が付きます。再試行方針は[エラー](/errors)を参照してください。 | HTTP ステータス | コード | 意味 | | ---------: | ----------------------------------------------- | ----------------------------------- | | 400 | `bad_request` | JSON、アクション、パラメーターが不正。メッセージにフィールドを示す | | 401 | `missing_api_key` / `invalid_api_key` | キー未送信、または不正、期限切れ、無効、上限到達 | | 402 | `insufficient_credits` | 残高が 0、または呼び出し料金に不足 | | 403 | `forbidden` | キーまたはアカウントでは許可されていない | | 404 | `not_found` | 指定したアクションやリソースがない | | 409 | `idempotency_conflict` | 同じ冪等キーを異なるリクエストで使った | | 429 | `rate_limit_exceeded` | リクエスト数の上限到達。`Retry-After` 秒待つ | | 500 | `internal_error` | 予期しない内部エラー。再試行可能 | | 503 | `processing_unavailable` またはその他の `processing_*` | 完了できなかった。バックオフして再試行 | 失敗した呼び出しはクレジットを消費しません。成功時は、アカウントの現在の BeatAPI 料金と選択アクションに基づいて消費します。仕入れ料金やデータ提供元の URL は、この文書にも公開レスポンスにも含まれません。 ## MCP 同じカタログと仕様を、MCP ツール `capabilities_search`、`capabilities_inspect`、`capabilities_run` と [Capabilities API](/capabilities) でも利用できます。利用者の言葉でプラットフォームと操作（`小红书 搜索笔记`、`tiktok user profile`）を検索します。プラットフォーム名だけなら機能別の概要を返します。Search が返した `data:` の reference をそのまま使い、各応答の `next` に従ってください。 MCP は大きな結果を初期設定ではプレビューで返します。1 時間以内なら、同じ API キーと元の `reference` を使い、`operation: "result"` と返された `request_id` を指定して、全結果を無料で取得できます。データ提供元の認証情報や固有のパスは不要です。