TikTok user search by country: 3 KR hits, 15 credits

TikTok user search can return only the creators in one country. On 2026-09-17, production GET /v1/tiktok/search/users?query=cooking&country=KR&limit=3 at https://www.socialcrawl.dev returned three Korean-region accounts — bear_wife12, bing_oii, leoniecadao. author.location was KR / KR / KR, bios 3/3, 15 credits, no cursor, no redirect. That is how you find TikTok creators by country: ISO-2 on the same keyword search.

Same query=cooking without country was still 1 credit and author.location null on all five rows. TikTok's public search page does not expose an ISO-2 creator filter. The Research API Query User call looks up a known handle and has no country field (spec); that dead-end is in TikTok data without an official API.

Stack: curl · GET https://www.socialcrawl.dev/v1/tiktok/search/users · header x-api-key. No TikTok developer app. Five captured calls, trimmed JSON, a two-mode credit table, then how to rerun it.

How do I find TikTok creators by country?

One GET with query plus country= (an ISO 3166-1 alpha-2 code) keeps only creators whose public account region matches. If you want a TikTok creator search for one market, this is the API shape: keyword plus country, not a marketplace board. TikTok's public search page does not take ISO-2.

The 2026-09-17 production call hit https://www.socialcrawl.dev with Cache-Control: no-cache and --max-redirs 0. A 3xx would have failed. Live call:

curl -s --max-redirs 0 -H "x-api-key: $SOCIALCRAWL_API_KEY" \
  -H "Cache-Control: no-cache" -H "Pragma: no-cache" \
  "https://www.socialcrawl.dev/v1/tiktok/search/users?query=cooking&country=KR&limit=3"

HTTP 200 in 4.88s, credits_used: 15, cached: false, dropped: 0, pagination.next_cursor: null, has_more: false. Request req-EZsguJxPPoP6LtHq. Trimmed envelope from that response:

{
  "success": true,
  "platform": "tiktok",
  "endpoint": "/v1/tiktok/search/users",
  "credits_used": 15,
  "credits_remaining": 90136,
  "cached": false,
  "request_id": "req-EZsguJxPPoP6LtHq",
  "pagination": {
    "next_cursor": null,
    "has_more": false,
    "page_size": 3
  },
  "data": {
    "dropped": 0,
    "total": 3,
    "items": [
      {
        "author": {
          "username": "bear_wife12",
          "display_name": "bear_wife",
          "location": "KR",
          "bio": "Breakfast for husband series 🌞\nbreakfast ideas💡👍",
          "followers": 50558,
          "verified": false
        }
      },
      {
        "author": {
          "username": "bing_oii",
          "display_name": "빙이",
          "location": "KR",
          "bio": "집순이의 집밥",
          "followers": 25877,
          "verified": false
        }
      },
      {
        "author": {
          "username": "leoniecadao",
          "display_name": "Leonie",
          "location": "KR",
          "bio": "becoming.\n☁️💫🪽\nxoxo",
          "followers": 27045,
          "verified": false
        }
      }
    ]
  }
}

Every row is KR. Bios 3/3. Country mode already carries author.location and bio on the row. That is the unified schema — you do not set include=profile on this call. The formula is 5 credits × delivered rows; unused limit slots are refunded per the TikTok user search endpoint contract. This call asked for 3, got 3, paid 15. Unused slots refund when the page is short; this page was not.

Country mode is a single shot. There is no cursor. Docs default is 8 rows, max 20 via limit; this call used limit=3 only. leoniecadao (display name Leonie) is a KR-region account in this capture, not a nationality claim. Handles rotate: a later query=cooking&country=KR will return different usernames. author.location should still be KR on every row.

A cheap follow-up proves the filter is account region, not a guess. GET /v1/tiktok/profile?handle=bing_oii returned HTTP 200, author.location: KR, bio 집순이의 집밥, computed.language: ko, 1 credit (req-mVuw2HgR4Aacr8C8, 4.14s). Followers were 25,877 on the search row and 25,907 on the profile a minute later. Search-index counts can trail the live profile by a few dozen. Looking up one known handle is a different call from filtering the search.

This is not include=profile on a global page, not GET /v1/tiktok/profile as the search itself, not hashtags/popular?countryCode=, and not trending?region=.

What happens if I omit country on TikTok user search?

Same endpoint, same keyword, no country. The cheap global page is unchanged. That is still a TikTok users search across every region, not a country sample.

curl -s --max-redirs 0 -H "x-api-key: $SOCIALCRAWL_API_KEY" \
  -H "Cache-Control: no-cache" -H "Pragma: no-cache" \
  "https://www.socialcrawl.dev/v1/tiktok/search/users?query=cooking&limit=5"

HTTP 200 in 2.76s, 1 credit, author.location null × 5, author.bio null × 5, has_more: true, next_cursor present. Request req-gGW6joIv78B3FQqR. Handles on this call (not a country sample): cookming_, cookingwithshereen, albert_cancook, cookinwithmegg, holmescooking. Two of those five are verified (cookingwithshereen, albert_cancook); follower counts run from 1,509,058 (cookming_) to 15,821,414 (albert_cancook). None of that tells you where the account is registered.

Use omit-country when you want a cheap, paginated keyword page and you do not need region on the row. Pay the 5-per-row country mode when the filter is the point. The unfiltered ~30-row / 1-credit page is measured in TikTok API documentation: 150 followers per credit. This call asked for 5 and got 5 with has_more: true. Do not read 30 from this limit=5 page.

Do not use include=profile as a substitute for country=. Hydration fills bio and author.location on a global page. It does not keep only KR (or US, or DE). Different call, different job.

