TikTok for Developers

Docs

Query User Followers

Request

HTTP URL

https://open.tiktokapis.com/v2/research/user/followers/

HTTP Method

POST

Scopes

research.data.basic (required)

Headers

Key

Type

Description

Example

Required

Authorization

string

The client access token obtained from /v2/oauth/token/.


Bearer clt.example12345Example12345Example

Yes

Content-Type

string

The original media type of the resource

application/json

Yes

Body

Key

Type

Description

Example Value

Required

username

string

The username as the unique identifier

"test_username"

Yes

max_count


int64

The maximum number of followers that can be returned in this response. Default is 20; max is 100.

100

No

cursor

int64

Followers followed on or before this time will be returned. It is a Unix timestamp in UTC seconds. Default value is set as the time this request was made.

1706833705


No

Example

curl --location 'https://platform.tiktokapis.com/v2/research/user/followers/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer clt.test123test123test123' \
--data '{
    "username": "test_user",
    "max_count":3,
    "cursor": 12347764
}'

Response

Body

Key

Type

Description

data

UserFollowerData

The list of the followers of the user

error

ErrorStructV2

Error object

UserFollowerData

Key

Type

Description

user_followers

list<UserInfo>

A list of user info objects that match the query


cursor

int64

Followers that followed this user on or before this time will be returned. It is a Unix timestamp in UTC seconds. Default value is set as the time this request was made.

has_more

bool

Whether this user has more followers or not

User Info Object

Field Name

Type

Description

"display_name"

string

The profile name of the follower of this user

"username"

string

The username of the follower of this user

Example

{
    "data": {
        "cursor": 1706837834,
        "has_more": true,
        "user_followers": [
            {
                "display_name": "test user",
                "username": "test_username"
            },
            {
                "username": "test user 2",
                "display_name": "test_username2"
            }
        ]
    },
    "error": {
        "code": "ok",
        "message": "ok",
        "log_id": "123499999999999999999999999999"
    }
}