> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scraperize.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Search users
> Searches TikTok accounts matching a `query`, 10 per page in TikTok’s own ranking (it matches loosely — usernames, nicknames and bios — so a query rarely returns nothing). Each account comes with its user id and secUid, username, nickname, bio, profile link, avatar, verification badge and label, follower count, total likes, and its LIVE room id when it is live. Pass the returned `cursor` (with the same query) to get the next page; it is null on the last page. Results can shift slightly between identical searches. Search results round large follower counts and don’t always carry the verification badge — for exact stats, an authoritative `verified` flag and the full profile use `/v1/tiktok/profile`.
**Cost: 1 credit** per successful request. Errors and cache hits (`cache_max_age`) are free.
Paste this into ChatGPT, Claude or your coding assistant to generate working code for this endpoint (use the copy button).
```text Prompt
I want to make an API call to /v1/tiktok/search/users. Here are the details:
Endpoint: GET https://api.scraperize.com/v1/tiktok/search/users
Description: Searches TikTok accounts matching a `query`, 10 per page in TikTok’s own ranking (it matches loosely — usernames, nicknames and bios — so a query rarely returns nothing). Each account comes with its user id and secUid, username, nickname, bio, profile link, avatar, verification badge and label, follower count, total likes, and its LIVE room id when it is live. Pass the returned `cursor` (with the same query) to get the next page; it is null on the last page. Results can shift slightly between identical searches. Search results round large follower counts and don’t always carry the verification badge — for exact stats, an authoritative `verified` flag and the full profile use `/v1/tiktok/profile`.
Required Headers:
- x-api-key: Your API key
Parameters:
- query (string) [required]: The search text, e.g. a name or username (1–100 characters).
- cursor (string): The `cursor` from the previous response (same query), to get the next page. Omit for the first page.
- cache_max_age (select): Optional. Return a cached result if one this age or newer exists — served for **0 credits** with `meta.cached=true` and `meta.cachedAt`. Otherwise a fresh scrape runs (**1 credit**) and refreshes the cache. Omit to always scrape fresh.
Example Response:
{
"data": {
"query": "paul",
"correctedQuery": null,
"users": [
{
"id": "7673203716040442900",
"secUid": "MS4wLjABAAAANF3gh472UnRU4aAOCACvxj8PU1tHHL0FxG12kre-98mqiaB9ZbZmCG0sEMTr-8OX",
"handle": "paul430830",
"nickname": "Paul",
"bio": null,
"url": "https://www.tiktok.com/@paul430830",
"avatarUrl": "https://p16-common-sign.tiktokcdn.com/tos-alisg-avt-0068/9680d75d3265b4ad61928d456600ab5c~tplv-tiktokx-cropcenter:100:100.webp?biz_tag=tiktok_user.user_cover&dr…",
"avatar": {
"uri": "tos-alisg-avt-0068/9680d75d3265b4ad61928d456600ab5c",
"urls": [
"https://p16-common-sign.tiktokcdn.com/tos-alisg-avt-0068/9680d75d3265b4ad61928d456600ab5c~tplv-tiktokx-cropcenter:100:100.webp?biz_tag=tiktok_user.user_cover&dr…"
],
"width": 720,
"height": 720
},
"verified": false,
"verificationLabel": null,
"enterpriseVerifyReason": null,
"followerCount": 2822,
"likeCount": 1432,
"liveRoomId": null,
"isLive": false
}
],
"count": 10,
"cursor": "10_20261005224524E46DA90E886C6A7D7452",
"hasMore": true,
"fetchedAt": "2026-10-05T14:45:25.529Z"
},
"meta": {
"requestId": "req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f",
"creditsCharged": 1,
"creditsRemaining": 4999,
"cached": false
}
}
Please help me write code in my preferred programming language to make this API call and handle the response appropriately. Include error handling and best practices.
```
## OpenAPI
````yaml /api-reference/openapi.json get /v1/tiktok/search/users
openapi: 3.0.3
info:
title: Scraperize API
version: 1.0.0
description: >-
Extract public data from social media platforms as clean JSON. Endpoints are
split by platform and by what they return, e.g. `GET /v1/twitter/tweet`.
## Authentication
Send your API key in the `x-api-key` header (or `Authorization: Bearer
`). Create keys in your dashboard.
## Credits
Each successful live scrape costs **1 credit**. Credits are prepaid and
never expire.
## Caching
Every endpoint accepts an optional `cache_max_age`
(`1d`|`3d`|`7d`|`14d`|`30d`). A cache hit within that window is returned for
**0 credits**.
## Responses
Success returns `{ "data": …, "meta": { "requestId", … } }`. Errors return
`{ "error": { "code", "message", "requestId" } }` with a matching HTTP
status. `meta` on a scrape carries `creditsCharged`, `creditsRemaining`,
`cached`, and (on a hit) `cachedAt`.
## Rate limits
Requests are limited per team per minute; over the limit returns `429` with
a `Retry-After` header.
servers:
- url: https://api.scraperize.com
description: Production
security:
- ApiKeyAuth: []
tags:
- name: Twitter
description: Twitter / X scraping endpoints
- name: Facebook
description: Facebook scraping endpoints
- name: Linkme
description: Linkme (link.me) scraping endpoints
- name: Amazon
description: Amazon (creator shop / storefront) scraping endpoints
- name: Linkbio
description: Linkbio (lnk.bio) scraping endpoints
- name: Pillar
description: Pillar (pillar.io) scraping endpoints
- name: Komi
description: Komi (komi.io) scraping endpoints
- name: Linktree
description: Linktree (linktr.ee) scraping endpoints
- name: Kick
description: Kick (kick.com) scraping endpoints
- name: Snapchat
description: Snapchat (snapchat.com) scraping endpoints
- name: Telegram
description: Telegram (t.me) scraping endpoints
- name: LinkedIn
description: LinkedIn scraping endpoints
- name: Twitch
description: Twitch scraping endpoints
- name: TikTok
description: TikTok (tiktok.com) scraping endpoints
paths:
/v1/tiktok/search/users:
get:
tags:
- TikTok
summary: Search users
description: >-
Searches TikTok accounts matching a `query`, 10 per page in TikTok’s own
ranking (it matches loosely — usernames, nicknames and bios — so a query
rarely returns nothing). Each account comes with its user id and secUid,
username, nickname, bio, profile link, avatar, verification badge and
label, follower count, total likes, and its LIVE room id when it is
live. Pass the returned `cursor` (with the same query) to get the next
page; it is null on the last page. Results can shift slightly between
identical searches. Search results round large follower counts and don’t
always carry the verification badge — for exact stats, an authoritative
`verified` flag and the full profile use `/v1/tiktok/profile`.
parameters:
- name: query
in: query
required: true
description: The search text, e.g. a name or username (1–100 characters).
schema:
type: string
minLength: 1
maxLength: 100
example: paul
- name: cursor
in: query
required: false
description: >-
The `cursor` from the previous response (same query), to get the
next page. Omit for the first page.
schema:
type: string
example: 10_2026100219392944173A9283D8D5591CC1
- name: cache_max_age
in: query
required: false
description: >-
Optional. Return a cached result if one this age or newer exists —
served for **0 credits** with `meta.cached=true` and
`meta.cachedAt`. Otherwise a fresh scrape runs (**1 credit**) and
refreshes the cache. Omit to always scrape fresh.
schema:
type: string
enum:
- 1d
- 3d
- 7d
- 14d
- 30d
example: 7d
responses:
'200':
description: One page of matching accounts.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
query:
type: string
correctedQuery:
type: string
nullable: true
users:
type: array
items:
type: object
count:
type: integer
cursor:
type: string
nullable: true
hasMore:
type: boolean
fetchedAt:
type: string
format: date-time
meta:
type: object
description: >-
requestId + credit/caching metadata (creditsCharged,
creditsRemaining, cached, cachedAt).
required:
- data
- meta
example:
data:
query: paul
correctedQuery: null
users:
- id: '7673203716040442900'
secUid: >-
MS4wLjABAAAANF3gh472UnRU4aAOCACvxj8PU1tHHL0FxG12kre-98mqiaB9ZbZmCG0sEMTr-8OX
handle: paul430830
nickname: Paul
bio: null
url: https://www.tiktok.com/@paul430830
avatarUrl: >-
https://p16-common-sign.tiktokcdn.com/tos-alisg-avt-0068/9680d75d3265b4ad61928d456600ab5c~tplv-tiktokx-cropcenter:100:100.webp?biz_tag=tiktok_user.user_cover&dr=14579&idc=my2&ps=13740610&refresh_token=4358a587&shcp=c1333099&shp=30310797&t=4d5b0474&x-expires=1791295200&x-signature=81niXSrfEjwb6lt1qecTrWo3WZA%3D
avatar:
uri: tos-alisg-avt-0068/9680d75d3265b4ad61928d456600ab5c
urls:
- >-
https://p16-common-sign.tiktokcdn.com/tos-alisg-avt-0068/9680d75d3265b4ad61928d456600ab5c~tplv-tiktokx-cropcenter:100:100.webp?biz_tag=tiktok_user.user_cover&dr=14579&idc=my2&ps=13740610&refresh_token=4358a587&shcp=c1333099&shp=30310797&t=4d5b0474&x-expires=1791295200&x-signature=81niXSrfEjwb6lt1qecTrWo3WZA%3D
- >-
https://p19-common-sign.tiktokcdn.com/tos-alisg-avt-0068/9680d75d3265b4ad61928d456600ab5c~tplv-tiktokx-cropcenter:100:100.webp?biz_tag=tiktok_user.user_cover&dr=14579&idc=my2&ps=13740610&refresh_token=bb3aa2be&shcp=c1333099&shp=30310797&t=4d5b0474&x-expires=1791295200&x-signature=nkF9ZcbBc6L8BcflfYS2k%2F%2B2phQ%3D
- >-
https://p16-common-sign.tiktokcdn.com/tos-alisg-avt-0068/9680d75d3265b4ad61928d456600ab5c~tplv-tiktokx-cropcenter:100:100.jpeg?biz_tag=tiktok_user.user_cover&dr=14579&idc=my2&ps=13740610&refresh_token=312727bd&shcp=c1333099&shp=30310797&t=4d5b0474&x-expires=1791295200&x-signature=9AlcPprWlfv1bYJ%2BCiQ9N2D497I%3D
width: 720
height: 720
verified: false
verificationLabel: null
enterpriseVerifyReason: null
followerCount: 2822
likeCount: 1432
liveRoomId: null
isLive: false
- id: '6812646607822849030'
secUid: >-
MS4wLjABAAAACYtfQgGRI1X0f8j_PuUGQmZRgJt5JpZx_RPRWSbm6EnygBHUmH0Qe-a-c8rbhndp
handle: paulkincaid2
nickname: Paul
bio: >-
Entertaining content to make you laugh, cry, or want to
punch me in the face
url: https://www.tiktok.com/@paulkincaid2
avatarUrl: >-
https://p16-common-sign.tiktokcdn.com/tos-maliva-avt-0068/fcf92f26f72f5f84ab54871715e90f35~tplv-tiktokx-cropcenter:100:100.webp?biz_tag=tiktok_user.user_cover&dr=14579&idc=my2&ps=13740610&refresh_token=9df66af3&shcp=c1333099&shp=30310797&t=4d5b0474&x-expires=1791295200&x-signature=i57ZIVx7nErBzSwCBJAr%2FOfY7IM%3D
avatar:
uri: tos-maliva-avt-0068/fcf92f26f72f5f84ab54871715e90f35
urls:
- >-
https://p16-common-sign.tiktokcdn.com/tos-maliva-avt-0068/fcf92f26f72f5f84ab54871715e90f35~tplv-tiktokx-cropcenter:100:100.webp?biz_tag=tiktok_user.user_cover&dr=14579&idc=my2&ps=13740610&refresh_token=9df66af3&shcp=c1333099&shp=30310797&t=4d5b0474&x-expires=1791295200&x-signature=i57ZIVx7nErBzSwCBJAr%2FOfY7IM%3D
- >-
https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/fcf92f26f72f5f84ab54871715e90f35~tplv-tiktokx-cropcenter:100:100.webp?biz_tag=tiktok_user.user_cover&dr=14579&idc=my2&ps=13740610&refresh_token=fe6a7fa4&shcp=c1333099&shp=30310797&t=4d5b0474&x-expires=1791295200&x-signature=yDzcygnMFGxOAS5D%2F8g4AvazTZc%3D
- >-
https://p16-common-sign.tiktokcdn.com/tos-maliva-avt-0068/fcf92f26f72f5f84ab54871715e90f35~tplv-tiktokx-cropcenter:100:100.jpeg?biz_tag=tiktok_user.user_cover&dr=14579&idc=my2&ps=13740610&refresh_token=fa047825&shcp=c1333099&shp=30310797&t=4d5b0474&x-expires=1791295200&x-signature=lkMoCVbRvcgP1rIhvH6tkG5JX8I%3D
width: 720
height: 720
verified: false
verificationLabel: null
enterpriseVerifyReason: null
followerCount: 227900
likeCount: 2119547
liveRoomId: null
isLive: false
- id: '6818673157319721989'
secUid: >-
MS4wLjABAAAAYXPoFhbxg1JNqiY7oYwLP8XqamMAf2wqzyKn0WVHVlCy8ooAf1jxTU3NZEipmetP
handle: gavla_
nickname: Paul
bio: Just for laughs
url: https://www.tiktok.com/@gavla_
avatarUrl: >-
https://p16-common-sign.tiktokcdn.com/tos-maliva-avt-0068/86b71631b8724d68fc46dd9f8aac680e~tplv-tiktokx-cropcenter:100:100.webp?biz_tag=tiktok_user.user_cover&dr=14579&idc=my2&ps=13740610&refresh_token=71e851ce&shcp=c1333099&shp=30310797&t=4d5b0474&x-expires=1791295200&x-signature=SOgVO7JNq%2FW9s5mgCvcDiVzsfgk%3D
avatar:
uri: tos-maliva-avt-0068/86b71631b8724d68fc46dd9f8aac680e
urls:
- >-
https://p16-common-sign.tiktokcdn.com/tos-maliva-avt-0068/86b71631b8724d68fc46dd9f8aac680e~tplv-tiktokx-cropcenter:100:100.webp?biz_tag=tiktok_user.user_cover&dr=14579&idc=my2&ps=13740610&refresh_token=71e851ce&shcp=c1333099&shp=30310797&t=4d5b0474&x-expires=1791295200&x-signature=SOgVO7JNq%2FW9s5mgCvcDiVzsfgk%3D
- >-
https://p19-common-sign.tiktokcdn.com/tos-maliva-avt-0068/86b71631b8724d68fc46dd9f8aac680e~tplv-tiktokx-cropcenter:100:100.webp?biz_tag=tiktok_user.user_cover&dr=14579&idc=my2&ps=13740610&refresh_token=5e45049f&shcp=c1333099&shp=30310797&t=4d5b0474&x-expires=1791295200&x-signature=R7F2ECyyvjJT5fx%2Boe%2BuE4G9Foc%3D
- >-
https://p16-common-sign.tiktokcdn.com/tos-maliva-avt-0068/86b71631b8724d68fc46dd9f8aac680e~tplv-tiktokx-cropcenter:100:100.jpeg?biz_tag=tiktok_user.user_cover&dr=14579&idc=my2&ps=13740610&refresh_token=8773b27b&shcp=c1333099&shp=30310797&t=4d5b0474&x-expires=1791295200&x-signature=xNPiynUo27IL4s%2BmRqaB07IeetM%3D
width: 720
height: 720
verified: false
verificationLabel: null
enterpriseVerifyReason: null
followerCount: 200200
likeCount: 3096593
liveRoomId: null
isLive: false
count: 10
cursor: 10_20261005224524E46DA90E886C6A7D7452
hasMore: true
fetchedAt: '2026-10-05T14:45:25.529Z'
meta:
requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
creditsCharged: 1
creditsRemaining: 4999
cached: false
'400':
description: Invalid cursor.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: BAD_REQUEST
message: The request was invalid.
requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
'401':
description: Missing, invalid, or revoked API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: UNAUTHORIZED
message: API key required — pass it in the `x-api-key` header.
requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
'402':
description: Not enough credits for this request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: INSUFFICIENT_CREDITS
message: >-
This request costs 1 credit, but your balance is 0. Top up
to continue.
requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
'422':
description: >-
Invalid query parameters (missing or empty query, or longer than 100
characters).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: VALIDATION_ERROR
message: Request validation failed
requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
details:
- path: url
message: Required
'429':
description: Over the per-minute rate limit — honour `Retry-After`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: RATE_LIMITED
message: >-
Rate limit exceeded — max 100 requests per 60s. Retry in
~30s.
requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
'503':
description: >-
Temporarily unavailable — retry after `Retry-After`. `error.code`
tells you why: `UPSTREAM_BLOCKED` (the source blocked this request),
`EXTRACTION_FAILED` (the source returned unexpected data),
`PLATFORM_UNAVAILABLE` (the source is down), or
`SERVICE_UNAVAILABLE` (we are at capacity).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: UPSTREAM_BLOCKED
message: >-
The source is temporarily unavailable. Please try again
shortly.
requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
components:
schemas:
Error:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: NOT_FOUND
message:
type: string
example: The requested content was not found.
requestId:
type: string
example: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
details:
type: array
items:
type: object
description: Present on validation errors.
required:
- code
- message
- requestId
required:
- error
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
Your API key. Send it in the `x-api-key` header (or `Authorization:
Bearer `). Create and manage keys from your dashboard.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.