What does a bad country code cost — and does US behave the same?

A typo is a free 400. ZZ is a user-assigned ISO 3166-1 alpha-2 code, which is a polite way of saying it is not a country. The endpoint agrees.

curl -s --max-redirs 0 -H "x-api-key: $SOCIALCRAWL_API_KEY" \
  -H "Cache-Control: no-cache" -H "Pragma: no-cache" \
  "https://www.socialcrawl.dev/v1/tiktok/search/users?query=cooking&country=ZZ"

HTTP 400 in 72 ms, credits_used: 0. Request req-ie5mzqaOMywjuJvf. Balance after the unfiltered call was 90,135 and stayed 90,135.

{
  "success": false,
  "error": {
    "type": "INVALID_REQUEST",
    "status": 400,
    "message": "Invalid value for 'country': 'ZZ'. Allowed values: US, GB, CA, …, KR, …, KH."
  },
  "credits_used": 0,
  "credits_remaining": 90135,
  "request_id": "req-ie5mzqaOMywjuJvf"
}

The message lists the allowed ISO-2 set (it includes KR and US). Invalid code is not a billed empty page.

Same keyword, second market, so KR is not a one-off:

curl -s --max-redirs 0 -H "x-api-key: $SOCIALCRAWL_API_KEY" \
  -H "Cache-Control: no-cache" -H "Pragma: no-cache" \
  "https://www.socialcrawl.dev/v1/tiktok/search/users?query=cooking&country=US&limit=3"

HTTP 200 in 5.36s, 3 rows, author.location US / US / US, bios 2/3, 15 credits, next_cursor: null, has_more: false. Request req-vJg84OHsw1krbaj2.

Same formula as KR (5 × 3 = 15). Same single-shot pagination. Bios are not guaranteed: universal_truther came back with location: US and bio: null (and posts_count: 0). Write what the row has. britsgoneusa is a US-region row in this capture; the bio is about a visa. Public account region is what the account is registered as, not a passport.

Is country= the same as video-search region=?

No. Four "country" ideas get conflated, and only the first one is this param.

1. Creator's public account region. The two-letter region on the account. The SocialCrawl API puts it on author.location. search/users?country=KR keeps only those rows. A filter on the creator, not a routing hint. (endpoint docs)
2. Request locale / proxy. Video search?region= and default trending region= set where the request comes from. They do not filter creators. This run did not call /v1/tiktok/search.
3. Audience geography. Where followers live. TikTok One treats this as a separate control from creator country. On a known handle, GET /v1/tiktok/user/audience ranks countries from a sample of public followers. Not search.
4. Video registered region. Research API region_code on a video query; trending rows carry post.ext.region. Neither is "creators whose account is in KR."

Creator Marketplace filters creator country and audience country as two separate UI controls. That is logged-in matchmaking, not GET /v1/tiktok/search/users. Do not conflate hashtags/popular?countryCode= either — that is a Creative Center hashtag board.

How do I rerun this TikTok user search?

1. Get a key. A SocialCrawl account includes 100 free credits, no card. Auth is x-api-key — one API key. No TikTok developer app, no Research API application.
2. Run the same KR call from above (query=cooking&country=KR&limit=3). Rows and handles will move; author.location should still be KR on every returned row; credits_used should be 5 × rows. Optional Python twin:

import os
import requests

r = requests.get(
    "https://www.socialcrawl.dev/v1/tiktok/search/users",
    params={"query": "cooking", "country": "KR", "limit": 3},
    headers={"x-api-key": os.environ["SOCIALCRAWL_API_KEY"]},
    timeout=60,
)
payload = r.json()
print(r.status_code, payload.get("credits_used"), payload.get("pagination"))

3. Where next: the explorer to see the payload before writing a single line; the TikTok user search endpoint for the live param table; the TikTok platform catalogue for the rest of the reads; the API reference if you want the envelope contract. If you want the 1-credit global page instead, that is the unfiltered search. MCP and Agent Skills wrap the same x-api-key surface if an agent should fire the GET.

Frequently asked questions

Can I run a TikTok account search and keep only one country?

Yes. GET /v1/tiktok/search/users?query=…&country=KR (ISO-2) keeps creators whose public account region matches. In-app account search by name is username lookup, not a country filter. This run: query=cooking&country=KR&limit=3 returned 3 KR rows at 15 credits.

How do I search TikTok users by location?

Send country= as ISO 3166-1 alpha-2 (KR, US, DE). That is not a city, not GPS, and not a map pin. It keeps creators whose public account region matches. It is not filming location and not where the audience lives.

How many credits does a country-filtered TikTok user search use?

5 per delivered row; unused limit slots refunded. This run: KR limit=3 → 15; US limit=3 → 15. Omit country: 1 credit for the global page. Invalid ISO-2: 0. Profile lookup of one handle is a separate 1-credit call.

Does country-filtered user search paginate?

No cursor. Single shot. Docs default 8, max 20 via limit. KR and US calls both came back has_more: false / next_cursor: null. The unfiltered page still paginates (has_more: true on this limit=5 call).

Does country= mean audience geography or where the video was filmed?

Neither. It is public account region only (author.location). Audience geo is a different call (GET /v1/tiktok/user/audience on a known handle). Filming / video-registered region is video-search region=, Research region_code, or trending post.ext.region. To find a TikTok account region by username, use GET /v1/tiktok/profile (1 credit; bing_oii matched KR). include=profile hydrates a global page; it still does not filter.

Handles will rotate on a rerun. author.location should still match the ISO-2 you asked for, and credits_used should still be 5 × rows. Live param table: TikTok user search endpoint. To see the payload before writing a single line, open the explorer.