Skip to main content
POST
List TikTok followers

Description

This endpoint allows you to fetch a paginated list of followers for a specific TikTok account. Each entry includes user profile information and statistics.

Endpoint

POST /api/v1/get-tiktok-user-followers

Request Headers

Request Body

The handle is the TikTok username (e.g., stoolpresidente). You can find it in the profile URL: https://www.tiktok.com/@{handle}.

Responses

Success (200 OK)

Returns a JSON object containing an array of the account’s followers with pagination information.
Response Headers:
  • Content-Type: application/json
  • X-RateLimit-Limit: The rate limit for the user.
  • X-RateLimit-Remaining: The remaining number of requests for the user.

Error Responses

400 Bad Request

Indicates an issue with the request parameters.
Possible error messages:
  • Invalid JSON in request body
  • 'handle' parameter is required and must be a non-empty string.
  • The followers service could not process the handle.
  • The followers service reported an issue.

401 Unauthorized

API key is missing, invalid, or inactive.

403 Forbidden

API key does not have enough credits.

404 Not Found

The followers list could not be found.

500 Internal Server Error

An unexpected error occurred on the server.
Possible error messages:
  • Service not configured. Please contact support.
  • Service authentication failed. Please contact support.
  • An unexpected server error occurred...

502 Bad Gateway

Indicates an issue with an upstream service.
Possible error messages:
  • The followers service is currently unavailable.
  • Received invalid data structure from followers service.
  • Error fetching followers data from the upstream service.

503 Service Unavailable

Rate limit exceeded with an upstream service.

Example Request

cURL

Node.js (fetch)

Notes

  • Use the minTime field from the response to paginate through all followers.
  • The hasMore field indicates whether there are additional pages available.
  • The total field provides the approximate total count of followers.
  • Each follower entry includes both profile information and statistics.
  • This endpoint is useful for influencer analytics, audience analysis, and growth tracking.

Credit Cost

This endpoint costs 10 credits per successful request. For more details, see our Credit Costs page.

Rate Limiting

This endpoint is subject to standard API rate limits. Check the X-RateLimit-Limit and X-RateLimit-Remaining headers in the response to monitor your usage.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
handle
string
required
minTime
number

Cursor for pagination.

count
number
requestSource
enum<string>

Optional identifier describing where the API request originated.

Available options:
API,
WEB,
MAKE_DOT_COM,
ZAPIER,
N8N,
PLAYGROUND,
DEFAULT_AUTOMATION,
AGENT_PREVIEW,
AGENT_LIVE,
AUTOPILOT,
STUDIO

Response

Followers retrieved.

followers
object[]
maxCursor
number | null
minCursor
number | null
hasMore
boolean | null
total
integer | null