TikTok user search API
TikTok user search: GET /v1/tiktok/search/users. 1 credit per request.
GET /v1/tiktok/search/users
GET /v1/tiktok/search/users
TikTok user search.
- Cost: 1 credit
- Cache: Results are kept up to 30 days; send
max_age_daysto reuse them for free. - Timeout: A request still running after about 25 seconds answers
202with a job to poll (Batch and jobs).
Parameters#
| Name | Type | Required | Description |
|---|---|---|---|
query | string | yes | Search terms. Also accepted as keyword, q. |
Every request also accepts:
cursor: the cursor from the previous page (Pagination).trim:truefor a smaller response withoutnullfields andextra.raw:trueto also get the platform's original object asraw.max_age_days: accept a cached result up to this many days old, for 0 credits (Caching).
Example request#
Set your key in the environment first (see Authentication).
1curl -G "https://api.socialscrape.dev/v1/tiktok/search/users" \2 -H "x-api-key: $SOCIALSCRAPE_API_KEY" \3 --data-urlencode "query=nasa"1import os2import requests34params = {5 "query": "nasa",6}7res = requests.get(8 "https://api.socialscrape.dev/v1/tiktok/search/users",9 headers={"x-api-key": os.environ["SOCIALSCRAPE_API_KEY"]},10 params=params,11)12body = res.json()1314if body["ok"]:15 print(body["data"])16else:17 print(body["error"]["code"], body["error"]["message"])1const url = new URL("https://api.socialscrape.dev/v1/tiktok/search/users");2url.search = new URLSearchParams({3 "query": "nasa"4}).toString();5const res = await fetch(url, {6 headers: { "x-api-key": process.env.SOCIALSCRAPE_API_KEY! },7});8const body = await res.json();910if (body.ok) {11 console.log(body.data);12} else {13 console.error(body.error.code, body.error.message);14}1{2 "nodes": [3 {4 "name": "SocialScrape TikTok user search",5 "type": "n8n-nodes-base.httpRequest",6 "typeVersion": 4.2,7 "position": [8 0,9 010 ],11 "parameters": {12 "method": "GET",13 "url": "https://api.socialscrape.dev/v1/tiktok/search/users",14 "sendQuery": true,15 "queryParameters": {16 "parameters": [17 {18 "name": "query",19 "value": "nasa"20 }21 ]22 },23 "sendHeaders": true,24 "headerParameters": {25 "parameters": [26 {27 "name": "x-api-key",28 "value": "={{ $env.SOCIALSCRAPE_API_KEY }}"29 }30 ]31 }32 }33 }34 ],35 "connections": {}36}Example response#
This is a sample from a recorded response, lists and long text are shortened. Status 200.
200 OKSample response
1{2 "ok": true,3 "credits_charged": 1,4 "credits_remaining": 4999,5 "cached": false,6 "cached_at": null,7 "request_id": "req_c83ed80b25d3cb6833c4958f",8 "data": {9 "object": "list",10 "items": [11 {12 "object": "profile",13 "platform": "tiktok",14 "id": "7664638705177150477",15 "handle": "nasa",16 "name": "NASA",17 "headline": null,18 "url": "https://www.tiktok.com/@nasa",19 "kind": "creator",20 "bio": "Making the seemingly impossible, possible.✨",21 "avatar_url": "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/e5143212a59c09a008bf50f487d54d1f~tplv-tiktokx-cropcenter:100:100.webp?biz_tag=tiktok_user.user_cover&dr=9640&idc=useast5&ps=13740610&refresh_token=9a678828&shcp=c1333099&shp=3...",22 "banner_url": null,23 "verified": true,24 "is_private": null,25 "external_url": null,26 "links": null,27 "location": null,28 "category": null,29 "created_at": null,30 "stats": {31 "followers": 2100000,32 "following": null,33 "posts": null,34 "likes": 11436616,35 "views": null36 },37 "extra": {38 "sec_uid": "MS4wLjABAAAAU9BRVzC8oCaegVnia8IbqWhPb_-dbU7s00Y3wS1_Nx8g5RUaYvyXrpejgjdxTwd6",39 "verification_reason": "institution account"40 }41 },42 {43 "object": "profile",44 "platform": "tiktok",45 "id": "7064838657300251654",46 "handle": "𝑛𝑎𝑠𝑎",47 "name": "NASA_Editor",48 "headline": null,49 "url": "https://www.tiktok.com/@𝑛𝑎𝑠𝑎",50 "kind": "creator",51 "bio": "I'm Editor space 🚀😀",52 "avatar_url": "https://p19-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/8854cd9becb41a377a03e7a61f908fd8~tplv-tiktokx-cropcenter:100:100.webp?biz_tag=tiktok_user.user_cover&dr=9640&idc=useast5&ps=13740610&refresh_token=69b8a325&shcp=c1333099&shp=30310...",53 "banner_url": null,54 "verified": null,55 "is_private": null,56 "external_url": null,57 "links": null,58 "location": null,59 "category": null,60 "created_at": null,61 "stats": {62 "followers": 55,63 "following": null,64 "posts": null,65 "likes": 0,66 "views": null67 },68 "extra": {69 "sec_uid": "MS4wLjABAAAAqGlRomrFFt4-_sBFjST6nDj6DP0bbhyoiS8y2cBQczhJutoWloS-FMKKv_F9hA8F"70 }71 }72 ],73 "cursor": "c10",74 "has_more": true,75 "parent": null76 },77 "cursor": "c10",78 "has_more": true79}Response#
A list of Profile objects in data.items, with data.cursor and data.has_more.
See Data models for every field. The envelope around data is described in Responses.
Errors#
Failures are free: credits_charged is 0. Branch on error.code, never on the message.
| Code | HTTP | Retry | Meaning |
|---|---|---|---|
invalid_params | 400 | no | A parameter is missing, unknown or has the wrong type. |
not_found | 404 | no | The platform says this profile, post or item does not exist. |
Every request can also fail with the account and platform errors listed on the Errors page.
Related endpoints#
- TikTok profile (
GET /v1/tiktok/profile) - TikTok profile videos (
GET /v1/tiktok/profile/videos) - TikTok collection videos (
GET /v1/tiktok/collection/videos) - TikTok video details (
GET /v1/tiktok/video) - TikTok video transcript (
GET /v1/tiktok/video/transcript) - TikTok video comments (
GET /v1/tiktok/video/comments) - TikTok comment replies (
GET /v1/tiktok/video/comment/replies) - TikTok search suggestions (
GET /v1/tiktok/search/suggestions)