---
title: "TikTok Search Users API"
method: GET
path: "/v1/tiktok/search/users"
tags: ["TikTok"]
---

# TikTok Search Users API

`GET /v1/tiktok/search/users`

## Request

- Base URL: `https://api.captapi.com`
- URL: `https://api.captapi.com/v1/tiktok/search/users`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Search TikTok users — distinct creators only, id + secUid, per-counter isApproximate flags, cursor pagination.

Pass a search query and get matching creators as clean JSON: id + secUid (stable TikTok identity — secUid is what follower/video list calls need), username, displayName, bio, url, followers, following, videos, likes, verified, profileImage, and items[] sample videos when TikTok includes them. Rows are deduped by id — TikTok repeats users across search cards, so totalReturned can be below limit with hasMore false (the honest count, never padding). Every counter carries a per-row *IsApproximate flag (followersIsApproximate, likesIsApproximate, …) computed from the value itself — search display-rounds big totals on some paths. The four counters are always keyed on every row: when TikTok's card omits one (following on some video-derived rows) both the count and its flag are null — a null pair, never two silently missing keys. items[] views/likes carry the same viewsIsApproximate/likesIsApproximate flags (a sample video's 15000000 plays is 15M display-rounded, not an exact int). Cursor pagination via nextCursor + hasMore — the cursor is an opaque string that carries the search session, not just an offset, so pass it back verbatim; a creator ranking with several videos can repeat across a page boundary, so dedupe by id when stitching many pages. The native path is TikTok's signed web search (~1 s per page, single-digit seconds at any limit): the dedicated user-search API for the exact-match head where the exit allows it, topped up from distinct authors derived from general-search video rankings — timings.via says which served (signer / signer-mixed / signer-general). If the signer is unreachable the default answer is an empty degraded page (0 credits) — degradedReason names the failure: native-unavailable (page 1 can't be served at all) vs cursor-unsupported (a page-2+ request degraded after page 1 worked). The fallback parameter is deprecated: it has no effect, sending it adds an X-Captapi-Warning header, and it is removed on 2026-12-17. Prefer id/secUid over @handle for CRM joins — handles change. Envelope includes timings{path,via,nativeMs,totalMs}. Flat 1 credit on every path.

Docs: https://captapi.com/apis/tiktok-search-users

## Query parameters

- `q` string, required
- `limit` integer
- `cursor` string
- `fallback` boolean
- `cache` boolean

## Response `200`

Success. The data object for this endpoint.

- object
  - `success` unknown, required
  - `data` object, required
    - `query` string: The search query you sent.
    - `totalReturned` integer: Number of items returned in this response.
    - `hasMore` boolean: Whether more results are available beyond this page. When true, pass nextCursor to fetch the next page.
    - `nextCursor` string: Cursor to pass for the next page of results. May be null when the platform does not expose deep pagination (e.g. some Facebook Ad Library searches).
    - `users` object[]
      - `id` string: Id of this users item.
      - `secUid` string: TikTok secure user ID — required for many platform-internal list endpoints.
      - `username` string: Account username / handle.
      - `displayName` string: Display name of the account. Canonical across profile endpoints (prefer over name).
      - `bio` string: Profile bio. Canonical across profile endpoints (prefer over description on YouTube).
      - `url` string: Canonical URL of the item.
      - `followers` integer: Follower count.
      - `following` integer: Number of accounts followed.
      - `likes` integer: Like count (number).
      - `verified` boolean: Whether the account is verified on this platform.
      - `profileImage` string: Profile image URL. Deprecated alias of avatar on Instagram/Twitter/Threads/TikTok profile endpoints (one release).
      - `followersIsApproximate` boolean: True when followers was parsed from a compact Facebook chrome label (e.g. 28M) rather than an exact integer.
      - `followingIsApproximate` boolean: Following is approximate. Example: false.
      - `likesIsApproximate` boolean: True when engagement.likes looks display-rounded rather than exact.

## Other responses

- `400`: Bad request: wrong platform URL, unknown endpoint, or an invalid parameter value. Not billed.
- `401`: Missing, invalid or revoked API key. Not billed.
- `402`: Not enough credits for this request. Not billed.
- `404`: The resource does not exist or is not public. Not billed.
- `422`: A required parameter is missing or has the wrong type. Not billed.
- `429`: Rate limit reached. Wait for Retry-After seconds. Not billed.
- `502`: The platform could not be reached or returned nothing usable. Retryable, not billed. 503 and 504 use the same envelope.

## Changes

- **2026-10-19** `22d8e96a11f2`: 1 breaking, 1 info
  - for the `query` request parameter `fallback`, default value `false` was removed
  - `query` request parameter `fallback` was deprecated

[Operation history](https://skmtc.dev/captapi/apis/captapi-api/changes/v1/tiktok/search/users/get.md)

---

[API](https://skmtc.dev/captapi/apis/captapi-api.md) · [All operations](https://skmtc.dev/captapi/apis/captapi-api/llms.txt) · [OpenAPI document](https://skmtc.dev/captapi/apis/captapi-api/revisions/c9b9ac5ff1bd?raw)