# TikTok Search Users API (https://www.socialcrawl.dev/platforms/tiktok/search-users)

> Searches TikTok for user accounts matching a query, 30 per page. Each row carries the username, display name, avatar, profile URL, verification status, whether the account is private, and the follower, following, video and like counts. The search surface publishes nothing else, so on a plain call `author.bio`, `author.location`, `author.ext.bio_link` and `author.ext.business_category` are null on every row. Send `include=profile` and every row is joined, in the same call, to the profile lookup that carries them: the bio, the ISO 3166-1 alpha-2 region at `author.location`, the link in the bio and the account category land on each row. Cost: 1 credit for the page plus 1 credit per row filled from a fresh lookup (30 rows, so 31 at most); rows already in cache are filled for free, rows that could not be filled are refunded, and a repeat of the same call within the cache window is 0. Time: a plain call is about 2 seconds; `include=profile` adds 4 to 9 seconds on a fresh page (the lookups run in parallel and the call waits for the slowest, never more than 12 seconds) and nothing when the rows are already cached. `limit=N` (1 to 30) takes the top N rows of the page and, with `include`, caps the extra credits at N. The response carries a `hydration` block itemising rows, lookups, cache hits, credits and milliseconds. The counts on a search row are the search index's own figures and can trail the profile's by a few thousand on a large account; the join never overwrites a value the row already carries. Page with cursor. Send `country=` as an ISO 3166-1 alpha-2 code (KR, US, DE, …) to search for creators whose account region is that country instead of the global page: each returned row already carries `author.location`, the bio and the profile URL, the call does not paginate, and a row whose region does not match is dropped. A row is also dropped when neither its matched video, bio nor name is about your query, so a query that names only a market or a kind of account ("influencers") returns an empty page at 0 credits; put the topic in `query`. Cost: 5 credits per in-country creator returned (8 by default, at most 20 via `limit`); unused slots are refunded. A typo is a free 400. The global 1-credit page is unchanged when `country` is omitted.

TL;DR: `GET /v1/tiktok/search/users` costs 1 credit for the page. include=profile holds 1 credit per row, at most 30 (or `limit`), and keeps only the rows filled from a fresh lookup, so a page is at most 31 credits; rows served from cache are free, unfilled rows are refunded, and a repeat within the cache window costs 0. country= holds 5 credits per requested in-country row (8 by default, at most 20) and keeps only the rows returned, so a miss is 0. The page is cached for 2 minutes and the per-account lookups for 15 minutes. With `max_pages`, `max_items` or `max_credits`, each page walked is billed at this price (a cached page is free), and `max_credits` caps the total. and returns SocialCrawl's unified JSON schema. Single x-api-key auth, 100 free credits on signup.

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `query` | yes | Search keyword or phrase to find TikTok users |
| `cursor` | no | Cursor to get more users. Get 'cursor' from previous response. |
| `trim` | no | Accepted for compatibility; the response is already the canonical shape, so this flag has no effect. |
| `include` | no | Set to `profile` (one token only) to fill `author.bio`, `author.location` (the ISO region), `author.ext.bio_link` and `author.ext.business_category` on every row in this one call. Holds 1 credit per row (at most 30, or `limit`) and keeps only the rows filled from a fresh lookup; rows already in cache and rows that could not be filled are refunded, so the most a call can cost is 1 + rows. Adds 4 to 9 seconds on a fresh page (never more than 12) and nothing when the rows are already cached; read `data.hydration` for the rows, the credits held and kept, and the time. (profile) |
| `limit` | no | Take the top N rows of the page (1 to 30) after the search has run. With `include=profile` it also caps the extra credits at N: `limit=5&include=profile` costs at most 6. With `country=` it is the in-country page size (1 to 20, default 8) and the credit cap at 5 per row. On the global page it is not a page size: `next_cursor` still advances past the full page, so rows beyond N on this page are not returned by the next page. |
| `country` | no | ISO 3166-1 alpha-2 account region to filter by (KR, US, DE, …). Returns only creators whose public region is that country, 5 credits per row returned (8 by default, at most 20). A row is also dropped when neither its matched video, bio nor name is about your query, so a query that names only a market or a kind of account ("influencers") returns an empty page at 0 credits; put the topic in `query`. Omit it for the global 1-credit page. A code this endpoint does not accept is a free 400. (US \| GB \| CA \| AU \| NZ \| IE \| DE \| FR \| ES \| IT \| PT \| NL \| BE \| CH \| AT \| SE \| NO \| DK \| FI \| IS \| PL \| CZ \| SK \| HU \| RO \| BG \| GR \| HR \| RS \| SI \| UA \| RU \| TR \| IL \| AE \| SA \| QA \| KW \| EG \| MA \| ZA \| NG \| KE \| GH \| TZ \| ET \| BR \| MX \| AR \| CO \| CL \| PE \| VE \| EC \| UY \| PY \| BO \| CR \| PA \| DO \| JM \| JP \| KR \| CN \| TW \| HK \| MO \| SG \| MY \| ID \| TH \| VN \| PH \| IN \| PK \| BD \| LK \| NP \| MM \| KH) |
| `max_pages` | no | 1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them. Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped. |
| `max_items` | no | 1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows, then stop with `data.walk.stopped: "max_items"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`"time_budget"`): send the returned cursor with the same params to continue. |
| `max_credits` | no | 1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: "max_credits"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price. |

## Code example

```bash
curl -G "https://www.socialcrawl.dev/v1/tiktok/search/users" \
  --data-urlencode "query=cooking" \
  -H "x-api-key: sc_YOUR_API_KEY"
