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." Keyword video search now labels post.ext.region on each video so you filter country client-side — distinct from this country= user search — in the TikTok video search API.

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. Once you have a country-filtered row with a handle on it, seeding that same handle into the TikTok account finder returns a list of lookalike creators for 5 credits (28 to 30 for three of our four test seeds), no second keyword needed. The same country and region options now exist on Instagram, covered in Instagram influencers by country. 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.