CaptapiCaptapi
TikTok · Guide

How to run a TikTok search users

TL;DR
To run a TikTok search users, sign up for a free Captapi key, then send one GET request to /v1/tiktok/search/users with your input. You get clean JSON back in seconds for 1 credit per call — no OAuth, scraping or platform SDKs. Search TikTok users — distinct creators only, id + secUid, per-counter isApproximate flags, cursor pagination.
Get your free API keyAPI reference

How to run a TikTok search users (step by step)

  1. 1

    Get a free API key

    Create a free Captapi account (100 credits, no card) and generate an API key from the dashboard.

  2. 2

    Call the TikTok Search Users API

    Send an authenticated GET request to /v1/tiktok/search/users with your input. No OAuth, no scraping setup.

  3. 3

    Read the JSON response

    Parse the clean JSON response. Pass cache=true for a free 24h cache hit; default is always fresh.

Code example

curl "https://api.captapi.com/v1/tiktok/search/users?q=khaby" \
  -H "Authorization: Bearer capt_live_..."
# or: -H "x-api-key: capt_live_..."

What the response looks like

{
  "success": true,
  "data": {
    "query": "khaby",
    "totalReturned": 2,
    "hasMore": true,
    "nextCursor": "30:20260809225002ADA0CE0CD6A89",
    "users": [
      {
        "id": "127905465618821121",
        "secUid": "MS4wLjABAAAAwAg0rSzO65WQfz4RzQgGv2Xdv108BgPXhRrrmNVIHQZ9PO8-flwwRtEppYTS0OjA",
        "username": "khaby.lame",
        "displayName": "Khabane lame",
        "bio": "Se vuoi ridere sei nel posto giusto😎 If u wanna laugh u r in the right place😎",
        "url": "https://www.tiktok.com/@khaby.lame",
        "followers": 162476412,
        "following": 81,
        "likes": 2650481169,
        "verified": true,
        "profileImage": "https://p19-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/08987e23b94057953fd4f1738694bf5f~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=ef0e9f02&x-expires=1786006800&x-signature=7Mx8iglAOcSlnXlc8QyIBifQV0M%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast8",
        "followersIsApproximate": false,
        "followingIsApproximate": false,
        "likesIsApproximate": false
      },
      {
        "id": "6663294979903422470",
        "secUid": "MS4wLjABAAAAbq-1Yqpp1a6u5KbV_sMg93_FK7AN3d6MJeZ3H0Yj3vZXOtqFXXjc2TIkMW7flCxX",
        "username": "espn",
        "displayName": "ESPN",
        "bio": "Serving Sports Fans. Anytime. Anywhere.",
        "url": "https://www.tiktok.com/@espn",
        "followers": 60100768,
        "following": 657,
        "likes": 5769632093,
        "verified": true,
        "profileImage": "https://p16-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/7310257743653240837~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=7e4745a7&x-expires=1786006800&x-signature=cJrkoOAcA8KBqdaAWgBgeaE6f6w%3D&t=4d5b0474&ps=13740610&shp=a5d48078&shcp=81f88b70&idc=useast8",
        "followersIsApproximate": false,
        "followingIsApproximate": false,
        "likesIsApproximate": false
      }
    ]
  }
}

Billing metadata (credits charged, cache hit/miss) is returned in the X-Captapi-Credits and X-Captapi-Cache response headers.

Request parameters

NameTypeRequiredDescription
qstring YesSearch query matched against usernames, display names and bios (min 2 characters).
limitintegerNoMax items to return (default 20, max 100). Flat 1 credit per call.
cursorstringNoPagination cursor. Omit (or pass 0) for the first page; then pass the nextCursor value from the previous response verbatim — it carries the search session, not just an offset. A null nextCursor means the end of the results.
fallbackbooleanNoOpt into the scraper actor when native search is unavailable (~2 min, capped at 100 s, degraded-empty on timeout). Default false — return an empty degraded page (0 credits) instead.
cachebooleanNoSet true to serve from the 24h response cache (0 credits on hit). Default false — always fetch fresh.

Frequently asked questions

What does the TikTok Search Users API do?

The TikTok Search Users API lets you search and return matching results from a public TikTok query using one GET request to /v1/tiktok/search/users. It returns clean JSON — no OAuth or infrastructure setup required.

How many credits does the TikTok Search Users API cost?

Each successful call costs 1 credit. Pass cache=true to serve from the 24h cache (0 credits on hit); default is always fresh. Selected profile endpoints also accept cacheMaxAge=1d|3d|7d|14d|30d. Failed or empty results are never charged.

Do I need a TikTok API key or OAuth?

No. A single Captapi key works across every platform Captapi supports — YouTube, TikTok, Instagram, Facebook, Twitter/X, Reddit, Threads, Bluesky, Pinterest, LinkedIn, Rumble, Spotify, Kwai, and more. We handle proxies, rate limits, retries, and authentication for you.

Why do I need secUid if I already have the @handle?

Handles change; id and secUid do not. TikTok's follower lists, video lists, and many internal calls require secUid. Prefer id/secUid for CRM joins and chaining — use username for display.

Why did I get fewer users than my limit with hasMore false?

Rows are deduped by id. TikTok repeats the same user across search cards (and scrapers re-emit the top match when results run out) — we return the honest distinct count, never padding. totalReturned is what uniquely exists.

What do the *IsApproximate flags mean on followers/likes?

Search display-rounds big totals on some paths (162.6M → 162600000). Each counter carries its own flag computed from the value — followersIsApproximate: true means the number is display-rounded; false means exact. Small counts (following, videos) are almost always exact.

When should I pass fallback=true?

Almost never. Native signed search answers in single-digit seconds; when it is unreachable the default response is an empty degraded page (0 credits, degradedReason: native-unavailable) so your pipeline never blocks. fallback=true opts into the scraper actor — expect ~2 minutes, a hard 100 s cap, and possibly a degraded-empty page on actor timeout. Use it only for batch jobs that must have a result at any latency.

native-unavailable vs cursor-unsupported — what's the difference?

Both are empty 0-credit degraded pages, but they name different failures. native-unavailable means page 1 itself can't be served (the signer path is down) — fallback=true is the remedy. cursor-unsupported means a page-2+ request degraded after page 1 worked — re-request page 1 for a fresh cursor instead of paying for the actor.

Can the same creator appear on two pages?

Rarely, yes. Rows are derived from the videos ranking for your query, and one creator can rank with several videos straddling a page boundary. Within one response rows are strictly distinct; when stitching many pages, dedupe by id.

Is the TikTok Search Users API suitable for production use?

Yes. It is a stable REST endpoint with predictable JSON and automatic retries. Pass cache=true to serve from the 24h cache (0 credits on hit); default is always fresh. Selected profile endpoints also accept cacheMaxAge=1d|3d|7d|14d|30d. Use it for analytics, monitoring, and content automation.

Ready to run a TikTok search users?

Start free with 100 credits — no credit card required.

Get your free API key