ソーシャルデータ API | BeatAPI API Documentation

BeatAPI Social Data は、対応するソーシャルプラットフォームの公開データを取得する、開発者向けの同期 API です。BeatAPI API キーと BeatAPI のアクション ID を使用し、アカウント、接続経路、元のレスポンスの詳細は API の内部で処理します。

クイックスタート

Social Data アクションカタログから選び、ID とパラメーターを送信します。

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 <BeatAPI API key> を使います。同じリクエストを再試行する可能性がある場合は Idempotency-Key を付けられます。同じキーを異なるリクエストに再利用すると拒否されます。

レスポンス

成功時には共通の BeatAPI 形式で返します。

{
  "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 で現在の 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`

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 件

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`

email_source はメールアドレスの取得元を示します。プロフィールからリンクされた Web サイトのアドレスは、本人ではなく宣伝するブランドのものかもしれません。個人の連絡先として扱う前に email_source を確認してください。

クレジット

この 2 つだけは、リクエスト単位ではなく返されたクリエイター単位で課金します。GET /v1/social-data/pricing の billing_unit は、この 2 つが "creator"、その他が "request" です。

誰も見つからなかった場合も、空の data 配列を持つ成功レスポンスとなり、クリエイター 1 件分のクレジットを消費します。結果の有無にかかわらず検索処理は行われたためです。limit と handles の件数でコストを制限してください。

エラーとクレジット

通常の BeatAPI エラー形式を使い、すべてのエラーに安定した code と retryable が付きます。再試行方針はエラーを参照してください。

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 でも利用できます。利用者の言葉でプラットフォームと操作（小红书搜索笔记、tiktok user profile）を検索します。プラットフォーム名だけなら機能別の概要を返します。Search が返した data:<action-id> の reference をそのまま使い、各応答の next に従ってください。

MCP は大きな結果を初期設定ではプレビューで返します。1 時間以内なら、同じ API キーと元の reference を使い、operation: "result" と返された request_id を指定して、全結果を無料で取得できます。データ提供元の認証情報や固有のパスは不要です。

Social Data API