TikTokフォロワー取得API

1回のPOSTで公開TikTokアカウントのフォロワーをリスト表示——最大50件のフォロワープロフィールを完全なメタデータ付きで返します。

1回のPOSTで最大50件
完全なフォロワーメタデータ
柔軟なユーザー名入力
サンプルサイズの制御
冪等キー対応
サーバーサイドでキー保持

リクエスト例

curl -X POST "https://api.agentbody.io/v1/tiktok/profile/followers" \
  -H "Authorization: Bearer <YOUR_AGENTBODY_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"max_results":"1","username":"YOUR_USERNAME"}'

レスポンス例

OpenAPI 仕様に記載されたレスポンス。

Sample of public follower profiles for the TikTok account.

{
  "items": [
    {
      "avatar_url": "https://example.com/avatar.jpg",
      "bio": "example bio",
      "display_name": "Example User",
      "followers": 1200,
      "following": 300,
      "likes": 45000,
      "profile_url": "https://www.tiktok.com/@example",
      "username": "example",
      "verified": false
    }
  ],
  "total": 1,
  "username": "khaby.lame"
}

機能特徴

tiktok.profile_followersオペレーションは、1つのTikTokプロフィールの公開フォロワーアカウントのサンプルをリスト表示します。APIキーはサーバー側で保持。エンドポイントは1回の呼び出しで最大50件の公開メタデータ付きフォロワープロフィールを返します。

1回のPOSTで最大50件

/v1/tiktok/profile/followers にTikTokユーザー名・@ハンドル・プロフィールURLをPOST。成功時の200は username・total・items を返します。itemsには最大50件のフォロワープロフィールが、各9つのメタデータフィールド付きで入ります。

完全なフォロワーメタデータ

レスポンスの各itemは username・display_name・bio・profile_url・avatar_url・followers・following・likes・verified を含みます——各フォロワーアカウントの完全な公開プロフィールカードです。

柔軟なユーザー名入力

usernameパラメータは、裸のユーザー名・@ハンドル・完全なプロフィールURL（tiktok.com/@username）を受け付けます。APIは3つの形式を同じ公開プロフィールに正規化。非公開・存在しないアカウントは400または502を返します。

サンプルサイズの制御

オプションのmax_resultsパラメータで返すフォロワープロフィール数を1〜50で設定。返されるリストはフォロワー集合のサンプルであり、完全なフォロワーリストではありません。

冪等キー対応

Idempotency-Keyヘッダーを付ければ、失敗したリクエストを二重課金なしで安全にリトライできます。ゲートウェイがキーで重複排除するため、ネットワークリトライが同じプロフィールの二度目の検索を起こしません。

サーバーサイドでキー保持

エンドポイントにはサーバー側で保持するAgentBody APIキーが必要です。クライアント側コードにキーを含めないでください。すべての呼び出しはバックエンド経由で、キーの安全と利用量の追跡を確保します。

使い方

3ステップでTikTokフォロワー検索をシステムに組み込めます。

APIキーを取得

無料のAgentBodyアカウントを作成し、ダッシュボードでAPIキーを生成。キーは全リクエストの認証と残高への利用量計上に使われます。

ユーザー名をPOST

/v1/tiktok/profile/followers にTikTokユーザー名・@ハンドル・プロフィールURLをリクエストボディに入れてPOST。オプションでmax_results（1〜50）を設定し、安全なリトライのためIdempotency-Keyヘッダーを付けます。

フォロワーリストを受信

成功時の200はアカウントのユーザー名・件数・フォロワープロフィール配列を返します。itemsを反復して各フォロワーのユーザー名・表示名・プロフィール文・カウント・認証フラグを処理。

よくある質問

TikTokフォロワー取得APIの仕組みは？

/v1/tiktok/profile/followers にTikTokユーザー名・@ハンドル・プロフィールURLをPOSTします。APIがアカウントの公開フォロワープロフィールのサンプルを取得し、完全なメタデータ付きで最大50件を返します。

どのユーザー名形式に対応していますか？

usernameパラメータは、裸のユーザー名・@ハンドル・完全なプロフィールURL（tiktok.com/@username）を受け付けます。3つの形式はすべて同じ公開プロフィールに解決。非公開・削除済み・存在しないアカウントは400または502を返します。

返されるフォロワーリストは完全ですか？

いいえ。エンドポイントはフォロワー集合のサンプルを返し、max_resultsで1回の呼び出しあたり最大50件に制限されます。オーディエンス監査と調査サンプル向けの設計で、フォロワーの完全な列挙ではありません。

フォロワーごとにどのメタデータが返りますか？

各itemには username・display_name・bio・profile_url・avatar_url・followers・following・likes・verified が含まれます——TikTokが公開するアカウントの完全なメタデータです。

どんなエラーコードが返りますか？

400は不正・非対応のユーザー名、401はAPIキー欠落・無効、409は冪等性の競合、502/503/504は上流障害です。失敗は課金されません。上流エラーは同じ冪等キーでリトライしてください。

APIは非公開アカウントに対応していますか？

いいえ。非公開TikTokアカウントのフォロワーリストは承認されたフォロワーのみに制限されており、APIはそれらにエラーを返します。公開アカウントのみ対応です。非公開アカウントのフォロワーアクセスを謳うサービスは信用しないでください。