Getting Started

This guide will show you how to use the Research API. Learn how to use the Research API to query video data and fetch public TikTok account data in the following use case example.

View your client registration

Once your application is approved, a research client will be generated for your project. You can view your approved research projects here. Select a project from the list to see the research client details.

The provided Client key and Client secret are required to connect to the Research API endpoints. The client key and secret are hidden by default but can be displayed by clicking the Display button (eye icon).

Obtain a client access token

Once you have obtained the client key and secret for your project, generate a client access token. Add this access token in the authorization header of the http requests to connect to the Research API endpoints.

Query TikTok public content data

The cURL command below shows an example of how you can query the TikTok ID and like count of videos created in the US or Canada with the keyword hello world in the video description.

 
curl -X POST \
  'https://open.tiktokapis.com/v2/research/video/query/?fields=id,like_count' \
  -H 'authorization: bearer clt.example12345Example12345Example' \
  -d '{ 
          "query": {
              "and": [
                   { "operation": "IN", "field_name": "region_code", "field_values": ["US", "CA"] },
                   { "operation": "EQ", "field_name": "keyword", "field_values": ["hello world"] }
               ]
          }, 
          "start_date": "20220615",
          "end_date": "20220628",
          "max_count": 10
}'

Query condition

Similar to the WHERE clause in SQL, a condition can be used to filter data returned in a query operation. The above request is equivalent to the following SQL query:

 SELECT id,like_count FROM video_table WHERE region_code IN ["US", "CA"] AND create_date > 20220615

Note: approximate string matching (or fuzzy string searching) is used to match conditions.

field_name

The following are the field_name values:

• keyword
• create_date
• username
• region_code
• video_id
• hashtag_name
• music_id
• effect_id
• video_length

operation

The following are the operation values:

IN: Tests if an expression matches any value in a list of values.EQ: Tests if an expression matches the specified value.GT: Tests if an expression is strictly greater than the specified value.GTE: Tests if an expression is greater than or equal to the specified value.LT: Tests if an expression is strictly less than the specified value.LTE: Tests if an expression is less than or equal to the specified value.

AND, OR or NOT

Conditions are grouped by the following boolean operators:

AND: Displays a record if all the conditions separated by AND are TRUE.OR: Displays a record if any of the conditions separated by OR is TRUE.NOT: Displays a record if all the conditions separated by NOT are FALSE.

Pagination

If the total number of videos that match the query criteria is larger than the max number of videos that can be returned in a single request, the response data will be returned with different requests.

First page

When you send the first request, you do not need to set the search_id or cursor in the request body. In the http response, cursor and search_id are returned, which are used in the subsequent requests.

Try out this request:

curl -X POST \
  'https://open.tiktokapis.com/v2/research/video/query/?fields=id,like_count' \
  -H 'authorization: bearer clt.example12345Example12345Example' \
  -d '{ 
          "query": {
              "and": [
                   { "operation": "IN", "field_name": "region_code", "field_values": ["US", "IN"] },
                   { "operation": "GT", "field_name": "hashtag_name", "field_values": ["hello"] }
               ]
          }, 
          "start_date": "20220615",
          "end_date": "20220628",
          "max_count": 10
}'

The following example data is returned from the response.

{
    "data": {
        "cursor": 10,
        "has_more": true,
        "search_id": "7160776277492814854",
        "videos": [
            ...
        ]
    },
    "error": {
        ...
    }
 }

Next page

With the cURL command below, you can get the next page of query results.

curl -X POST \
  'https://open.tiktokapis.com/v2/research/video/query/?fields=id,like_count' \
  -H 'authorization: bearer clt.example12345Example12345Example' \
  -d '{ 
          "query": {
              "and": [
                   { "operation": "IN", "field_name": "region_code", "field_values": ["US", "IN"] },
                   { "operation": "GT", "field_name": "hashtag_name", "field_values": ["hello"] }
               ]
          }, 
          "max_count": 10,
          "cursor": 10,
          "start_date": "20220615",
          "end_date": "20220628",
          "search_id": "7160776277492814854",
}'

The following example data is returned from the response.

{
    "data": {
        "cursor": 20,
        "has_more": true,
        "search_id": "7160776277492814854",
        "videos": [
            ...
        ]
    },
    "error": {
        ...
    } 
}

Query TikTok public account information

With the cURL command below, you can query public TikTok account information by a TikTok handle.

curl --location --request POST 'https://open.tiktokapis.com/v2/research/user/info/?fields=display_name,bio_description,avatar_url,is_verified,follower_count,following_count,likes_count,video_count' \
--header 'Authorization: bearer {{access_token}}' \
--header 'Content-Type: text/plain' \
--data-raw '{
    "username": "joe1234567"
}'

The following example data is returned from the response.

{
    "data": {
        "username": "joe1234567",
        "video_count": 64,
        "avatar_url": "https://my-awesome-avatar",
        "display_name": "joe 1234567",
        "follower_count": 111,
        "likes_count": 4146,
        "bio_description": "joe joe",
        "following_count": 103,
        "is_verified": false
    },
    "error": {
        ...
    }
}