# solari tiktok account search

> 브랜드나 크리에이터 이름을 TikTok account_id로 바꿔요.

- **CLI**: `solari tiktok account search`
- **MCP 도구**: `solari_tiktok_account_search`
- **권한**: `solari:read` — 로그인한 SOLARI 계정이면 쓸 수 있어요.

브랜드/크리에이터 이름이나 TikTok 핸들을 추적 중인 후보 TikTok 계정으로 해석해요. 빠른 결정적 인덱스 검색이자 타입어헤드 방식으로, 핸들은 접두사로 표시 nickname은 텍스트 매치로 매칭하고 매치 품질과 팔로워 수 순으로 정렬해요. found와 함께 가장 잘 맞는 순으로 정렬된 items를 반환하며(items[0]이 최상위 매치), 각 항목은 account_id(다른 solari_tiktok_* 툴이 받는 SOLARI 계정 UUID. TikTok account_id는 어떤 Instagram account_id와도 다른 값이며 둘은 절대 호환되지 않아요), username(TikTok 핸들), nickname, follower_count, video_count, region, is_verified, is_private, is_commerce_user, commerce_user_category, profile_url을 담아요. found=false에 items가 비어 있으면 매치가 없다는 뜻이에요. query는 핸들이나 nickname에 실제로 나타나야 하므로, 발음 기반 별칭으로 해석되지 않으면 원래 표기로 다시 시도해 보세요. 사용자가 특정 국가를 요청한 게 아니라면 region은 설정하지 않아요: 추적 중인 TikTok 계정 상당수는 region이 없고, region 필터를 걸면 그 계정들이 떨어져 나가요. 아직 추적 중이 아닌 핸들은 여기 나타나지 않아요. 그런 핸들은 solari_tiktok_account_profile이나 solari_tiktok_account_posts로 바로 넘기면 실시간으로 수집해요. 로그인된 SOLARI 계정이면 누구나 사용할 수 있어요.

**언제 쓰나** — 모든 TikTok 질문의 첫 호출. Instagram account_id는 여기서 통하지 않아요.

**무엇이 돌아오나** — 가장 잘 맞는 순으로 정렬된 후보 계정. items[0]이 최상위 매치예요.

## 파라미터

- `query` (string, 필수) — 해석할 브랜드/크리에이터 이름 또는 TikTok 핸들.
- `limit` (integer, 선택, ≥ 1) — 반환할 최대 후보 수, 기본값 8. 50을 넘는 값은 50으로 잘려요.
- `region` (string, 선택, ≤ 8 chars) — KR, JP, US 같은 선택적 리전 코드. 사용자가 특정 국가를 요청한 게 아니라면 설정하지 않아요: region을 설정하면 리전이 알려지지 않은 계정은 떨어져 나가요.

## 응답

### `Response`

- `found` (boolean) — 후보가 하나 이상 매치되면 true.
- `items` (object[]) — 후보 목록.

### `items[]`

- `account_id` (uuid) — TikTok account_id. 같은 브랜드라도 Instagram account_id와 절대 호환되지 않아요.
- `username` (string) — TikTok 핸들.
- `nickname` (string) — 표시 이름.
- `follower_count / video_count` (integer) — 팔로워 수와 영상 수.
- `region` (string | null) — 리전 코드. 추적 중인 계정 상당수는 값이 없어요.
- `is_verified / is_private` (boolean) — 인증 및 비공개 플래그.
- `is_commerce_user` (boolean) — 커머스 계정인지 여부.
- `commerce_user_category` (string | null) — 커머스 카테고리, 예: Beauty.
- `profile_url` (string) — 공개 프로필 URL.

## 예시

```console
$ solari tiktok account search query=innisfree limit=5
```

_읽기 편하도록 긴 문자열과 반복되는 배열 항목을 줄였어요._

```json
{
  "found": true,
  "items": [
    {
      "account_id": "019b2137-f76e-7b33-9437-26044fa7b1ed",
      "username": "innisfree_official",
      "nickname": "Innisfreeofficial",
      "follower_count": 143800,
      "video_count": 767,
      "region": "KR",
      "is_verified": true,
      "is_private": false,
      "is_commerce_user": true,
      "commerce_user_category": "Beauty",
      "profile_url": "https://www.tiktok.com/@innisfree_official"
    }
  ]
}
```

## MCP 호출로 쓰면

```json
{
  "name": "solari_tiktok_account_search",
  "arguments": {
    "query": "innisfree",
    "limit": 5
  }
}
```

## 주의사항

- 사용자가 특정 국가를 요청한 게 아니라면 region은 설정하지 않아요. 추적 중인 계정 상당수는 region이 없어서, region을 설정하면 그 계정들이 통째로 떨어져 나가요.
- 추적 중이 아닌 핸들은 여기 나타나지 않아요. tiktok account profile이나 tiktok account posts로 바로 넘기면 실시간으로 수집해요.

## 관련 도구

- [`solari_tiktok_account_profile`](https://solari.sh/docs/tools/tiktok-account-profile.md?lang=ko)
- [`solari_tiktok_account_posts`](https://solari.sh/docs/tools/tiktok-account-posts.md?lang=ko)
- [`solari_instagram_account_search`](https://solari.sh/docs/tools/instagram-account-search.md?lang=ko)