```

## FAQ

### How do I search for TikTok users with an API?

Send a GET request to /v1/tiktok/search/users with the query parameter set to a keyword or name. SocialCrawl returns a paginated list of matching accounts with handles, display names, follower counts, avatars, and verification status. Add country=KR (or US, DE, and other ISO codes) to return only creators whose public account region is that country.

### Can I filter TikTok user search by creator country?

Yes. Pass country as an ISO 3166-1 alpha-2 code such as KR, US or DE. The response is creators whose public account region is that country, with bio and author.location already on each row. Default 8 results, at most 20 with limit. This is not the region parameter on video search, which only routes a proxy and does not filter creators.

### What fields does the TikTok User Search endpoint return?

Each matching user returns the user id, handle, display name, avatar URL, profile URL, follower, following, video and like counts, and verification status in the unified schema. The bio, the region, the bio link and the account category are null on a plain call, because the search surface does not publish them; add include=profile and every row is filled with them from the profile lookup in the same call.

### How do I paginate through TikTok user search results?

Read the cursor field from the response and pass it as the cursor parameter on your next request. Repeat until cursor is 0 or empty to collect every matching user.

### Can I find verified TikTok creators with this endpoint?

Yes. Each result includes a verified boolean. Filter the response client-side to keep only accounts where verified=true to get a shortlist of verified creators for the query.

### Can I get each account's bio and region in the same call?

Yes. Add include=profile and every row on the page is joined to the profile lookup in the same call, so the bio, the two-letter region at author.location, the bio link and the account category land on each account without a second request per row. The counts the row already carried are kept as they are. Rows already in cache are filled for free, rows that could not be filled are refunded and named in _warnings, and the response carries a hydration block with the rows looked up, filled and served from cache, the credits held and kept, and the milliseconds the join added. Use limit to take only the top N rows and cap the extra credits with it.

### How much does the TikTok User Search API cost?

A plain request costs 1 credit on the standard tier regardless of how many users are returned per page. With include=profile the call holds one more credit per row and keeps it only for rows filled from a fresh lookup, so a full page of 99 accounts is at most 100 credits; rows already in cache are free, rows that could not be filled are refunded, and limit caps the rows and the extra credits together. New accounts get 100 free credits with no credit card required.

See the full TikTok API: https://www.socialcrawl.dev/platforms/tiktok

## Pricing

- Standard endpoints: 1 credit per call
- Advanced endpoints: 5 credits per call
- Premium endpoints: 10 credits per call
- 100 free credits on signup, no credit card required. Cached responses cost 0 credits. Credit packs never expire.
- Full pricing: https://www.socialcrawl.dev/pricing

## Explore with AI

Questions this API answers, phrased for an AI assistant:

- How to search TikTok users with the SocialCrawl API
- What does the SocialCrawl TikTok User Search endpoint return?