TikTok follower viewer API
List a public TikTok account's followers with one POST. The response returns up to 50 follower profiles with full metadata.
- One POST, Up To 50 Profiles
- Full Follower Metadata
- Flexible Username Input
- Sample Size Control
- Idempotency Key Support
- Server-Side Key Required
Request examples
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"}'Response examples
Documented responses from the OpenAPI specification.
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"
}Features
The tiktok.profile_followers operation lists a sample of public follower accounts for one TikTok profile. Your server holds the API key; the endpoint returns up to 50 follower profiles with public metadata in a single call.
One POST, Up To 50 Profiles
Send POST /v1/tiktok/profile/followers with a TikTok username, @handle, or profile URL. A successful 200 returns username, total, and items — up to 50 follower profiles with nine metadata fields each.
Full Follower Metadata
Every item in the response carries username, display_name, bio, profile_url, avatar_url, followers, following, likes, and verified — the complete public profile card for each follower account.
Flexible Username Input
The username parameter accepts a bare username, an @handle, or a full profile URL (tiktok.com/@username). The API normalizes all three formats to the same public profile; private or nonexistent accounts return a 400 or 502 error.
Sample Size Control
The optional max_results parameter sets how many follower profiles to return, from 1 up to 50. The returned list is a sample of the follower set, not the complete follower list.
Idempotency Key Support
Pass an Idempotency-Key header to safely retry failed requests without duplicate charges. The gateway deduplicates by key, so a network retry never triggers a second lookup for the same profile.
Server-Side Key Required
The endpoint requires an AgentBody API key held on your server. Never expose the key in client-side code; route all calls through your backend to keep the key secure and your usage tracked.
How to use
Integrate TikTok follower lookups in three steps with the API.
Get Your API Key
Create a free AgentBody account and generate an API key from the dashboard. The key authenticates every request and tracks usage against your balance.
POST The Username
Send a POST request to /v1/tiktok/profile/followers with the TikTok username, @handle, or profile URL in the request body. Optionally set max_results (1-50) and include an Idempotency-Key header for safe retries.
Receive The Follower List
A successful 200 response returns the account username, the item count, and the follower profiles array. Iterate items to process each follower's username, display name, bio, counts, and verified flag.
Frequently asked questions
How does the TikTok follower viewer API work?
Send a POST request to /v1/tiktok/profile/followers with a TikTok username, @handle, or profile URL. The API fetches a sample of the account's public follower profiles and returns up to 50 of them with full metadata.
What username formats are supported?
The username parameter accepts a bare username, an @handle, or a full profile URL (tiktok.com/@username). All three formats resolve to the same public profile. Private, deleted, or nonexistent accounts return a 400 or 502 error.
Is the returned follower list complete?
No. The endpoint returns a sample of the follower set, capped at 50 profiles per call via max_results. It is designed for audience audits and research samples, not exhaustive follower enumeration.
What metadata is returned per follower?
Each item includes username, display_name, bio, profile_url, avatar_url, followers, following, likes, and verified — the full public profile metadata TikTok exposes for an account.
What error codes does the endpoint return?
400 for a malformed or unsupported username, 401 for a missing or invalid API key, 409 for idempotency conflicts, and 502/503/504 for upstream failures. Failures are not billed; retry upstream errors with the same idempotency key.
Does the API support private accounts?
No. Private TikTok accounts restrict their follower list to approved followers, and the API returns an error for them. Only public accounts are supported — any service claiming private-account follower access should not be trusted.