# solari fetch tiktok account search

> TikTok 계정을 이름으로 라이브 검색합니다.

- **CLI**: `solari fetch tiktok account search`
- **MCP 도구**: `solari_fetch_tiktok_account_search`
- **권한**: `solari:read`
- **이용 가능 플랜**: 무료 체험 · Plus · Pro · Enterprise
- **크레딧**: 1

이름이나 핸들 일부로 TikTok에 직접 계정을 물어봅니다. 결과는 핸들, 표시 이름, bio, 인증 배지, 팔로워 수, 프로필 사진, URL만 든 얇은 목록이고 TikTok이 정한 순서입니다. 이미 카탈로그에 있는 계정에는 account_id가 붙고, 나머지는 고른 계정을 fetch tiktok account로 추가하면 됩니다.

**언제 쓰나요** — catalog account search가 이름을 모르거나, 이름은 알지만 정확한 TikTok 핸들은 모를 때 쓰세요.

**돌려주는 값** — TikTok 순서대로 최대 limit개 후보, 다음 페이지용 cursor, 첫 후보를 읽거나 추가하는 명령입니다.

## 파라미터

- `query` (string, 필수, ≤ 100 chars) — 이름 또는 핸들 일부. @는 있어도 없어도 됩니다
- `limit` (integer, 선택, 기본값 10, 1–30) — 한 페이지에 최대 몇 개까지
- `cursor` (string, 선택, ≤ 1024 chars) — 같은 query의 이전 페이지에서 받은 next_cursor. 첫 페이지에서는 빼세요

## 응답

### `Response`

- `query` (string) — 검색에 쓴 문자열입니다. @는 뺀 값입니다
- `items` (object[]) — 맞는 계정입니다. TikTok 순서입니다
- `total` (integer) — 이 페이지의 후보 수입니다
- `has_more` (boolean) — TikTok에 다음 페이지가 있으면 true입니다
- `next_cursor` (string | null) — 같은 query와 함께 cursor로 넘기는 값입니다. 마지막 페이지면 null입니다
- `next` (string) — 첫 후보에 대한 명령입니다. 이미 수집된 계정이면 catalog 프로필, 아니면 fetch tiktok account입니다. 후보가 있을 때만 옵니다

### `items[]`

- `username` (string) — 핸들입니다. @는 없습니다
- `nickname` (string | null) — 표시 이름입니다
- `bio` (string | null) — bio 텍스트입니다
- `is_verified` (boolean | null) — 인증 배지입니다
- `follower_count` (integer | null) — TikTok이 지금 보여 주는 팔로워 수입니다
- `profile_pic_url` (string | null) — 프로필 사진 URL입니다
- `url` (string) — 공개 프로필 URL입니다
- `account_id` (uuid | null) — 이미 카탈로그에 있는 계정이면 TikTok account_id, 아니면 null입니다

## 예시

```console
$ solari fetch tiktok account search query=innisfree limit=1
```

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

```json
{
  "query": "innisfree",
  "items": [
    {
      "username": "innisfree_official",
      "nickname": "Innisfreeofficial",
      "bio": "NATURE MEETS KOREAN SKIN SCIENCE",
      "is_verified": true,
      "follower_count": 143900,
      "profile_pic_url": "https://p16-common-sign.tiktokcdn-eu.com/tos-alisg-avt-0068/3f8e48dc4a284a8ead37e93175ebdb86~tplv-tiktokx-cropcenter:720:720.jpeg?…",
      "url": "https://www.tiktok.com/@innisfree_official",
      "account_id": "019b2137-f76e-7b33-9437-26044fa7b1ed"
    }
  ],
  "total": 1,
  "has_more": true,
  "next_cursor": "eyJjIjoiMSIsInMiOiIyMDI2MDkyOTA2NDMxMkE3QzRFMTlCMkQzRjVBOEM2RTAxIn0",
  "next": "solari catalog tiktok account profile username=innisfree_official"
}
```

## MCP 호출

```json
{
  "name": "solari_fetch_tiktok_account_search",
  "arguments": {
    "query": "innisfree",
    "limit": 1
  }
}
```

## 주의사항

- 순서와 랭킹은 TikTok 기준이라 공식 계정이 항상 맨 앞은 아닙니다. 고르기 전에 is_verified와 follower_count를 확인하세요.
- 아무것도 저장하지 않습니다. account_id가 있는 후보는 이미 카탈로그에 있어서 catalog tiktok 도구로 바로 읽을 수 있습니다. account_id가 없는 후보는 그 username으로 fetch tiktok account를 호출하면 추가됩니다.
- has_more가 true이면 next_cursor를 같은 query와 함께 cursor로 넘겨 다음 페이지를 받으세요. cursor는 다른 query에는 쓸 수 없습니다.
- 호출마다 TikTok에 라이브로 물어봅니다. 몇 초 걸리고, cache하지 않습니다. items가 비어 있으면 TikTok에 맞는 계정이 없다는 뜻입니다.

## 관련 도구

- [`solari_fetch_tiktok_account`](https://solari.sh/docs/tools/fetch-tiktok-account.md?lang=ko)
- [`solari_catalog_tiktok_account_search`](https://solari.sh/docs/tools/catalog-tiktok-account-search.md?lang=ko)
- [`solari_catalog_tiktok_account_profile`](https://solari.sh/docs/tools/catalog-tiktok-account-profile.md?lang=ko)
- [`solari_fetch_tiktok_post_search`](https://solari.sh/docs/tools/fetch-tiktok-post-search.md?lang=ko)