# solari fetch tiktok post search

> TikTok 영상을 키워드로 라이브 검색합니다.

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

키워드로 TikTok에 직접 영상을 검색합니다. 결과는 TikTok의 관련도 순이고, 영상 id, URL, 작성자, 캡션, 게시 시각, 재생·좋아요·댓글·공유 수, 길이, 커버 이미지만 든 얇은 목록입니다. 아무것도 저장하지 않으며, 어느 결과든 URL로 fetch tiktok post를 호출하면 수집됩니다.

**언제 쓰나요** — 어떤 주제, 브랜드, 문구에 대해 사람들이 TikTok에 무엇을 올리는지 보고 싶은데 시작할 핸들이 없을 때 쓰세요.

**돌려주는 값** — TikTok 순서대로 최대 limit개 영상, 다음 페이지용 cursor, 첫 영상을 수집하는 fetch 명령입니다.

## 파라미터

- `query` (string, 필수, ≤ 100 chars) — 검색할 키워드나 문구
- `limit` (integer, 선택, 기본값 20, 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입니다
- `note` (string | null) — 주의할 점이 있을 때만 옵니다. 예를 들어 맞는 영상이 없을 때입니다
- `next` (string) — 첫 영상을 수집하는 fetch 명령입니다. 결과가 있을 때만 옵니다

### `items[]`

- `video_id` (string) — TikTok 공개 숫자 id입니다
- `url` (string) — 공개 영상 URL입니다. fetch tiktok post에 그대로 넘기면 됩니다
- `username` (string | null) — 작성자 핸들입니다. URL에 들어 있을 때만 옵니다
- `caption` (string | null) — 캡션입니다
- `posted_at` (timestamp | null) — 게시 시각 (UTC)
- `play_count` (integer | null) — 재생 수입니다
- `like_count` (integer | null) — 좋아요 수입니다
- `comment_count` (integer | null) — 댓글 수입니다
- `share_count` (integer | null) — 공유 수입니다
- `duration_seconds` (integer | null) — 영상 길이(초)입니다
- `cover_url` (string | null) — 커버 이미지 URL입니다. 만료될 수 있으니 바로 쓰세요

## 예시

```console
$ solari fetch tiktok post search query="green tea ceramide" limit=1
```

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

```json
{
  "query": "green tea ceramide",
  "items": [
    {
      "video_id": "7680375687139642645",
      "url": "https://www.tiktok.com/@innisfree_official/video/7680375687139642645",
      "username": "innisfree_official",
      "caption": "Deeply hydrated skin—NO OFF HOURS. 💚  wherever the day takes MINGYU—his hydration stays SUPERCHARGED ⚡️ Green Tea Ceramide Milk: Lightweight milky toner that won't clog your pores …",
      "posted_at": "2026-09-02T12:00:00Z",
      "play_count": 493,
      "like_count": 37,
      "comment_count": 2,
      "share_count": 0,
      "duration_seconds": 23,
      "cover_url": "https://p16-common-sign.tiktokcdn-eu.com/tos-alisg-p-0037/oQfAEIgDBRiLAeFsAQeZhIQ9CEfIAgBDpAqbfE~tplv-tiktokx-origin.image?…"
    }
  ],
  "total": 1,
  "has_more": true,
  "next_cursor": "eyJjIjoiMSIsInMiOiIyMDI2MDkyOTA2NDUxOEIzRDJGMDdBOUMxRTRCNkQ4RjAyIn0",
  "note": null,
  "next": "solari fetch tiktok post url=https://www.tiktok.com/@innisfree_official/video/7680375687139642645"
}
```

## MCP 호출

```json
{
  "name": "solari_fetch_tiktok_post_search",
  "arguments": {
    "query": "green tea ceramide",
    "limit": 1
  }
}
```

## 주의사항

- 결과는 TikTok의 관련도 랭킹이라 느슨하게만 관련된 영상이 섞일 수 있습니다. 쓰기 전에 caption과 username을 확인하세요.
- 아무것도 저장하지 않고 결과에 post_id도 없습니다. 결과의 url로 fetch tiktok post를 호출하면 작성자와 함께 전체 게시물을 수집해 저장합니다.
- has_more가 true이면 next_cursor를 같은 query와 함께 cursor로 넘겨 다음 페이지를 받으세요. cursor는 다른 query에는 쓸 수 없습니다.
- 호출마다 TikTok에 라이브로 물어봅니다. 몇 초 걸리고, cache하지 않습니다. items가 비어 있고 note가 있으면 맞는 공개 영상이 없다는 뜻입니다.

## 관련 도구

- [`solari_fetch_tiktok_post`](https://solari.sh/docs/tools/fetch-tiktok-post.md?lang=ko)
- [`solari_fetch_tiktok_account_search`](https://solari.sh/docs/tools/fetch-tiktok-account-search.md?lang=ko)
- [`solari_catalog_tiktok_content_search`](https://solari.sh/docs/tools/catalog-tiktok-content-search.md?lang=ko)