# SOLARI

> SOLARI CLI와 MCP — 터미널에서 쓰는 크리에이터·브랜드 인텔리전스.

## 개요

SOLARI CLI는 SOLARI의 크리에이터·콘텐츠 데이터를 터미널로 가져와요. Instagram·TikTok의 브랜드나 크리에이터를 찾고, 광고 콘텐츠 규모를 재고, 캡션과 영상 전사문에 실제로 담긴 말을 검색하고, 지금 뜨는 흐름을 읽어요. jq·셸 스크립트·AI 코딩 에이전트와 그대로 조합되는 평범한 명령이에요.

SOLARI는 MCP 서버로도 열려 있어서, Claude Desktop이나 ChatGPT 같은 앱은 CLI 없이 바로 닿을 수 있어요. 어느 쪽으로 오든 같은 도구와 같은 읽기 전용 권한을 써요.

```console
$ solari instagram account search query=oliveyoung brands_only=true
$ solari tiktok content search query=sunscreen region=KR
$ solari instagram content trending region=KR limit=10 --json
```

## 설치

CLI는 파일 하나예요. 곁들여 깔아야 하는 게 따로 없어요. 평소 도구를 설치하던 방식 중 편한 걸 고르시면 돼요. 어느 쪽이든 받는 건 똑같아요.

**macOS**

Shell:
```bash
curl -fsSL https://solari.sh/install | sh
```
Homebrew:
```bash
brew install brandazine/solari/solari
```
npm:
```bash
npm install -g @brandazine/solari
```
uv:
```bash
uv tool install solari-cli
```
uv tool 은 CLI를 자기만의 환경에 넣고 PATH 에 걸어줘요. 프로젝트 의존성과 부딪히지 않아요.

**Windows**

PowerShell:
```powershell
irm https://solari.sh/install.ps1 | iex
```
npm:
```bash
npm install -g @brandazine/solari
```
uv:
```bash
uv tool install solari-cli
```
uv tool 은 CLI를 자기만의 환경에 넣고 PATH 에 걸어줘요. 프로젝트 의존성과 부딪히지 않아요.

**Linux**

Shell:
```bash
curl -fsSL https://solari.sh/install | sh
```
npm:
```bash
npm install -g @brandazine/solari
```
uv:
```bash
uv tool install solari-cli
```
uv tool 은 CLI를 자기만의 환경에 넣고 PATH 에 걸어줘요. 프로젝트 의존성과 부딪히지 않아요.

설치를 확인해 보세요:

```console
$ solari --version
1.0.0-alpha.9
```

## 빠른 시작

한 번 로그인한 뒤 도구를 훑어보고 하나 실행해 보세요. 훑어보기는 내 컴퓨터에 있는 사본이 답하니까 바로 나와요.

```console
$ solari auth login          # opens a browser; sign in with your SOLARI account
$ solari                     # platforms and groups available to you
$ solari instagram account   # a group path lists its tools
$ solari instagram account search --help    # parameters, without calling

$ solari instagram account search query=oliveyoung brands_only=true limit=3
```

보통은 이름을 account_id 로 바꾼 다음, 그 id 를 다른 도구에 넘기는 순서로 이어져요:

```console
$ solari instagram account search query=innisfree brands_only=true --json \
    | jq -r '.content[0].text | fromjson | .items[0].account_id'
018cabce-14cc-7544-8890-7811ec33ef74

$ solari instagram brand ad stats username=innisfreeofficial
$ solari instagram brand top collaborators username=innisfreeofficial limit=20
```

이름으로만 들어갈 수 있는 건 아니에요. query_type=bio 는 계정이 스스로를 소개한 문구를 검색하니까, 이미 아는 브랜드가 아니라 카테고리에서 출발할 수 있어요:

```console
$ solari instagram account search query="협찬 문의" query_type=bio region=KR limit=10
$ solari instagram account search query=skincare query_type=bio brands_only=true limit=20
```

## 명령 구조

경로가 곧 명령이에요. 도중까지만 치면 그 아래 있는 것들을 보여주고, 도구 경로를 끝까지 치면 실행되고, 필요한 값을 빠뜨리면 실행하는 대신 무엇이 필요한지 알려줘요. 공백과 밑줄은 똑같이 동작하고, solari_ 접두사는 빼도 돼요.

```console
$ solari instagram brand              # lists the group
$ solari brand overview --help        # unambiguous trailing paths resolve while browsing
$ solari instagram brand overview username=innisfreeofficial   # calls
```

인자는 key=value 쌍이에요. 배열은 JSON이나 쉼표 목록 둘 다 받아요.

```bash
solari instagram content batch post_ids='["019f505f-…","019f5060-…"]'
solari instagram content batch post_ids=019f505f-…,019f5060-…
```

- `solari help all` — 모든 명령·도구·파라미터를 한 페이지에 담아 보여줘요. 내 컴퓨터에서 답하고, --json 을 붙이면 기계가 읽기 좋은 형태로 나와요. AI 에이전트에게 한 번에 전부 쥐여줄 때 좋아요.
- `solari get <path ...>` — 도구 실행만 해요. 덜 끝난 경로는 거부해요. 오타가 조용히 목록 출력으로 바뀌면 곤란한 스크립트에서 쓰세요.
- `solari cache refresh` — 내 컴퓨터에 있는 도구 목록을 지금 바로 갱신해요. 알아서 갱신될 때까지 기다리지 않아도 돼요.

## 인증

로그인하면 브라우저가 열려요. 여느 웹사이트에 로그인할 때와 같아요.

- `solari auth login` — 브라우저를 열어요. 열 수 없는 환경(SSH, 에이전트가 대신 실행하는 경우)에서는 로그인 링크를 대신 출력해요.
- `solari auth list` — 로그인해 둔 SOLARI 계정을 모두 보여줘요.
- `solari auth switch <account>` — 이미 로그인해 둔 다른 계정으로 바꿔요. 브라우저를 다시 열지 않아요.
- `solari auth status` — 어느 서버의 어느 계정인지, 무엇에 닿을 수 있는지, 로그인이 언제 만료되는지 보여줘요. 종료 코드 3은 다시 로그인해야 한다는 뜻이에요.
- `solari auth logout` — 로그아웃해요. --all 을 붙이면 모든 계정에서 한 번에 로그아웃해요.

브라우저가 명령을 실행한 컴퓨터로 되돌려주지 못하는 환경(SSH, 컨테이너)에서는, 로그인을 마친 뒤 브라우저 주소창의 주소를 복사해서 기다리고 있는 프롬프트에 붙여넣으면 끝나요.

### 어디까지 닿을 수 있나

권한은 읽기 전용 하나뿐이고, 모든 도구에 적용돼요. 로그인만 마치면 전부 쓸 수 있어요. 등급도, 도구별로 따로 여는 것도 없어요. 요금제로 막는 대신 계정 하나가 얼마나 자주 부를 수 있는지에만 상한이 있어요.

## 출력과 파이핑

결과는 표준 출력으로, 프롬프트와 힌트는 표준 에러로 나가요. 그래서 파이프에는 데이터만 흘러요. 색은 사람이 터미널에서 보고 있을 때만 입혀요. 파이프나 JSON에는 절대 섞이지 않아요.

- `--json` — 가공하지 않은 JSON. 도구의 답은 한 겹 감싸여서 와요. 실제 데이터는 content[0].text 안의 JSON 문자열이에요.
- `--ndjson` — 한 줄에 JSON 객체 하나씩, 응답 안의 항목을 하나씩 흘려요. 그것들을 감싸고 있던 값(total, has_more 등)은 표준 에러로 가요. jq와 함께 쓰거나, 많은 양을 파일로 바로 받아 적을 때를 위한 옵션이에요.
- `--refresh` — 내 컴퓨터의 사본을 건너뛰고 서버에서 도구 목록을 새로 받아요.
- `--color[=always|never|auto]` — 도움말과 도구 목록에 색을 입혀요. 기본값 auto 는 터미널에서 볼 때만 색을 써요. NO_COLOR=1 이면 끄고, FORCE_COLOR=1 이면 파이프에서도 켜요. --no-color 는 never 와 같아요.
- `--verbose, -v` — 명령이 도는 동안 진행 상황을 표준 에러로 찍어요. 비밀 값은 가려져요.

```console
$ solari instagram brand ad posts username=innisfreeofficial months=24 limit=200 --ndjson >> ads.ndjson
$ jq -s 'group_by(.username) | map({creator: .[0].username, posts: length})' ads.ndjson
```

## 설정

설정은 ~/.solari/config.json 에 있어요. 모든 설정에는 짝이 되는 환경변수가 있고, 환경변수를 주면 그 한 번의 명령에서만 그 값이 이겨요. solari config list 는 지금 적용된 값과 그 값이 어디서 왔는지 함께 보여줘요.

```console
$ solari config list
$ solari config set server https://solari.sh
$ solari config unset server
```

- `server · SOLARI_SERVER` — 어느 SOLARI 서버에 접속할지. 기본값은 https://solari.sh 이고, 로그인에 성공하면 그때 쓴 서버를 기억해요.
- `cacheTtl · SOLARI_CACHE_TTL` — 내 컴퓨터의 도구 목록을 최신으로 볼 시간(초). 기본 900이고, 0이면 항상 서버에 물어봐요.
- `cacheShadow · SOLARI_CACHE_SHADOW` — 내 컴퓨터에서 답한 뒤, 뒤에서 조용히 도구 목록을 갱신할지. 기본 true.
- `callTimeout · SOLARI_CALL_TIMEOUT` — 도구 호출을 기다리는 시간(초). 기본 150.
- `catalogTimeout · SOLARI_CATALOG_TIMEOUT` — 도구 목록을 기다리는 시간(초). 기본 8이라, 닿지 않는 서버에 매달리지 않고 금방 실패해요.
- `SOLARI_HOME` — SOLARI 파일을 ~/.solari 말고 다른 곳에 두게 해요.
- `SOLARI_NO_UPDATE_CHECK=1` — 하루 한 번 도는 업데이트 확인을 완전히 꺼요. NO_UPDATE_NOTIFIER=1 도 같은 효과예요.

도구 목록은 내 컴퓨터에서 먼저 답해요. 그래서 훑어보기와 파라미터 확인이 즉시 끝나요. 사본이 위의 시간보다 오래되면 뒤에서 알아서 갱신해요. 사본이 모르는 경로는 그 자리에서 서버에 물어보니까, 서버에 새로 생긴 도구도 바로 쓸 수 있어요.

## 에이전트

명령을 실행하는 에이전트를 이미 쓰고 계시다면, 이 한 줄만 건네고 이 페이지는 닫으셔도 돼요. 사람이 아니라 에이전트가 읽으라고 쓴 짧은 설정 페이지를 받아서 나머지는 알아서 해요. 연결하거나 설치하고, 로그인을 안내하고, 이 컴퓨터의 도구에 SOLARI를 등록하는 것까지요.

```text
set up solari.sh/get-started.md
```

이 아래는 그 페이지가 하는 일이에요. 직접 손으로 하고 싶으시다면 이어서 보시면 돼요.

solari init 은 이 컴퓨터의 AI 에이전트에게 이 CLI가 있다는 걸 알려줘요. 그러면 Instagram·TikTok 데이터에 관한 질문이 나올 때 에이전트가 알아서 이걸 집어요. Claude Code용 skill, Codex의 AGENTS.md 안에 직접 관리하는 구역, zsh 탭 자동완성을 설치해요. solari init --remove 로 전부 되돌릴 수 있어요.

```bash
solari init            # claude + codex + zsh, with a confirmation for each
solari init claude     # just one target
solari init --remove
```

터미널·스크립트, 그리고 명령을 직접 실행하는 에이전트에는 CLI를 쓰세요. Claude Desktop이나 ChatGPT처럼 앱이 직접 서버에 붙는 경우에는 MCP를 쓰시면 돼요.

### 기계가 읽는 문서

이 사이트의 모든 페이지는 같은 주소 뒤에 .md 를 붙인 마크다운 판이 있어요. 레퍼런스 전체를 한 파일로 받아 모델에 그대로 건넬 수도 있어요.

- `/get-started.md` — 이 섹션 맨 위의 한 줄이 가리키는 설정 페이지. 읽으라고가 아니라 에이전트가 실행하라고 쓴 문서예요.
- `/llms.txt` — llms.txt 형식으로 정리한 문서 색인.
- `/llms-full.txt` — 가이드와 도구 전체를 하나의 마크다운 파일로 이어 붙인 것.
- `/docs/tools.md` — 아무 페이지나 마크다운으로. ?lang=ko 나 ?lang=ja 를 붙이면 다른 언어로 받아요.

## MCP로 연결하기

SOLARI는 원격 MCP 서버로도 열려 있어요. MCP를 지원하는 호스트는 여기에 바로 붙어서, CLI와 똑같은 읽기 전용 도구를 설치 없이 그대로 써요. 알려줄 건 주소 하나예요:

```text
https://solari.sh/mcp
```

처음 연결하면 브라우저가 열려서 SOLARI 계정으로 로그인해요. 그다음 호스트가 어떤 도구를 부를지 물어보고, 승인하기 전에는 아무것도 실행되지 않아요. 어느 호스트로 붙어도 읽기 전용이에요.

### Claude Desktop

설정을 열고 사이드바 맨 아래의 Customize 를 눌러요.

![Claude Desktop 설정 사이드바. 맨 아래에 Customize 가 있어요.](https://solari.sh/docs/claude-desktop-settings.webp)

_Settings → Customize_

Connectors 로 가서 Add 를 누르고 창을 채워요. 목록에 표시할 이름과 위의 주소예요.

![Claude Desktop의 Add custom connector 창. 이름과 SOLARI MCP 주소가 채워져 있어요.](https://solari.sh/docs/claude-desktop-add-connector.webp)

_Connectors → Add → Add custom connector_

Continue 를 누르면 로그인을 한 번 거쳐요. 그다음부터는 커넥터 목록에 SOLARI가 남고, 어떤 대화에서든 도구를 쓸 수 있어요. claude.ai 도 같은 방식이에요.

### Claude Code

명령 하나로 서버를 등록해요.

```bash
claude mcp add --transport http solari https://solari.sh/mcp
```

Claude Code가 서버에 처음 닿을 때 로그인을 물어봐요. /mcp 를 치면 연결 상태가 보이고, 로그인을 직접 시작할 수도 있어요.

### ChatGPT

ChatGPT도 Claude Desktop과 같아요. 설정 → Connectors 에서 위 주소를 커스텀 커넥터로 추가하고 로그인하면 돼요. 커스텀 커넥터는 유료 요금제에서만 쓸 수 있어요.

### 그 밖의 호스트

원격 MCP 서버를 지원하는 다른 앱도 붙일 수 있어요. 대개 설정 파일에 이런 항목을 넣어요:

```json
{
  "mcpServers": {
    "solari": {
      "url": "https://solari.sh/mcp"
    }
  }
}
```

> 어떤 앱은 내 컴퓨터에 설치된 MCP 서버만 실행할 수 있어요. 그런 앱은 SOLARI에 바로 닿지 못하니까 CLI를 쓰시면 돼요.

## 오류와 종료 코드

오류 메시지는 다음에 뭘 하면 되는지 알려주고, 종료 코드는 스크립트에서 분기해도 될 만큼 안정적이에요.

- `0` — 성공.
- `1` — 도구나 서버 쪽에서 실패했어요.
- `2` — CLI가 받아들일 수 없는 입력이에요. 없는 경로, 빠진 인자, 잘못된 값 중 하나예요.
- `3` — 로그인이 필요해요. 브라우저 로그인은 사람만 끝낼 수 있으니까, 에이전트는 계속 시도하지 말고 사용자에게 알려야 해요.

### 자주 보는 도구 오류

- `auth expired, reconnect the connector` — 로그인이 만료됐어요. solari auth login 을 다시 실행하거나, 앱에서 커넥터를 다시 연결해 주세요.
- `SOLARI access denied (403)` — SOLARI가 호출을 거절했어요. 모든 도구는 로그인한 계정에게 열려 있으니까, 이건 계정 쪽 문제예요. 다시 로그인해 보시고 계속되면 알려주세요.
- `rate limited, retry shortly` — 짧은 시간에 너무 많이 불렀어요. 잠깐 쉬었다 다시 시도해 주세요.
- `SOLARI upstream timed out` — 호출이 너무 오래 걸렸어요. 대부분의 도구는 90초, 집계와 트렌드 클러스터 도구는 120초예요. 범위를 좁히거나 limit 을 낮춰서 다시 시도해 보세요.

## 데이터 커버리지

SOLARI가 답할 수 있는 범위는 어느 도구를 쓰느냐에 따라 달라져요. 중요한 제한은 둘이에요. 어느 리전을 다루는가, 그리고 얼마나 과거까지 보는가.

- 키워드 검색과 집계(양 플랫폼의 content search·content aggregate)는 KR·JP·US·TW 네 리전을 다루고 최근 약 6개월치를 담아요. 그보다 이전 날짜를 달라고 하면 가장 오래된 날짜로 당겨지고, 실제로 어느 날짜가 쓰였는지 응답이 알려줘요.
- 계정·브랜드·포스트 조회는 전체 이력을 쓰기 때문에, 네 리전이나 6개월 제한을 받지 않아요.
- 리전 중에서는 KR의 커버리지가 가장 깊어요.
- 검색 결과 수는 10,000까지 정확하고 그 위로는 더 올라가지 않아요. TikTok 검색은 9,800에서 더 넘기지 못하니까, 더 깊이 보려면 기간을 좁혀 보세요.

### 식별자

- account_id 는 플랫폼별로 발급되는 SOLARI 계정 UUID예요. 같은 브랜드라도 Instagram account_id 와 TikTok account_id 는 다른 값이며 서로 바꿔 쓸 수 없어요.
- 계정을 받는 자리는 account_id UUID와 username 둘 다 받고, 둘 다 주면 account_id 가 이겨요.
- post_id 는 역시 플랫폼별로 발급되는 SOLARI 포스트 UUID예요. 공개된 대응물은 slug(Instagram shortcode)나 video_id(TikTok 숫자 id)예요.

## 자주 묻는 질문

### CLI가 SOLARI 데이터를 바꿀 수 있나요?

아니요. 모든 도구가 읽기 전용이에요. CLI에도 MCP 서버에도 쓰기를 하는 기능은 없어요.

### Claude 같은 에이전트에서도 쓸 수 있나요?

네. solari init 으로 이 컴퓨터의 에이전트에게 CLI를 알려주거나, MCP 서버에 직접 연결하시면 돼요. 둘 다 읽기 전용이에요.

### 검색이 왜 아무것도 못 찾았나요?

계정 검색은 핸들을 앞에서부터, 표시 이름은 어디에 있든 찾아요. 입력한 말이 둘 중 하나에 실제로 들어 있어야 해서, 별칭이나 줄임말로는 안 찾아져요. 계정이 실제로 쓰는 철자로 다시 시도해 보세요. 콘텐츠 검색이라면 리전이 KR·JP·US·TW 중 하나인지, 날짜가 최근 6개월 안인지 확인해 보세요.

### 요금이 있나요?

지금은 무료로 쓰실 수 있어요. 달라지는 게 있으면 미리 안내해 드릴게요.

## 도구 레퍼런스

SOLARI CLI와 MCP 서버가 제공하는 모든 도구를 파라미터·응답 필드·실제 호출 예시와 함께 정리했어요. 도구 이름은 solari_<platform>_<group>_<name> 규칙을 따르고, CLI에서는 같은 경로를 공백으로 띄어 써요.

### solari instagram account search

> 브랜드·크리에이터 이름이나 프로필 bio 문구를 Instagram account_id로 바꿔요.

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

브랜드/크리에이터 이름이나 Instagram 핸들을 추적 중인 후보 계정으로 해석하고, 프로필 bio 텍스트도 검색해요. 빠른 결정적 인덱스 검색이며, 타입어헤드처럼 후보를 모두 반환해요. query_type으로 무엇을 매칭할지 고를 수 있어요 — auto(기본값)는 핸들을 접두사로, 프로필 표시 이름(한글 또는 영문)을 텍스트 매치로 함께 보고, username이나 full_name은 둘 중 하나로만 좁히며, bio는 프로필 bio 텍스트를 전문 검색해요. bio 모드는 이름이 아니라 계정이 스스로를 어떻게 소개하는지로 찾는 방법이에요("skincare", "협찬 문의", "コスメ"). 매치 품질과 팔로워 수 순으로 정렬해요. found와 함께 가장 잘 맞는 순으로 정렬된 items를 반환하며(items[0]이 최상위 매치), 각 항목은 account_id(다른 모든 툴이 받는 SOLARI 계정 UUID), username, full_name, biography, follower_count, region, is_verified, profile_pic_url을 담아요. found=false에 items가 비어 있으면 매치가 없다는 뜻이에요. 이름으로 찾는 모드에서는 query가 핸들이나 표시 이름에 실제로 나타나야 해요 — 발음 기반 별칭이나 약어로는 해석되지 않으니 원래 표기(예: 영문 브랜드명)로 다시 시도해 보세요. 브랜드명을 해석할 때는 brands_only=true를 설정해 팬 계정과 밈 계정을 걸러내고, query_type=bio와 함께 쓰면 한 카테고리의 브랜드를 한 번에 훑을 수 있어요. region은 특정 국가를 요청받은 게 아니라면 비워 두세요 — 설정하면 그 리전 밖 계정을 전부 버려요. 로그인된 SOLARI 계정이면 누구나 사용할 수 있어요. 이름으로 언급된 엔티티를 해석할 때는 이 툴을 먼저 쓰세요.

**언제 쓰나** — 사용자가 엔티티를 이름으로 언급하면 항상 이 툴을 먼저 호출하세요. 다른 모든 Instagram 툴은 여기서 반환된 account_id를 받아요.

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

#### 파라미터

- `query` (string, 필수) — 해석할 브랜드/크리에이터 이름(한글/영문) 또는 Instagram 핸들. query_type=bio일 때는 프로필 bio에서 찾을 단어예요.
- `query_type` (enum, 선택, 기본값 "auto") — 무엇을 매칭할지 골라요. auto = 핸들과 표시 이름을 함께, username = 핸들만, full_name = 표시 이름만, bio = 프로필 bio 텍스트. 값: `auto`, `username`, `full_name`, `bio`.
- `brands_only` (boolean, 선택, 기본값 false) — 알려진 브랜드 계정으로 매치를 한정해요. 브랜드명을 해석할 때 권장해요.
- `limit` (integer, 선택, ≥ 1) — 반환할 최대 후보 수, 기본값 8. 50을 넘는 값은 50으로 잘려요.
- `region` (string, 선택, ≤ 8 chars) — KR, JP, US 같은 리전 코드(선택). 특정 국가를 요청받은 게 아니라면 비워 두세요 — 설정하면 해당 리전만 남기고 나머지는 버려요.

#### 응답

##### `Response`

- `found` (boolean) — 후보가 하나 이상 매치되면 true.
- `items` (object[]) — 후보 목록. 매치 품질, 그다음 팔로워 수 순으로 정렬돼요.

##### `items[]`

- `account_id` (uuid) — SOLARI account id — 다른 모든 Instagram 툴이 받는 값이에요.
- `username` (string) — Instagram 핸들.
- `full_name` (string) — 프로필 표시 이름.
- `biography` (string) — 프로필 bio 텍스트.
- `follower_count` (integer) — 스냅샷 시점의 팔로워 수.
- `region` (string) — 리전 코드.
- `is_verified` (boolean) — Instagram 인증 배지.
- `profile_pic_url` (string) — 프로필 사진 URL.

#### 예시

```console
$ solari instagram account search query=oliveyoung brands_only=true limit=5
```

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

```json
{
  "found": true,
  "items": [
    {
      "account_id": "018cab6d-1648-7071-9734-c47a2be2fd19",
      "username": "oliveyoung_official",
      "full_name": "올리브영 OLIVE YOUNG",
      "biography": "ALL LIVE YOUNG 🫒\nALL LIVE BETTER @olivebetter.official",
      "follower_count": 1199628,
      "region": "KR",
      "is_verified": true,
      "profile_pic_url": "https://dcr.bzine.co/instagram/users/oliveyoung_official/profile-picture"
    },
    {
      "account_id": "018dc63c-31b5-740f-bde0-2c00931385e1",
      "username": "oliveyoung_global",
      "full_name": "OLIVE YOUNG Global",
      "biography": "Korea's No.1 Health & Beauty Store\n✈️ FREE SHIPPING on orders over $60",
      "follower_count": 535949,
      "region": "KR",
      "is_verified": true,
      "profile_pic_url": "https://dcr.bzine.co/instagram/users/oliveyoung_global/profile-picture"
    },
    {
      "account_id": "018cabcf-e60e-70af-95eb-eff777ce5195",
      "username": "oliveyoung_magazine",
      "full_name": "올리브영 매거진",
      "biography": "내 일상과 가까운 뷰티 매거진",
      "follower_count": 142316,
      "region": "KR",
      "is_verified": false,
      "profile_pic_url": "https://dcr.bzine.co/instagram/users/oliveyoung_magazine/profile-picture"
    },
    "… 2 more"
  ]
}
```

#### MCP 호출로 쓰면

```json
{
  "name": "solari_instagram_account_search",
  "arguments": {
    "query": "oliveyoung",
    "brands_only": true,
    "limit": 5
  }
}
```

#### 주의사항

- 이름으로 찾는 모드에서는 query가 핸들이나 표시 이름에 실제로 나타나야 해요. 발음 기반 별칭이나 약어로는 해석되지 않아요 — 원래 표기로 다시 시도해 보세요.
- 브랜드명을 해석할 때는 brands_only=true를 설정하세요. 팬 계정과 밈 계정을 걸러내요.
- query_type=bio는 이름 대신 프로필 bio 텍스트를 검색해요. 계정이 스스로를 어떻게 소개하는지로 찾을 수 있어요 — "skincare", "협찬 문의", "コスメ". 한국어·일본어·중국어 bio는 부분 문자열로도 매칭되니, 검색어가 bio 안에서 독립된 단어일 필요는 없어요.
- bio 검색 대상은 SOLARI가 이미 추적 중인 계정이고, 열 곳 중 한 곳쯤은 bio 자체가 없어요. 전수 조사가 아니라 발견용으로 쓰세요.
- region은 결과를 해당 리전으로 좁히고 나머지 계정은 전부 버려요. 특정 국가를 요청받은 게 아니라면 비워 두세요.

#### 관련 도구

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

### solari instagram account similar

> 주어진 핸들과 관계 그래프가 겹치는 Instagram 계정을 찾아요.

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

관계 그래프 겹침을 기준으로 주어진 username과 유사한 Instagram 계정을 찾아요. UUID가 아니라 Instagram 핸들(@ 없이)을 받아요. 로그인한 SOLARI 계정이면 누구나 사용할 수 있어요.

**언제 쓰나** — "이 크리에이터랑 비슷한 계정이 또 누가 있나?" — 협업 이력이 아니라 그래프 인접성이에요.

**무엇이 돌아오나** — 시드 계정, 유사 계정들, 그리고 탐색 과정을 설명하는 진단 정보.

#### 파라미터

- `username` (string, 필수) — 유사 계정을 찾을 대상 Instagram 핸들. 앞의 @는 빼고 넣으세요.
- `limit` (integer, 선택, ≥ 1) — 반환할 유사 계정 수, 기본값 50. 100을 넘는 값은 100으로 잘려요.

#### 응답

##### `Response`

- `user_id` (uuid) — 시드 계정 id.
- `user` (object) — 시드 계정 프로필 요약.
- `params` (object) — 실제로 적용된 탐색 파라미터 (k, hops, max_rank_to_use).
- `results` (object[]) — 유사 계정, 점수 내림차순.
- `diagnostics` (object) — 사용된 이웃, 알고리즘, 빌드 시간 — 결과가 이상해 보일 때 유용해요.

##### `results[]`

- `user_id` (uuid) — 유사 계정의 account_id.
- `username` (string) — 핸들.
- `full_name / bio` (string) — 표시 이름과 bio 텍스트.
- `score` (number) — 그래프 겹침 점수. 이 응답 안에서만 비교 가능해요.
- `follower_count` (integer) — 팔로워 수.
- `region` (string) — 리전 코드.
- `has_collaborated` (boolean) — 이 계정이 시드와 광고 협업 이력이 있는지 여부.
- `last_collaboration_date` (date | null) — 가장 최근 협업 날짜.
- `recent_media` (object[]) — 최근 포스트 프리뷰.

#### 예시

```console
$ solari instagram account similar username=oliveyoung_official limit=8
```

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

```json
{
  "user_id": "018cab6d-1648-7071-9734-c47a2be2fd19",
  "user": {
    "user_id": "018cab6d-1648-7071-9734-c47a2be2fd19",
    "username": "oliveyoung_official",
    "full_name": "올리브영 OLIVE YOUNG",
    "profile_pic_url": "https://dcr.bzine.co/instagram/users/oliveyoung_official/profile-picture",
    "follower_count": 1199628,
    "region": "KR",
    "is_verified": null
  },
  "params": {
    "k": 8,
    "hops": 3,
    "max_rank_to_use": 25
  },
  "results": [
    {
      "user_id": "018cabd4-926b-7a58-b0cb-11dfc7c37006",
      "username": "gs25_official",
      "score": 0.1515,
      "profile_pic_url": "https://dcr.bzine.co/instagram/users/gs25_official/profile-picture",
      "follower_count": 1017802,
      "median_views": null,
      "full_name": "대한민국 대표 편의점 GS25",
      "bio": "더 재미있게 더 실속있게\n오늘 가장 최신의 트렌드를 만나는\n#25매거진 #재미있는GS25 #라이프스타일플랫폼",
      "region": "KR",
      "has_collaborated": false,
      "last_collaboration_date": null,
      "recent_media": [
        {
          "post_id": "01a062a3-a504-7fe5-b53f-7cd291ffceff",
          "media_type": "image",
          "source_url": "https://bzine.co/cdn-cgi/image/fit=scale-down,width=480/https://smr-images.bzine.co/users/018cabd4-926b-7a58-b0cb-11dfc7c37006/posts/01a062a3-a504-7fe5-b53f-7cd291ffceff/medias/01a062a3-a7f8-702c-994f-bd426afe5d74.jpg",
          "thumbnail_url": "https://bzine.co/cdn-cgi/image/fit=scale-down,width=480/https://smr-images.bzine.co/users/018cabd4-926b-7a58-b0cb-11dfc7c37006/posts/01a062a3-a504-7fe5-b53f-7cd291ffceff/medias/01a062a3-a7f8-702c-994f-bd426afe5d74.jpg",
          "slug": "Dcx-Nrij7IV",
          "media_url": "https://bzine.co/cdn-cgi/image/fit=scale-down,width=480/https://smr-images.bzine.co/users/018cabd4-926b-7a58-b0cb-11dfc7c37006/posts/01a062a3-a504-7fe5-b53f-7cd291ffceff/medias/01a062a3-a7f8-702c-994f-bd426afe5d74.jpg",
          "play_count": null,
          "posted_at": "2026-09-02T10:00:09+00:00"
        },
        "… 3 more"
      ],
      "collaborated_with": []
    },
    "… 7 more"
  ],
  "diagnostics": {
    "neighbors_used": 4930,
    "unique_terms": 25,
    "build_ms": 7664,
    "algorithm": "distance_weighted_jaccard",
    "max_rank_used": 25,
    "target_related_count": 25
  }
}
```

#### MCP 호출로 쓰면

```json
{
  "name": "solari_instagram_account_similar",
  "arguments": {
    "username": "oliveyoung_official",
    "limit": 8
  }
}
```

#### 주의사항

- 핸들만 받아요 — 여기서는 account_id UUID를 받지 않아요.
- 그래프 겹침이 아니라 브랜드 협업 기준의 유사도가 필요하면 brand top collaborators를 사용하세요.

#### 관련 도구

- [`solari_instagram_account_search`](https://solari.sh/docs/tools/instagram-account-search.md?lang=ko)
- [`solari_instagram_brand_top_collaborators`](https://solari.sh/docs/tools/instagram-brand-top-collaborators.md?lang=ko)

### solari instagram brand overview

> 브랜드 프로필과 광고 발자취를 나타내는 id 목록.

- **CLI**: `solari instagram brand overview`
- **MCP 도구**: `solari_instagram_brand_overview`
- **권한**: `solari:read` — 로그인한 SOLARI 계정이면 쓸 수 있어요.

브랜드의 프로필과 광고 협업 발자취를 반환해요: 그 브랜드를 타깃으로 광고 포스트를 만든 크리에이터 ID와 광고 포스트 ID 자체 (기본은 상위 20개 프리뷰에 전체 개수가 함께 실리며, full=true로 설정하면 각각 최대 100개까지 전체 목록을 받아요). 포스트 ID는 solari_instagram_content_batch에 넣어 내용을 채우세요. UUID가 아니라 브랜드의 Instagram 핸들(@ 없이)을 받아요. 로그인한 SOLARI 계정이면 누구나 사용할 수 있어요. 추적 중이 아닌 핸들이면 404를 반환해요.

**언제 쓰나** — 브랜드 분석의 출발점. 포스트 id는 content batch에 넣어 내용을 채우세요.

**무엇이 돌아오나** — 브랜드 프로필, 그리고 그 브랜드를 태그한 크리에이터와 포스트의 id.

#### 파라미터

- `username` (string, 필수) — 앞의 @를 뺀 브랜드 Instagram 핸들.
- `full` (boolean, 선택, 기본값 false) — 상위 20개 프리뷰 대신 전체 ID 목록을 반환해요.

#### 응답

##### `Response`

- `information` (object) — 브랜드 프로필: user_id, username, full_name, bio, follower_count.
- `all_influencers_id` (uuid[]) — 그 브랜드의 광고를 만든 크리에이터의 account_ids. 기본은 상위 20개.
- `all_influencers_count` (integer) — 잘리기 전 전체 크리에이터 수.
- `all_influencers_truncated` (boolean) — 목록이 프리뷰일 때 true.
- `all_campaign_posts_id` (uuid[]) — 광고 포스트 id. 기본은 상위 20개.
- `all_campaign_posts_count` (integer) — 잘리기 전 전체 포스트 수.
- `all_campaign_posts_truncated` (boolean) — 목록이 프리뷰일 때 true.

#### 예시

```console
$ solari instagram brand overview username=innisfreeofficial
```

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

```json
{
  "information": {
    "user_id": "018cabce-14cc-7544-8890-7811ec33ef74",
    "username": "innisfreeofficial",
    "full_name": "INNISFREE | 이니스프리",
    "bio": "NATURE MEETS KOREAN SKIN SCIENCE",
    "follower_count": 847619,
    "brand_id": null
  },
  "all_influencers_id": [
    "01935f3d-8188-727e-a0bb-09e54aadfdac",
    "018caf6e-abfd-73da-88ad-11a56c39358b",
    "019a0061-b1d4-7adb-8ea4-1c5572dca38c",
    "… 17 more"
  ],
  "all_campaign_ids": [],
  "all_campaign_posts_id": [
    "019f505f-f8be-7e88-ae08-6fba999950b1",
    "019f5060-3449-779e-a08b-d6d49add90cd",
    "019f4342-3357-7418-916c-da1c44468308",
    "… 17 more"
  ],
  "post_id_to_campaign_id": {},
  "all_influencers_count": 93,
  "all_influencers_truncated": true,
  "all_campaign_posts_count": 100,
  "all_campaign_posts_truncated": true
}
```

#### MCP 호출로 쓰면

```json
{
  "name": "solari_instagram_brand_overview",
  "arguments": {
    "username": "innisfreeofficial"
  }
}
```

#### 주의사항

- full=true는 전체 목록을 반환하지만 각각 100개에서 상한이 걸려요. 정확한 총계가 필요하면 id를 세지 말고 brand ad stats를 사용하세요.
- 핸들만 받아요 — 여기서는 account_id UUID를 받지 않아요.
- 추적 중이 아닌 핸들은 404를 반환해요.

#### 관련 도구

- [`solari_instagram_brand_ad_stats`](https://solari.sh/docs/tools/instagram-brand-ad-stats.md?lang=ko)
- [`solari_instagram_content_batch`](https://solari.sh/docs/tools/instagram-content-batch.md?lang=ko)
- [`solari_instagram_brand_ad_posts`](https://solari.sh/docs/tools/instagram-brand-ad-posts.md?lang=ko)

### solari instagram brand ad stats

> 브랜드 최근 기간의 정확한 광고 물량.

- **CLI**: `solari instagram brand ad stats`
- **MCP 도구**: `solari_instagram_brand_ad_stats`
- **권한**: `solari:read` — 로그인한 SOLARI 계정이면 쓸 수 있어요.

브랜드의 최근 기간에 대한 정확한 광고 포스트 수와 협업 크리에이터 수, 그리고 집계 범위가 제한된 재생 수 합계. solari_instagram_brand_overview의 ID 목록은 상한이 걸려 있으므로 정확한 광고 물량 수치가 필요하면 이 툴을 쓰세요. 행 단위 원본 포스트가 필요하면 solari_instagram_brand_ad_posts를 쓰세요. 브랜드의 Instagram 핸들을 받아요(@ 없이). 로그인한 모든 SOLARI 계정에서 사용할 수 있어요.

**언제 쓰나** — 숫자로 답하는 질문 — "이 브랜드는 광고를 몇 개 집행했나?". brand overview의 id 목록은 상한이 걸려 있으므로 개수를 세면 안 돼요.

**무엇이 돌아오나** — 광고 포스트 수, 협업 크리에이터 수, 그리고 집계 범위가 제한된 재생 수 합계.

#### 파라미터

- `username` (string, 필수) — 브랜드 Instagram 핸들. 앞의 @는 빼세요.

#### 응답

##### `Response`

- `total_ad_posts` (integer) — 해당 기간의 광고 포스트 수. 정확한 값이에요.
- `unique_creator_count` (integer) — 고유 협업 크리에이터 수.
- `total_play_count` (integer) — 재생 수 합계.
- `play_count_covered_posts` (integer) — 재생 수 합계가 실제로 포함하는 포스트 수. total_ad_posts보다 작으면 그 합계는 하한값이에요.
- `window_months` (integer) — 기간 길이(개월).

#### 예시

```console
$ solari instagram brand ad stats username=innisfreeofficial
```

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

```json
{
  "total_ad_posts": 405,
  "unique_creator_count": 360,
  "total_play_count": 27357941,
  "play_count_covered_posts": 405,
  "window_months": 3
}
```

#### MCP 호출로 쓰면

```json
{
  "name": "solari_instagram_brand_ad_stats",
  "arguments": {
    "username": "innisfreeofficial"
  }
}
```

#### 주의사항

- 핸들만 받아요.
- 원본 행이 필요하면 brand ad posts를 쓰세요.

#### 관련 도구

- [`solari_instagram_brand_ad_posts`](https://solari.sh/docs/tools/instagram-brand-ad-posts.md?lang=ko)
- [`solari_instagram_brand_overview`](https://solari.sh/docs/tools/instagram-brand-overview.md?lang=ko)

### solari instagram brand ad posts

> 브랜드를 대상으로 한 광고 포스트를 행 단위로. 각 행에 작성 크리에이터가 붙어요.

- **CLI**: `solari instagram brand ad posts`
- **MCP 도구**: `solari_instagram_brand_ad_posts`
- **권한**: `solari:read` — 로그인한 SOLARI 계정이면 쓸 수 있어요.

특정 브랜드를 대상으로 식별된 광고 포스트를 행 단위로 페이지네이션해 반환해요. 각 행에는 slug, caption, posted_at, 좋아요/댓글 수, 영상이면 play_count, 그리고 작성한 크리에이터의 username과 account_id가 채워져요. sort=recent는 전체 구간을 최신순으로 페이지네이션하며 total이 정확해요. sort=engagement는 제한된 최근 구간 안에서 순위를 매기고 그 구간 크기를 ranking_window로 알려줘요(non-null이면 정렬이 전체가 아니라 일부만 커버한다는 뜻이에요). months로 조회 기간을 넓혀요(기본값 3, 최대 24). solari_instagram_brand_ad_stats의 행 단위 짝이에요. 브랜드의 Instagram 핸들(@ 제외)을 받아요. 로그인된 SOLARI 계정이면 누구나 사용할 수 있어요. 추적 중이 아닌 핸들이면 404를 반환해요.

**언제 쓰나** — 브랜드의 광고 이력을 롤업이 아니라 원시 행 단위로 분석할 때.

**무엇이 돌아오나** — 광고 포스트. total의 의미는 sort에 따라 달라져요.

#### 파라미터

- `username` (string, 필수) — 앞의 @를 뺀 브랜드 Instagram 핸들.
- `sort` (enum, 선택, 기본값 "recent") — recent는 전체 구간을 페이지네이션하며 total이 정확하고, engagement는 ranking_window 안에서 순위를 매겨요. 값: `recent`, `engagement`.
- `months` (integer, 선택, ≥ 1) — 조회 기간(개월), 기본값 3. 24를 넘는 값은 24로 잘려요.
- `limit` (integer, 선택, ≥ 1) — 페이지당 포스트 수, 기본값 50. 200을 넘는 값은 200으로 잘려요.
- `offset` (integer, 선택, 기본값 0, ≥ 0) — 페이지네이션 offset, 기본값 0.

#### 응답

##### `Response`

- `items` (object[]) — 광고 포스트.
- `total` (integer) — sort=recent일 때 구간 전체의 정확한 개수.
- `has_more` (boolean) — 다음 페이지 존재 여부.
- `ranking_window` (integer | null) — engagement 랭킹이 실제로 살펴본 범위. non-null이면 정렬이 전체 구간이 아니라 일부만 커버한다는 뜻이에요.

##### `items[]`

- `id` (uuid) — 포스트 id.
- `slug` (string) — Instagram shortcode.
- `text` (string) — 캡션 텍스트.
- `posted_at` (timestamp) — 게시 시각(UTC).
- `username / user_id / account_id` (string) — 작성한 크리에이터. account_id가 현재 이름이고, user_id도 같은 값을 담아요.
- `like_count / comment_count / play_count` (integer) — 인게이지먼트 스냅샷.
- `media_type` (string) — 포스트 포맷.
- `media / media_url / thumbnail_url` (string) — 미디어 링크.
- `virtual_campaign` (object | null) — 캠페인 그룹. 해석된 경우에만.

#### 예시

```console
$ solari instagram brand ad posts username=innisfreeofficial limit=2
```

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

```json
{
  "items": [
    {
      "id": "01a062a0-2747-72eb-b20d-670cf30f2c96",
      "slug": "DcygG05GrA-",
      "text": "#광고 요즘 부쩍 신경 쓰이기 시작한 모공 고민을 직접 경험해보고 싶어 방문한 이니스프리 레티놀 시카 강의실 무빙 팝업💙\n\n업그레이드된 레티놀 시카 모공 흔적 앰플을 직접 테스트해볼 수 있을 뿐 아니라, 제품을 알아보고 체험할 수 있는 다양한 프로그램과 이벤트가 마련되어 있어 더욱 재미있게 둘러볼 수 있었어요.\n\n특히 오늘 방문했을 때는 정말 많은 분들이 찾아와서 놀랐는데요. 대기 줄이 길게 …",
      "posted_at": "2026-09-02T14:56:19Z",
      "virtual_campaign": null,
      "username": "_mini_mming",
      "user_id": "018caf92-e08a-78a2-b9c3-59f6f5740182",
      "profile_picture_url": null,
      "like_count": 384,
      "comment_count": 4,
      "thumbnail_url": null,
      "media_url": null,
      "media": [],
      "media_type": "post",
      "account_id": "018caf92-e08a-78a2-b9c3-59f6f5740182"
    },
    "… 1 more"
  ],
  "total": 405,
  "has_more": true,
  "ranking_window": null
}
```

#### MCP 호출로 쓰면

```json
{
  "name": "solari_instagram_brand_ad_posts",
  "arguments": {
    "username": "innisfreeofficial",
    "limit": 2
  }
}
```

#### 주의사항

- sort=recent는 전체 구간을 최신순으로 페이지네이션하며 total이 정확해요. sort=engagement는 제한된 최근 구간 안에서 순위를 매기고 그 크기를 ranking_window로 알려줘요.
- months의 기본값은 3이고 24에서 상한이 걸려요.
- 핸들만 받아요. 추적 중이 아닌 핸들은 404를 반환해요.

#### 관련 도구

- [`solari_instagram_brand_ad_stats`](https://solari.sh/docs/tools/instagram-brand-ad-stats.md?lang=ko)
- [`solari_instagram_account_ad_posts`](https://solari.sh/docs/tools/instagram-account-ad-posts.md?lang=ko)

### solari instagram brand top collaborators

> 브랜드 광고를 얼마나 자주 진행했는지로 순위를 매긴 크리에이터.

- **CLI**: `solari instagram brand top collaborators`
- **MCP 도구**: `solari_instagram_brand_top_collaborators`
- **권한**: `solari:read` — 로그인한 SOLARI 계정이면 쓸 수 있어요.

그 브랜드를 대상으로 확인된 광고 포스트를 작성한 크리에이터를 협업 횟수 순으로 정렬한 목록. 브랜드는 account_id(solari_instagram_account_search가 주는 SOLARI 계정 UUID) 또는 username(Instagram 핸들)으로 지정해요. 알 수 없는 값을 주면 not-found 에러가 나요. 앞을 내다보는 적합도 점수가 아니라 지나온 협업 이력이에요. 로그인한 모든 SOLARI 계정에서 사용할 수 있어요.

**언제 쓰나** — "이 브랜드는 누구와 일하는가?" 앞을 내다보는 적합도 점수가 아니라 지나온 이력이에요.

**무엇이 돌아오나** — 협업 횟수 순으로 정렬된 크리에이터.

#### 파라미터

- `account_id` (string, 선택, uuid, pattern ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$) — solari_instagram_account_search가 주는 브랜드 account_id(SOLARI 계정 UUID). 이 값 또는 username 중 하나를 주세요.
- `username` (string, 선택, ≤ 64 chars) — 브랜드 Instagram 핸들. 앞의 @는 있어도 없어도 돼요. account_id가 설정되면 무시돼요.
- `promotion` (enum, 선택, 기본값 "all") — 광고 포스트 promotion 필터: 전체 행, promotion=true 행, 또는 promotion=false 행. 값: `all`, `true_only`, `false_only`.
- `limit` (integer, 선택, ≥ 1) — 반환되는 크리에이터 최대 수, 기본값 20. 1000을 넘는 값은 1000으로 잘려요.
- `offset` (integer, 선택, 기본값 0, ≥ 0) — 페이지네이션 offset, 기본값 0.

#### 응답

##### `Response`

- `brand_id` (uuid) — 확인된 브랜드 account_id.
- `promotion_filter` (string) — 적용된 promotion 필터.
- `items` (object[]) — 크리에이터. 협업 횟수 내림차순.
- `total_count` (integer) — 필터에 맞는 크리에이터 수.

##### `items[]`

- `creator_id` (uuid) — 크리에이터 account_id — 다른 툴들이 받는 값.
- `username / full_name` (string) — 핸들과 표시 이름.
- `profile_pic_url` (string) — 프로필 사진.
- `follower_count` (integer) — 팔로워 수.
- `collaboration_count` (integer) — 이 브랜드와의 협업 포스트 수.

#### 예시

```console
$ solari instagram brand top collaborators username=innisfreeofficial limit=5
```

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

```json
{
  "brand_id": "018cabce-14cc-7544-8890-7811ec33ef74",
  "promotion_filter": "all",
  "items": [
    {
      "creator_id": "0195474c-8ee3-7690-a385-71b2913e31b5",
      "username": "donge_cos",
      "full_name": "💞동이💞",
      "profile_pic_url": "https://dcr.bzine.co/instagram/users/donge_cos/profile-picture",
      "follower_count": 83354,
      "collaboration_count": 31
    },
    {
      "creator_id": "018ecc75-55d8-70a7-a348-d370aa504ed9",
      "username": "beinny_motd",
      "full_name": "베이니 BEINNY",
      "profile_pic_url": "https://dcr.bzine.co/instagram/users/beinny_motd/profile-picture",
      "follower_count": 205754,
      "collaboration_count": 29
    },
    "… 3 more"
  ],
  "total_count": 2331
}
```

#### MCP 호출로 쓰면

```json
{
  "name": "solari_instagram_brand_top_collaborators",
  "arguments": {
    "username": "innisfreeofficial",
    "limit": 5
  }
}
```

#### 주의사항

- limit은 1000까지 올릴 수 있어요. 그 크리에이터들의 포스트를 채우려면 creator_ids를 100개씩 brand collaborator posts에 넣으세요.
- 크리에이터에서 출발하는 반대 방향 뷰는 account collabs예요.

#### 관련 도구

- [`solari_instagram_brand_collaborator_posts`](https://solari.sh/docs/tools/instagram-brand-collaborator-posts.md?lang=ko)
- [`solari_instagram_account_collabs`](https://solari.sh/docs/tools/instagram-account-collabs.md?lang=ko)

### solari instagram brand collaborator posts

> 브랜드 하나와 최대 100명의 크리에이터를 한 번의 호출로 채워요.

- **CLI**: `solari instagram brand collaborator posts`
- **MCP 도구**: `solari_instagram_brand_collaborator_posts`
- **권한**: `solari:read` — 로그인한 SOLARI 계정이면 쓸 수 있어요.

브랜드 하나와 최대 100개의 크리에이터 account_ids에 대해, 각 크리에이터가 그 브랜드를 타깃으로 작성한 광고 포스트를 반환해요 — 크리에이터별로 post_count, reels_count, images_count, follower_count, 그리고 포스트 자체(slug, 캡션, posted_at, like/comment 수) — 총 인게이지먼트 순으로 정렬돼요. 전체 기간 이력을 다루며, 크리에이터마다 한 번씩 호출하는 대신 한 번의 호출로 끝내요. 크리에이터 account_id는 solari_instagram_brand_top_collaborators나 solari_instagram_brand_overview에서 얻어요. 브랜드는 account_id (SOLARI 계정 UUID) 또는 username (Instagram 핸들)으로 지정하며, 알 수 없는 참조는 not-found 에러를 반환해요. 로그인한 SOLARI 계정이면 누구나 사용할 수 있어요.

**언제 쓰나** — 크리에이터마다 한 번씩 호출하는 방식을 대체할 때. 최근 구간이 아니라 전체 기간 이력을 다뤄요.

**무엇이 돌아오나** — 크리에이터별 집계와 포스트 자체, 총 인게이지먼트 순 정렬.

#### 파라미터

- `account_id` (string, 선택, uuid, pattern ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$) — 브랜드 account_id (SOLARI 계정 UUID). 이 값 또는 username을 넘기세요.
- `username` (string, 선택, ≤ 64 chars) — 브랜드 Instagram 핸들. 앞의 @는 있어도 없어도 돼요. account_id가 지정되면 무시돼요.
- `account_ids` (uuid[], 필수, 1–100 items, uuid) — 내용을 채울 크리에이터 account_ids (SOLARI 계정 UUID). 호출당 최대 100개.

#### 응답

##### `Response`

- `(top level)` (object[]) — 크리에이터 배열 — 이 응답에는 envelope 객체가 없어요.

##### `[]`

- `user_id` (uuid) — 크리에이터 account_id.
- `username / full_name` (string) — 핸들과 표시 이름.
- `follower_count` (integer) — 팔로워 수.
- `post_count` (integer) — 이 브랜드를 타깃으로 한 포스트 수.
- `reels_count / images_count` (integer) — 포맷별 분해.
- `posts` (object[]) — 포스트 목록: id, slug, text, posted_at, like_count, comment_count, play_count.
- `like_count_avg / comment_count_avg` (number | null) — 평균 인게이지먼트, 계산된 경우에 한해.

#### 예시

```console
$ solari instagram brand collaborator posts username=innisfreeofficial account_ids='["0195474c-8ee3-7690-a385-71b2913e31b5","018ecc75-55d8-70a7-a348-d370aa504ed9"]'
```

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

```json
[
  {
    "user_id": "018ecc75-55d8-70a7-a348-d370aa504ed9",
    "username": "beinny_motd",
    "full_name": "베이니 BEINNY",
    "post_count": 29,
    "follower_count": 205754,
    "reels_count": 1,
    "images_count": 28,
    "posts": [
      {
        "id": "019c98bc-a666-717d-a5fe-ea96f1345042",
        "slug": "ByVKkIbnQ8S",
        "text": "#이니스프리 에서 새롭게 출시된 #구름블러틴트 ☁️💓\n비비드 코튼 잉크 블러버젼이에용\n.\n요즘 이런 블러틴트류 많이 출시돼서 넘 행복해요🥺💛\n이니스프리 블러틴트는 보송보송한 마무리지만 꽤 촉촉하고 가볍게 발리더라구요! 발림성 넘 좋았어요✨\n총 8가지 컬러인데 그중 제 맘에 드는 4가지 컬러는 입술에 발색해서 보여드려용 :) 특히 로즈+핑크 섞인듯한 2호 #로제핑크 완전 추천👍🏻✨\n가격은 9, …",
        "posted_at": "2019-06-05T14:02:19Z",
        "virtual_campaign": null,
        "like_count": 2399,
        "comment_count": 20,
        "play_count": null,
        "username": "beinny_motd",
        "user_id": "018ecc75-55d8-70a7-a348-d370aa504ed9"
      },
      "… 10 more"
    ],
    "like_count_avg": null,
    "comment_count_avg": null,
    "synced_at": null
  },
  "… 1 more"
]
```

#### MCP 호출로 쓰면

```json
{
  "name": "solari_instagram_brand_collaborator_posts",
  "arguments": {
    "username": "innisfreeofficial",
    "account_ids": [
      "0195474c-8ee3-7690-a385-71b2913e31b5",
      "018ecc75-55d8-70a7-a348-d370aa504ed9"
    ]
  }
}
```

#### 주의사항

- account_ids는 JSON 배열 또는 쉼표로 구분된 목록을 받아요. 호출당 최대 100개.
- 월 단위 구간 없이 전체 이력을 다뤄요.

#### 관련 도구

- [`solari_instagram_brand_top_collaborators`](https://solari.sh/docs/tools/instagram-brand-top-collaborators.md?lang=ko)
- [`solari_instagram_brand_overview`](https://solari.sh/docs/tools/instagram-brand-overview.md?lang=ko)

### solari instagram brand lookalike content

> 브랜드의 성과 최상위 광고처럼 보이고 읽히는 포스트.

- **CLI**: `solari instagram brand lookalike content`
- **MCP 도구**: `solari_instagram_brand_lookalike_content`
- **권한**: `solari:read` — 로그인한 SOLARI 계정이면 쓸 수 있어요.

브랜드의 성과 상위 광고 포스트와 시각적·의미적으로 비슷한 Instagram 포스트. 브랜드 자신의 광고 포스트를 시드로 삼은 벡터 이웃 검색으로 찾아요. 브랜드는 account_id(solari_instagram_account_search가 주는 SOLARI 계정 UUID) 또는 username(Instagram 핸들)으로 지정해요. 알 수 없는 값을 주면 not-found 에러가 나요. 로그인한 모든 SOLARI 계정에서 사용할 수 있어요.

**언제 쓰나** — 레퍼런스를 찾을 때. 브랜드 자신의 상위 광고를 시드로 삼은 벡터 이웃 검색.

**무엇이 돌아오나** — 유사(lookalike) 포스트와, 검색의 시드가 된 브랜드 자신의 광고 포스트.

#### 파라미터

- `account_id` (string, 선택, uuid, pattern ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$) — 유사(lookalike) 검색의 시드가 되는 광고 포스트를 가진 브랜드의 account_id(SOLARI 계정 UUID). 이 값 또는 username 중 하나를 주세요.
- `username` (string, 선택, ≤ 64 chars) — 브랜드 Instagram 핸들. 앞의 @는 있어도 없어도 돼요. account_id가 설정되면 무시돼요.
- `limit` (integer, 선택, ≥ 1) — 반환되는 유사(lookalike) 포스트 최대 개수, 기본값 30. 50을 넘는 값은 50으로 잘려요.
- `region` (string, 선택, 기본값 "KR") — 검색 범위를 정하는 리전 코드. KR, JP, US 등.

#### 응답

##### `Response`

- `items` (object[]) — 유사(lookalike) 포스트.
- `basis` (object[]) — 시드로 쓰인 브랜드 자신의 광고 포스트.
- `region` (string) — 검색 범위로 적용된 리전.

##### `items[] · basis[]`

- `post_id` (uuid) — SOLARI 포스트 id. 다른 콘텐츠 툴에 그대로 넣으면 돼요.
- `slug` (string) — Instagram shortcode — 공개 URL에서 /p/ 또는 /reel/ 뒤에 오는 구간.
- `author_id` (uuid) — 작성 계정의 account_id.
- `username` (string) — 작성자 핸들.
- `full_name` (string | null) — 프로필 표시 이름.
- `profile_pic_url` (string | null) — 프로필 사진 URL.
- `follower_count` (integer | null) — 스냅샷 시점의 작성자 팔로워 수.
- `region` (string | null) — 작성자에게 지정된 리전 코드.
- `posted_at` (timestamp) — 게시 시각(UTC).
- `media_type` (string) — image, video, 또는 carousel.
- `play_count` (integer | null) — 영상 재생 수. image 포스트에서는 null.
- `like_count` (integer | null) — 스냅샷 시점의 좋아요 수.
- `text` (string | null) — 캡션 텍스트.
- `media_url` (string) — 원본 미디어 URL.
- `thumbnail_url` (string) — 썸네일 URL.
- `score` (number | null) — 피드 랭킹 점수. 한 응답 안에서만 비교할 수 있어요.
- `efficiency_score` (number | null) — 작성자 팔로워 수 대비 성과.
- `est_percentile` (number | null) — 리전 내 추정 백분위, 0–1.
- `total_views_3m` (integer | null) — 최근 3개월 동안 작성자의 누적 조회 수.
- `median_views_3m` (integer | null) — 최근 3개월 동안 작성자의 조회 수 중앙값.
- `recent_collab_brands` (string[]) — 작성자가 최근 협업한 브랜드.
- `item_type` (string) — 항목 종류 태그. 콘텐츠 피드에서는 post.
- `content_source` (string | null) — 이 항목을 노출시킨 파이프라인.
- `is_saved` (boolean | null) — 이 항목이 SOLARI 앱에 저장되어 있는지 여부.
- `updated_at` (timestamp | null) — 지표 스냅샷이 마지막으로 갱신된 시각.

#### 예시

```console
$ solari instagram brand lookalike content username=innisfreeofficial limit=3
```

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

```json
{
  "items": [
    {
      "item_type": "content",
      "post_id": "019ecb92-a677-7421-8ed6-752efe3d99d0",
      "author_id": "0196cb39-870a-7a76-9773-0b95789c877d",
      "username": "boo_rookie",
      "full_name": null,
      "profile_pic_url": null,
      "follower_count": null,
      "region": null,
      "posted_at": "2026-06-11T08:14:37Z",
      "media_type": "video",
      "play_count": 427258,
      "like_count": null,
      "score": null,
      "efficiency_score": null,
      "est_percentile": null,
      "updated_at": null,
      "media_url": "https://smr-images-b.bzine.co/users/0196cb39-870a-7a76-9773-0b95789c877d/posts/019ecb92-a677-7421-8ed6-752efe3d99d0/medias/019ecb92-a92e-7fc8-b644-69b930f2e197.mp4",
      "thumbnail_url": "https://bzine.co/cdn-cgi/media/width=480,mode=frame,time=100ms/https://smr-images-a.bzine.co/users/0196cb39-870a-7a76-9773-0b95789c877d/posts/019ecb92-a677-7421-8ed6-752efe3d99d0/medias/019ecb92-a92e-7fc8-b644-69b930f2e1 …",
      "slug": "DZcD8KXxKwd",
      "text": null,
      "brand_match_score": null,
      "recent_collab_brands": [],
      "total_views_3m": null,
      "median_views_3m": null,
      "is_saved": null,
      "content_source": "lookalikes_by_top_ad"
    },
    "… 2 more"
  ],
  "basis": [
    {
      "item_type": "content",
      "post_id": "01a04c73-3ec3-7873-9e84-334c644abfe4",
      "author_id": "0196c474-c96e-71ad-aceb-61af051c81d3",
      "username": "hwitto_",
      "full_name": null,
      "profile_pic_url": null,
      "follower_count": null,
      "region": null,
      "posted_at": null,
      "media_type": "video",
      "play_count": 155729,
      "like_count": null,
      "score": null,
      "efficiency_score": null,
      "est_percentile": null,
      "updated_at": null,
      "media_url": "https://smr-images-a.bzine.co/users/0196c474-c96e-71ad-aceb-61af051c81d3/posts/01a04c73-3ec3-7873-9e84-334c644abfe4/medias/01a04c73-4036-7a83-a52a-97b0058e6732.mp4",
      "thumbnail_url": "https://bzine.co/cdn-cgi/media/width=480,mode=frame,time=100ms/https://smr-images.bzine.co/users/0196c474-c96e-71ad-aceb-61af051c81d3/posts/01a04c73-3ec3-7873-9e84-334c644abfe4/medias/01a04c73-4036-7a83-a52a-97b0058e6732 …",
      "slug": "DckGrZ6vZiU",
      "text": null,
      "brand_match_score": null,
      "recent_collab_brands": [],
      "total_views_3m": null,
      "median_views_3m": null,
      "is_saved": null,
      "content_source": "lookalikes_by_top_ad"
    },
    "… 5 more"
  ],
  "region": "KR"
}
```

#### MCP 호출로 쓰면

```json
{
  "name": "solari_instagram_brand_lookalike_content",
  "arguments": {
    "username": "innisfreeofficial",
    "limit": 3
  }
}
```

#### 주의사항

- limit은 50에서 상한이 걸려요.
- basis가 비어 있으면 아직 시드로 쓸 광고 포스트가 그 브랜드에 없다는 뜻이에요.

#### 관련 도구

- [`solari_instagram_brand_ad_posts`](https://solari.sh/docs/tools/instagram-brand-ad-posts.md?lang=ko)
- [`solari_instagram_content_search`](https://solari.sh/docs/tools/instagram-content-search.md?lang=ko)

### solari instagram account profile

> SOLARI가 Instagram 계정 하나에 대해 아는 모든 것, 성과 지표 포함.

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

추적 중인 Instagram 계정 하나의 전체 SOLARI 프로필: username, full name, bio, follower/following/post 수, verified 플래그, 추론된 account_type, 조회 수 지표(조회 수 중앙값과 총합, 광고 수, 전월 대비 성장률, 리전 백분위), 그리고 최근 포스트와 최근 광고 협업의 임베디드 프리뷰. 계정은 account_id (solari_instagram_account_search에서 얻은 UUID) 또는 username (Instagram 핸들)으로 지정해요. 아직 추적 중이 아닌 username은 첫 요청 때 실시간으로 수집돼요(수 초 소요. 응답에 fetched_on_demand=true가 실리며, 조회 수 지표와 협업 이력은 아직 만들어지지 않은 상태예요). 그 뒤에 나오는 not-found 에러는 해당 핸들이 Instagram에 존재하지 않는다는 뜻이에요. 로그인한 SOLARI 계정이면 누구나 사용할 수 있어요.

**언제 쓰나** — 계정 심층 분석의 첫 호출. 최근 포스트와 최근 협업이 함께 실려 오므로 후속 호출을 아낄 수 있어요.

**무엇이 돌아오나** — 프로필 필드, 조회 수 기반 성과 지표, 임베디드 프리뷰.

#### 파라미터

- `account_id` (string, 선택, uuid, pattern ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$) — 계정의 account_id (SOLARI 계정 UUID). 이 값 또는 username을 넘기세요.
- `username` (string, 선택, ≤ 64 chars) — Instagram 핸들. 앞의 @는 있어도 없어도 돼요. account_id가 지정되면 무시돼요.

#### 응답

##### `Response`

- `user_id` (uuid) — account_id.
- `username / full_name / bio` (string) — 핸들, 표시 이름, bio 텍스트.
- `follower_count / following_count` (integer) — 팔로워 수와 팔로잉 수.
- `total_post_count` (integer) — 누적 포스트 수.
- `post_count_3m` (integer) — 최근 3개월간 포스트 수.
- `is_verified` (boolean) — 인증 배지.
- `account_type` (string) — SOLARI가 추론한 계정 성격 (brand, creator, …).
- `median_views_cur` (integer) — 현재 윈도우의 조회 수 중앙값.
- `total_views_cur` (integer) — 현재 윈도우의 총 조회 수.
- `ad_count_cur` (integer) — 현재 윈도우의 광고 포스트 수.
- `median_views_growth_m1` (number) — 전월 대비 조회 수 중앙값 변화, 비율로 표시.
- `total_views_growth_m1` (number) — 전월 대비 총 조회 수 변화, 비율로 표시.
- `median_views_region_pct` (number) — 리전 내 조회 수 중앙값 백분위, 0–1.
- `total_views_region_pct` (number) — 리전 내 총 조회 수 백분위, 0–1.
- `recent_posts` (object[]) — 최근 포스트 프리뷰.
- `recent_collabs` (object[]) — 최근 광고 협업 프리뷰.
- `fetched_on_demand` (boolean) — 이 요청이 해당 계정을 처음 수집한 경우 true.

#### 예시

```console
$ solari instagram account profile username=innisfreeofficial
```

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

```json
{
  "user_id": "018cabce-14cc-7544-8890-7811ec33ef74",
  "username": "innisfreeofficial",
  "full_name": "INNISFREE | 이니스프리",
  "bio": "NATURE MEETS KOREAN SKIN SCIENCE",
  "profile_pic_url": "https://dcr.bzine.co/instagram/users/innisfreeofficial/profile-picture",
  "follower_count": 847619,
  "total_post_count": 4131,
  "post_count_3m": 100,
  "following_count": 17,
  "is_verified": true,
  "median_views_cur": 12409,
  "ad_count_cur": 0,
  "total_views_cur": 685771,
  "median_views_growth_m1": 0.04956440835659308,
  "total_views_growth_m1": 0.39407867587418205,
  "median_views_region_pct": 0.1736183168163037,
  "total_views_region_pct": 0.1457900950723917,
  "recent_posts": [
    {
      "post_id": "01a06275-d974-7fda-98ee-dd3ee15b4dcf",
      "slug": "DcyMAmUh6FZ",
      "media_type": "video",
      "media_url": "https://smr-images-b.bzine.co/users/018cabce-14cc-7544-8890-7811ec33ef74/posts/01a06275-d974-7fda-98ee-dd3ee15b4dcf/medias/01a06275-db2b-77f7-a020-b4beb744771f.mp4",
      "thumbnail_url": "https://bzine.co/cdn-cgi/media/width=480,mode=frame,time=0ms/https://smr-images.bzine.co/users/018cabce-14cc-7544-8890-7811ec33ef74/posts/01a06275-d974-7fda-98ee-dd3ee15b4dcf/medias/01a06275-db2b-77f7-a020-b4beb744771f.m …",
      "text": "Deeply hydrated skin—NO OFF HOURS. 💚\nwherever the day takes MINGYU (@min9yu_k)—his hydration stays SUPERCHARGED ⚡️\n\nGreen Tea Ceramide Milk: Lightweight milky toner that won‘t clog your pores\nGreen Tea Ceramide Mist: Tou …",
      "play_count": 22467,
      "like_count": 3224,
      "video_media_count": 0,
      "media_count": 1
    },
    "… 5 more"
  ],
  "recent_collabs": [],
  "account_type": "brand",
  "fetched_on_demand": false
}
```

#### MCP 호출로 쓰면

```json
{
  "name": "solari_instagram_account_profile",
  "arguments": {
    "username": "innisfreeofficial"
  }
}
```

#### 주의사항

- 추적 중이 아닌 핸들은 첫 요청 때 실시간으로 수집돼요. 수 초가 걸리며, fetched_on_demand=true로 표시되고 이 상태에서는 조회 수 지표와 협업 이력이 아직 만들어지지 않아요.
- 그 뒤에 나오는 not-found 에러는 해당 핸들이 Instagram에 존재하지 않는다는 뜻이에요.
- 지표는 스냅샷이라 실시간 수치보다 늦을 수 있어요.

#### 관련 도구

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

### solari instagram account posts

> 계정 하나의 포스트를 최신순으로 페이지 단위로 훑어요.

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

추적 중인 Instagram 계정 하나의 포스트를 최신순으로, 페이지네이션과 필터와 함께 반환해요. 계정은 account_id(solari_instagram_account_search가 주는 UUID) 또는 username(Instagram 핸들)으로 지정해요. 각 항목에는 post_id(SOLARI 포스트 UUID), slug와 url(공개 Instagram 퍼머링크), post_type(reel, video, photo, carousel), posted_at, 캡션 텍스트, like/comment/play 카운트, media_count, is_paid_partnership, medias 배열(포스트의 모든 미디어를 캐러셀 순서로 담고, 각각 media_type, media/thumbnail URL, video_duration, 그리고 tags — 그 미디어에 태그된 계정과 해시태그를 가지며, 태그된 계정이 추적 중이면 account_id도 함께 담겨요), 대표 thumbnail_url이 담겨요. 응답에는 found, account_id, username, total, has_more, items가 실려요. limit과 offset으로 페이지를 넘기고, since/until(UTC 날짜, 양끝 포함)과 post_type으로 범위를 좁혀요. 아직 추적 중이 아닌 username은 첫 요청 때 실시간으로 수집되며(수 초 소요), fetched_on_demand=true는 지금까지 가장 최근 포스트만 사용할 수 있다는 표시예요. found=false는 그 핸들이 Instagram에 존재하지 않는다는 뜻이에요. 로그인한 모든 SOLARI 계정에서 사용할 수 있어요.

**언제 쓰나** — 프로필 미리보기보다 더 깊이 파고들 때, 또는 기간과 포맷으로 좁힌 원본 행을 가져올 때.

**무엇이 돌아오나** — 각 포스트의 모든 미디어를 포함한 포스트. 미디어에 태그된 계정과 해시태그도 함께.

#### 파라미터

- `account_id` (string, 선택, uuid, pattern ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$) — 계정의 account_id(SOLARI 계정 UUID). 이 값 또는 username 중 하나를 주세요.
- `username` (string, 선택, ≤ 64 chars) — Instagram 핸들. 앞의 @는 있어도 없어도 돼요. account_id가 설정되면 무시돼요.
- `limit` (integer, 선택, ≥ 1) — 페이지당 포스트 수, 기본값 12. 200을 넘는 값은 200으로 잘려요.
- `offset` (integer, 선택, 기본값 0, ≥ 0) — 페이지네이션 offset, 기본값 0.
- `since` (string, 선택, pattern ^\d{4}-\d{2}-\d{2}$) — 이 UTC 날짜 이후의 포스트만. YYYY-MM-DD, 해당일 포함.
- `until` (string, 선택, pattern ^\d{4}-\d{2}-\d{2}$) — 이 UTC 날짜 이전의 포스트만. YYYY-MM-DD, 해당일 포함.
- `post_type` (enum, 선택) — 이 포맷의 포스트만. reel은 숏폼 단일 영상, video는 reel이 아닌 영상이에요. 값: `reel`, `video`, `photo`, `carousel`.

#### 응답

##### `Response`

- `found` (boolean) — false면 그 핸들이 Instagram에 존재하지 않는다는 뜻이에요.
- `account_id / username` (string) — 확인된 계정.
- `total` (integer) — 필터에 맞는 포스트 수.
- `has_more` (boolean) — 다음 페이지가 있는지 여부.
- `items` (object[]) — 포스트. 최신순.
- `fetched_on_demand` (boolean) — 지금까지 가장 최근 포스트만 사용할 수 있으면 true.

##### `items[]`

- `post_id` (uuid) — SOLARI 포스트 id.
- `slug` (string) — Instagram shortcode.
- `url` (string) — 공개 퍼머링크.
- `post_type` (string) — reel, video, photo, 또는 carousel.
- `posted_at` (timestamp) — 게시 시각(UTC).
- `text` (string) — 캡션 텍스트.
- `like_count / comment_count / play_count` (integer) — 인게이지먼트 스냅샷.
- `media_count` (integer) — 포스트에 담긴 미디어 개수.
- `is_paid_partnership` (boolean | null) — Instagram 자체의 유료 파트너십 라벨.
- `medias` (object[]) — 캐러셀 순서의 모든 미디어 — 각각 media_type, media/thumbnail URL, video_duration을 가져요.
- `medias[].tags` (object[]) — 그 미디어에 태그된 계정과 해시태그. 태그된 계정을 SOLARI가 추적 중이면 account_id가 함께 담겨요.
- `thumbnail_url` (string) — 대표 썸네일.

#### 예시

```console
$ solari instagram account posts username=innisfreeofficial limit=2
```

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

```json
{
  "found": true,
  "account_id": "018cabce-14cc-7544-8890-7811ec33ef74",
  "username": "innisfreeofficial",
  "fetched_on_demand": false,
  "total": 4196,
  "has_more": true,
  "items": [
    {
      "post_id": "01a06275-d974-7fda-98ee-dd3ee15b4dcf",
      "slug": "DcyMAmUh6FZ",
      "url": "https://www.instagram.com/p/DcyMAmUh6FZ/",
      "post_type": "reel",
      "posted_at": "2026-09-02T12:00:06+00:00",
      "text": "Deeply hydrated skin—NO OFF HOURS. 💚\nwherever the day takes MINGYU (@min9yu_k)—his hydration stays SUPERCHARGED ⚡️\n\nGreen Tea Ceramide Milk: Lightweight milky toner that won‘t clog your pores\nGreen Tea Ceramide Mist: Tou …",
      "like_count": 3224,
      "comment_count": 57,
      "play_count": 22467,
      "media_count": 1,
      "is_paid_partnership": false,
      "medias": [
        {
          "media_type": "video",
          "media_url": "https://smr-images-b.bzine.co/users/018cabce-14cc-7544-8890-7811ec33ef74/posts/01a06275-d974-7fda-98ee-dd3ee15b4dcf/medias/01a06275-db2b-77f7-a020-b4beb744771f.mp4",
          "thumbnail_url": "https://bzine.co/cdn-cgi/media/width=480,mode=frame,time=0ms/https://smr-images.bzine.co/users/018cabce-14cc-7544-8890-7811ec33ef74/posts/01a06275-d974-7fda-98ee-dd3ee15b4dcf/medias/01a06275-db2b-77f7-a020-b4beb744771f.m …",
          "video_duration": 23.868000030517578,
          "tags": []
        }
      ],
      "thumbnail_url": "https://bzine.co/cdn-cgi/media/width=480,mode=frame,time=0ms/https://smr-images.bzine.co/users/018cabce-14cc-7544-8890-7811ec33ef74/posts/01a06275-d974-7fda-98ee-dd3ee15b4dcf/medias/01a06275-db2b-77f7-a020-b4beb744771f.m …"
    },
    "… 1 more"
  ]
}
```

#### MCP 호출로 쓰면

```json
{
  "name": "solari_instagram_account_posts",
  "arguments": {
    "username": "innisfreeofficial",
    "limit": 2
  }
}
```

#### 주의사항

- 페이지당 최대 200개. 대량으로 가져올 때는 큰 페이지를 메모리에 올리기보다 --ndjson으로 파일에 이어 쓰는 편이 나아요.
- since와 until은 UTC 날짜이며 양끝을 포함해요.
- post_type=reel은 숏폼 단일 영상, video는 reel이 아닌 영상이에요.

#### 관련 도구

- [`solari_instagram_account_profile`](https://solari.sh/docs/tools/instagram-account-profile.md?lang=ko)
- [`solari_instagram_content_detail`](https://solari.sh/docs/tools/instagram-content-detail.md?lang=ko)
- [`solari_tiktok_account_posts`](https://solari.sh/docs/tools/tiktok-account-posts.md?lang=ko)

### solari instagram account collabs

> 크리에이터가 어느 브랜드의 광고를 진행했는지, 브랜드별로 묶어서.

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

크리에이터 한 명이 지정한 개월 수 안에 진행한 최근 광고 협업. 각 항목은 대상 브랜드(target_account_id, target_username)와 collab_count, last_posted_at, 그리고 샘플 협업 포스트로 이루어져요. items, has_more, total을 반환하며 limit/offset으로 페이지를 넘겨요. 크리에이터는 account_id(SOLARI 계정 UUID) 또는 username(Instagram 핸들)으로 지정해요. 알 수 없는 값을 주면 not-found 에러가 나요. 브랜드에서 출발하는 반대 방향 뷰는 solari_instagram_brand_top_collaborators예요. 로그인한 모든 SOLARI 계정에서 사용할 수 있어요.

**언제 쓰나** — "이 크리에이터는 누구와 일하는가?" 브랜드에서 출발하는 반대 방향 뷰는 brand top collaborators예요.

**무엇이 돌아오나** — 대상 브랜드마다 한 행. 각 행은 샘플 협업 포스트를 담아요.

#### 파라미터

- `account_id` (string, 선택, uuid, pattern ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$) — 크리에이터의 account_id(SOLARI 계정 UUID). 이 값 또는 username 중 하나를 주세요.
- `username` (string, 선택, ≤ 64 chars) — Instagram 핸들. 앞의 @는 있어도 없어도 돼요. account_id가 설정되면 무시돼요.
- `months` (integer, 선택, ≥ 1) — 조회 기간(개월), 기본값 3. 12를 넘는 값은 12로 잘려요.
- `limit` (integer, 선택, ≥ 1) — 페이지당 최대 항목 수, 기본값 5. 200을 넘는 값은 200으로 잘려요.
- `offset` (integer, 선택, 기본값 0, ≥ 0) — 페이지네이션 offset, 기본값 0.

#### 응답

##### `Response`

- `total` (integer) — 필터에 맞는 전체 행 수.
- `has_more` (boolean) — offset + limit 뒤에도 행이 있는지 여부.
- `items` (object[]) — 협업 요약. 대상 브랜드마다 하나.

##### `items[]`

- `target_account_id` (uuid) — 대상 브랜드의 account_id.
- `target_username` (string) — 대상 브랜드 핸들.
- `collab_count` (integer) — 이 브랜드와의 협업 포스트 수.
- `last_posted_at` (timestamp) — 가장 최근 협업.
- `post_id / slug` (string) — 샘플 포스트의 식별자.
- `text` (string) — 샘플 포스트 캡션.
- `like_count / play_count` (integer) — 샘플 포스트 인게이지먼트.
- `media_type` (string) — 샘플 포스트 포맷.
- `thumbnail_url / media_url` (string) — 샘플 포스트 미디어.
- `bio` (string) — 대상 브랜드 bio.

#### 예시

```console
$ solari instagram account collabs username=beinny_motd months=6 limit=3
```

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

```json
{
  "items": [
    {
      "post_id": "01a05575-7c9b-7232-8519-4a38fa061389",
      "target_user_id": "018cab85-8ef8-7dc9-ab0a-7044d463f65e",
      "target_username": "dasique_official",
      "collab_count": 2,
      "last_posted_at": "2026-08-30T05:08:56+00:00",
      "slug": "DcpugJ2kzv8",
      "text": "#광고 무겁지 않은 가을 데일리 팔레트 로즈밀크티 . .🫖🤎\n차분하고 미지근한 로즈핑크 팔레트인데\n부드러운 밀크티 무드라서 분위기가 넘 예뻐요..🥺\n\n데이지크에서 올리브영 X 산리오 콜라보\n시티팝 에디션으로 미니섀도우팔레트 4종이 출시되는데\n그 중 자주 추천드렸던 로즈밀크티, 밀크라떼가 있더라구요 !\n\nNEW 컬러 피치레코드, 모브카세트도 출시되어요🤍\n도시의 아침과 저녁 무드를 담은 데일리한 …",
      "play_count": 0,
      "media_type": "8",
      "like_count": 878,
      "video_media_count": 0,
      "media_count": 15,
      "bio": "🫒올영세일 08.30 – 09.05\nUP TO 37% SALE\n올리브영X산리오,\n🌠데이지크 🆕 미니 섀도우",
      "thumbnail_url": "https://bzine.co/cdn-cgi/image/fit=scale-down,width=480/https://smr-images-c.bzine.co/users/018ecc75-55d8-70a7-a348-d370aa504ed9/posts/01a05575-7c9b-7232-8519-4a38fa061389/medias/01a05575-7dd3-779e-9050-a6cb59578cb9.jpg",
      "media_url": "https://bzine.co/cdn-cgi/image/fit=scale-down,width=480/https://smr-images-c.bzine.co/users/018ecc75-55d8-70a7-a348-d370aa504ed9/posts/01a05575-7c9b-7232-8519-4a38fa061389/medias/01a05575-7dd3-779e-9050-a6cb59578cb9.jpg",
      "target_account_id": "018cab85-8ef8-7dc9-ab0a-7044d463f65e"
    },
    "… 2 more"
  ],
  "has_more": true,
  "total": 7
}
```

#### MCP 호출로 쓰면

```json
{
  "name": "solari_instagram_account_collabs",
  "arguments": {
    "username": "beinny_motd",
    "months": 6,
    "limit": 3
  }
}
```

#### 주의사항

- target_user_id는 target_account_id와 같은 값의 예전 이름이에요. 새 코드는 target_account_id를 읽어야 해요.
- months의 기본값은 3이고 12에서 상한이 걸려요.
- 브랜드별 집계가 아니라 행 단위 이력이 필요하면 account ad posts를 쓰세요.

#### 관련 도구

- [`solari_instagram_account_ad_posts`](https://solari.sh/docs/tools/instagram-account-ad-posts.md?lang=ko)
- [`solari_instagram_brand_top_collaborators`](https://solari.sh/docs/tools/instagram-brand-top-collaborators.md?lang=ko)

### solari instagram account ad posts

> 크리에이터가 작성한 광고 포스트의 행 단위 목록, 각 행에 타깃 브랜드 포함.

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

크리에이터 한 명이 작성한, 식별된 광고 포스트의 행 단위 페이지네이션 목록. 최신순이며 각 행에 타깃 브랜드가 붙어요 — 포스트-브랜드 쌍마다 한 행이므로, 여러 브랜드를 태그한 포스트는 타깃마다 한 번씩 나타나요. 각 항목은 post_id, slug와 url, post_type, posted_at, 캡션 텍스트, like/comment/play 수, media_count, is_paid_partnership, target_account_id/target_username을 담아요. target (브랜드의 account_id 또는 Instagram 핸들)으로 브랜드 하나만 필터링해요. months로 조회 기간을 넓혀요 (기본값 3, 최대 24). 같은 이력을 브랜드별로 묶어 주는 solari_instagram_account_collabs의 행 단위 짝이에요. 크리에이터는 account_id (SOLARI 계정 UUID) 또는 username (Instagram 핸들)으로 지정하며, 알 수 없는 참조는 not-found 에러를 반환해요. 로그인한 SOLARI 계정이면 누구나 사용할 수 있어요.

**언제 쓰나** — 협업 이력을 원본 행 단위로 분석할 때. 여러 브랜드를 태그한 포스트는 타깃마다 한 번씩 나타나므로, 각 행은 포스트–브랜드 쌍이에요.

**무엇이 돌아오나** — 광고 포스트, 최신순.

#### 파라미터

- `account_id` (string, 선택, uuid, pattern ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$) — 크리에이터의 account_id (SOLARI 계정 UUID). 이 값 또는 username을 넘기세요.
- `username` (string, 선택, ≤ 64 chars) — Instagram 핸들. 앞의 @는 있어도 없어도 돼요. account_id가 지정되면 무시돼요.
- `months` (integer, 선택, ≥ 1) — 조회 기간(개월), 기본값 3. 24를 넘는 값은 24로 잘려요.
- `limit` (integer, 선택, ≥ 1) — 페이지당 항목 수, 기본값 50. 200을 넘는 값은 200으로 잘려요.
- `offset` (integer, 선택, 기본값 0, ≥ 0) — 페이지네이션 offset, 기본값 0.
- `target` (string, 선택, ≤ 64 chars) — 선택적 타깃 브랜드 필터: 브랜드의 account_id (SOLARI 계정 UUID) 또는 Instagram 핸들.

#### 응답

##### `Response`

- `account_id / username` (string) — 확정된 크리에이터.
- `months` (integer) — 적용된 조회 기간.
- `total` (integer) — 전체 행 수.
- `has_more` (boolean) — 다음 페이지가 있는지 여부.
- `items` (object[]) — 포스트–브랜드 쌍.

##### `items[]`

- `post_id / slug / url` (string) — 포스트 식별자와 공개 링크.
- `post_type` (string) — reel, video, photo, 또는 carousel.
- `posted_at` (timestamp) — 게시 시각 (UTC).
- `text` (string) — 캡션 텍스트.
- `like_count / comment_count / play_count` (integer) — 인게이지먼트 스냅샷.
- `media_count` (integer) — 미디어 개수.
- `is_paid_partnership` (boolean | null) — Instagram의 유료 광고 파트너십 라벨.
- `target_account_id / target_username` (string) — 이 행이 귀속된 브랜드.

#### 예시

```console
$ solari instagram account ad posts username=beinny_motd months=6 limit=2
```

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

```json
{
  "account_id": "018ecc75-55d8-70a7-a348-d370aa504ed9",
  "username": "beinny_motd",
  "months": 6,
  "total": 12,
  "has_more": true,
  "items": [
    {
      "post_id": "01a05575-7c9b-7232-8519-4a38fa061389",
      "slug": "DcpugJ2kzv8",
      "url": "https://www.instagram.com/p/DcpugJ2kzv8/",
      "post_type": "carousel",
      "posted_at": "2026-08-30T05:08:56Z",
      "text": "#광고 무겁지 않은 가을 데일리 팔레트 로즈밀크티 . .🫖🤎\n차분하고 미지근한 로즈핑크 팔레트인데\n부드러운 밀크티 무드라서 분위기가 넘 예뻐요..🥺\n\n데이지크에서 올리브영 X 산리오 콜라보\n시티팝 에디션으로 미니섀도우팔레트 4종이 출시되는데\n그 중 자주 추천드렸던 로즈밀크티, 밀크라떼가 있더라구요 !\n\nNEW 컬러 피치레코드, 모브카세트도 출시되어요🤍\n도시의 아침과 저녁 무드를 담은 데일리한 …",
      "like_count": 878,
      "comment_count": 19,
      "play_count": 0,
      "media_count": 15,
      "is_paid_partnership": null,
      "target_account_id": "018cab85-8ef8-7dc9-ab0a-7044d463f65e",
      "target_username": "dasique_official"
    },
    "… 1 more"
  ]
}
```

#### MCP 호출로 쓰면

```json
{
  "name": "solari_instagram_account_ad_posts",
  "arguments": {
    "username": "beinny_motd",
    "months": 6,
    "limit": 2
  }
}
```

#### 주의사항

- target은 브랜드 하나로 필터링하며, account_id와 핸들 둘 다 받아요.
- months는 기본값 3이고 최대 24까지 거슬러 올라가요 — account collabs보다 멀리 가요.
- 같은 이력을 브랜드별로 묶어서 보려면 account collabs를 사용하세요.

#### 관련 도구

- [`solari_instagram_account_collabs`](https://solari.sh/docs/tools/instagram-account-collabs.md?lang=ko)
- [`solari_instagram_brand_ad_posts`](https://solari.sh/docs/tools/instagram-brand-ad-posts.md?lang=ko)

### solari instagram content detail

> Instagram 포스트 하나의 전체 정보.

- **CLI**: `solari instagram content detail`
- **MCP 도구**: `solari_instagram_content_detail`
- **권한**: `solari:read` — 로그인한 SOLARI 계정이면 쓸 수 있어요.

Instagram 포스트 하나의 상세 정보로, solari_instagram_content_trending 항목과 동일한 아이템 형태예요. 포스트는 post_id (solari_instagram_account_posts, solari_instagram_content_search, solari_instagram_content_trending, solari_instagram_content_rising에서 얻은 SOLARI post UUID), slug (공개 Instagram 숏코드), 또는 url (공개 포스트 URL)로 지정해요. 아직 추적 중이 아닌 숏코드나 URL은 첫 요청 때 실시간으로 수집되며(수 초 소요), 이 경우 fetched_on_demand=true로 표시돼요. 포스트가 존재하지 않거나 비공개일 때, 또는 알 수 없는 post_id일 때 item은 null이에요. 로그인한 SOLARI 계정이면 누구나 사용할 수 있어요.

**언제 쓰나** — post_id, 숏코드, 또는 공개 URL로 포스트 하나를 열 때.

**무엇이 돌아오나** — content 피드와 동일한 형태의 아이템 하나.

#### 파라미터

- `post_id` (string, 선택, uuid, pattern ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$) — SOLARI post_id UUID. 이 값, slug, 또는 url 중 하나를 넘기세요.
- `slug` (string, 선택, pattern ^[A-Za-z0-9_-]{3,20}$) — 공개 Instagram 숏코드로, 포스트 URL에서 /p/, /reel/, /tv/ 뒤의 구간이에요. post_id가 지정되면 무시돼요.
- `url` (string, 선택, ≤ 512 chars) — https://www.instagram.com/p/<shortcode>/ 또는 .../reel/<shortcode>/ 같은 공개 Instagram 포스트 URL. post_id나 slug가 지정되면 무시돼요.

#### 응답

##### `Response`

- `item` (object | null) — 포스트. 존재하지 않거나 비공개면 null.
- `fetched_on_demand` (boolean) — 이 요청이 해당 포스트를 처음 수집한 경우 true.

##### `item`

- `post_id` (uuid) — SOLARI post id. 다른 content 툴에 그대로 넣으면 돼요.
- `slug` (string) — Instagram 숏코드 — 공개 URL에서 /p/ 또는 /reel/ 뒤의 구간.
- `author_id` (uuid) — 작성 계정의 account_id.
- `username` (string) — 작성자 핸들.
- `full_name` (string | null) — 프로필 표시 이름.
- `profile_pic_url` (string | null) — 프로필 사진 URL.
- `follower_count` (integer | null) — 스냅샷 시점의 작성자 팔로워 수.
- `region` (string | null) — 작성자에게 할당된 리전 코드.
- `posted_at` (timestamp) — 게시 시각 (UTC).
- `media_type` (string) — image, video, 또는 carousel.
- `play_count` (integer | null) — 영상 재생 수. image 포스트에서는 null.
- `like_count` (integer | null) — 스냅샷 시점의 좋아요 수.
- `text` (string | null) — 캡션 텍스트.
- `media_url` (string) — 원본 미디어 URL.
- `thumbnail_url` (string) — 썸네일 URL.
- `score` (number | null) — 피드 랭킹 점수. 하나의 응답 안에서만 비교 가능해요.
- `efficiency_score` (number | null) — 작성자 팔로워 수 대비 성과.
- `est_percentile` (number | null) — 리전 내 추정 백분위, 0–1.
- `total_views_3m` (integer | null) — 최근 3개월간 작성자의 누적 조회 수.
- `median_views_3m` (integer | null) — 최근 3개월간 작성자의 조회 수 중앙값.
- `recent_collab_brands` (string[]) — 작성자가 최근에 협업한 브랜드.
- `item_type` (string) — 아이템 종류 태그. content 피드에서는 post.
- `content_source` (string | null) — 이 아이템을 노출시킨 파이프라인.
- `is_saved` (boolean | null) — SOLARI 앱에 저장된 아이템인지 여부.
- `updated_at` (timestamp | null) — 지표 스냅샷이 마지막으로 갱신된 시각.

#### 예시

```console
$ solari instagram content detail slug=DcyMAmUh6FZ
```

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

```json
{
  "item": {
    "item_type": "content",
    "post_id": "01a06275-d974-7fda-98ee-dd3ee15b4dcf",
    "author_id": "018cabce-14cc-7544-8890-7811ec33ef74",
    "username": "innisfreeofficial",
    "full_name": "INNISFREE | 이니스프리",
    "profile_pic_url": "https://dcr.bzine.co/instagram/users/innisfreeofficial/profile-picture",
    "follower_count": 847619,
    "region": null,
    "posted_at": "2026-09-02T12:00:06Z",
    "media_type": "video",
    "play_count": 22467,
    "like_count": 3224,
    "score": null,
    "efficiency_score": null,
    "est_percentile": null,
    "updated_at": null,
    "media_url": "https://smr-images-b.bzine.co/users/018cabce-14cc-7544-8890-7811ec33ef74/posts/01a06275-d974-7fda-98ee-dd3ee15b4dcf/medias/01a06275-db2b-77f7-a020-b4beb744771f.mp4",
    "thumbnail_url": "https://bzine.co/cdn-cgi/media/width=480,mode=frame,time=0ms/https://smr-images.bzine.co/users/018cabce-14cc-7544-8890-7811ec33ef74/posts/01a06275-d974-7fda-98ee-dd3ee15b4dcf/medias/01a06275-db2b-77f7-a020-b4beb744771f.m …",
    "slug": "DcyMAmUh6FZ",
    "text": "Deeply hydrated skin—NO OFF HOURS. 💚\nwherever the day takes MINGYU (@min9yu_k)—his hydration stays SUPERCHARGED ⚡️\n\nGreen Tea Ceramide Milk: Lightweight milky toner that won‘t clog your pores\nGreen Tea Ceramide Mist: Tou …",
    "brand_match_score": null,
    "recent_collab_brands": [],
    "total_views_3m": null,
    "median_views_3m": null,
    "is_saved": null,
    "content_source": null
  },
  "fetched_on_demand": false
}
```

#### MCP 호출로 쓰면

```json
{
  "name": "solari_instagram_content_detail",
  "arguments": {
    "slug": "DcyMAmUh6FZ"
  }
}
```

#### 주의사항

- url을 넘기면 /p/, /reel/, /tv/ 뒤의 숏코드를 자동으로 추출해요.
- 추적 중이 아닌 숏코드나 URL은 첫 요청 때 실시간으로 수집돼요.
- 여러 개를 한 번에 열려면 content batch를 사용하세요.

#### 관련 도구

- [`solari_instagram_content_batch`](https://solari.sh/docs/tools/instagram-content-batch.md?lang=ko)
- [`solari_instagram_account_posts`](https://solari.sh/docs/tools/instagram-account-posts.md?lang=ko)

### solari instagram content batch

> 한 번의 호출로 포스트 id를 최대 100개까지 실제 데이터로 채워요.

- **CLI**: `solari instagram content batch`
- **MCP 도구**: `solari_instagram_content_batch`
- **권한**: `solari:read` — 로그인한 SOLARI 계정이면 쓸 수 있어요.

solari_instagram_content_detail의 배치 버전. 포스트를 SOLARI 포스트 UUID로 한 번에 최대 100개까지 채워서 반환해요. 각 행에는 slug, caption, posted_at, like/comment 카운트, 영상이면 play_count, 그리고 작성자의 username과 account_id가 담겨요. 추적 중이 아닌 id는 빠지므로 found가 요청한 개수보다 적을 수 있어요. solari_instagram_brand_overview(full=true), solari_instagram_account_posts, solari_instagram_content_search, 또는 트렌드 피드가 준 post_id 목록을 그대로 넣으면 돼요. 로그인한 모든 SOLARI 계정에서 사용할 수 있어요.

**언제 쓰나** — brand overview나 트렌드 피드에서 얻은 id 목록을 실제 캡션과 지표로 바꿀 때.

**무엇이 돌아오나** — 요청한 id 중에서 찾은 포스트.

#### 파라미터

- `post_ids` (uuid[], 필수, 1–100 items, uuid) — 채울 SOLARI 포스트 UUID. 호출당 최대 100개. Instagram shortcode/slug가 아니에요.
- `sort` (enum, 선택, 기본값 "recent") — 항목 정렬: posted_at 내림차순(recent) 또는 like+comment engagement 내림차순. 값: `recent`, `engagement`.

#### 응답

##### `Response`

- `items` (object[]) — 찾은 포스트.
- `requested` (integer) — 보낸 id 개수.
- `found` (integer) — 찾아낸 개수. 추적 중이 아닌 id는 버려지므로 더 적을 수 있어요.

##### `items[]`

- `id` (uuid) — 포스트 id.
- `slug` (string) — Instagram shortcode.
- `text` (string) — 캡션 텍스트.
- `posted_at` (timestamp) — 게시 시각(UTC).
- `username / user_id / account_id` (string) — 작성 계정. account_id가 현재 이름이에요.
- `like_count / comment_count` (integer) — 인게이지먼트 스냅샷.
- `play_count` (integer | null) — 영상 재생 수.
- `media_type` (string) — 포스트 포맷.

#### 예시

```console
$ solari instagram content batch post_ids='["019f505f-f8be-7e88-ae08-6fba999950b1","019f5060-3449-779e-a08b-d6d49add90cd"]'
```

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

```json
{
  "items": [
    {
      "id": "019f505f-f8be-7e88-ae08-6fba999950b1",
      "slug": "Dam_BYyJxtR",
      "text": "#광고 ₊✩‧₊˚ @innisfreeofficial ˚₊✩‧₊ \n공들인 나의 화장.. 찜통 더위에 무너져 내릴때\n이니스프리 노세범 선 파우더 하나면 고민 끝!\n\n유분 가득한 피부.. 꺼진 부위, 모공, 요철 부각되어\n10년은 늙어보이는 몰골에서 노세범 선 파우더 바르는\n즉시 핑크빛 필터를 씌운 듯~ 뽀용 피부 완성 ⭒˚.⋆\n\n노세범 맛집 답게 과다 피지와 유분을 즉각 흡착시키고\n무엇보다 가벼 …",
      "posted_at": "2026-07-10T10:34:01Z",
      "virtual_campaign": null,
      "username": "the_ketchap",
      "user_id": "018d3b53-c0c1-71cc-a44f-204f7d850267",
      "profile_picture_url": null,
      "like_count": 38579,
      "comment_count": 31,
      "thumbnail_url": null,
      "media_url": null,
      "media": [],
      "media_type": "reel",
      "play_count": 676825,
      "account_id": "018d3b53-c0c1-71cc-a44f-204f7d850267"
    },
    "… 1 more"
  ],
  "requested": 2,
  "found": 2
}
```

#### MCP 호출로 쓰면

```json
{
  "name": "solari_instagram_content_batch",
  "arguments": {
    "post_ids": [
      "019f505f-f8be-7e88-ae08-6fba999950b1",
      "019f5060-3449-779e-a08b-d6d49add90cd"
    ]
  }
}
```

#### 주의사항

- SOLARI 포스트 UUID만 받아요. Instagram shortcode는 여기 들어가지 않아요 — 그건 content detail에 slug로 넣으세요.
- sort=engagement는 최신순 대신 like + comment 순으로 정렬해요.

#### 관련 도구

- [`solari_instagram_content_detail`](https://solari.sh/docs/tools/instagram-content-detail.md?lang=ko)
- [`solari_instagram_brand_overview`](https://solari.sh/docs/tools/instagram-brand-overview.md?lang=ko)

### solari instagram content search

> 캡션, 크리에이터 bio, 영상 전사문을 가로지르는 키워드 검색.

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

추적 중인 포스트에 대한 렉시컬 키워드 검색. 캡션, 크리에이터 bio, 영상 전사문 텍스트에 매칭하며(한국어 분석 + n-gram 부분 일치), 관련도 순으로 정렬되고 매치 하이라이트가 함께 와요. 각 item은 post_id, 작성자 account_id/username, caption, 전사문 텍스트, 인게이지먼트 수치, score를 담아요 — post_id는 solari_instagram_content_detail이나 solari_instagram_content_batch에, 계정 참조는 account 툴에 넘기면 돼요. 커버리지: KR, JP, US, TW 리전만 검색할 수 있고 대략 최근 6개월치 포스트를 담아요. total은 10,000까지 정확하고 거기서 포화해요. since/until(UTC 날짜)로 범위를 좁혀요. 로그인된 SOLARI 계정이면 누구나 사용할 수 있어요.

**언제 쓰나** — 주제나 표현으로 포스트를 찾을 때. 답이 카운트라면 content aggregate를 쓰세요.

**무엇이 돌아오나** — 관련도 순 히트. 매치 하이라이트 포함.

#### 파라미터

- `query` (string, 필수) — 캡션, 크리에이터 bio, 영상 전사문에 매칭되는 자유 텍스트 키워드 쿼리.
- `region` (enum, 선택, 기본값 "KR") — 검색할 리전. 이 네 개 리전만 인덱싱되어 있어요. 값: `KR`, `JP`, `US`, `TW`.
- `limit` (integer, 선택, ≥ 1) — 최대 히트 수, 기본값 20. 100을 넘는 값은 100으로 잘려요.
- `offset` (integer, 선택, 기본값 0, ≥ 0) — 페이지네이션 offset, 기본값 0.
- `since` (string, 선택, pattern ^\d{4}-\d{2}-\d{2}$) — 이 UTC 날짜 이후(당일 포함, YYYY-MM-DD)의 포스트만. 약 6개월보다 오래된 데이터는 인덱싱되지 않아요.
- `until` (string, 선택, pattern ^\d{4}-\d{2}-\d{2}$) — 이 UTC 날짜 이전(당일 포함, YYYY-MM-DD)의 포스트만.

#### 응답

##### `Response`

- `query / region` (string) — 적용된 query와 region.
- `total` (integer) — 전체 매치 수. 10,000까지 정확하고 그 뒤로는 포화해요.
- `took_ms` (integer) — 검색 소요 시간.
- `items` (object[]) — 히트 목록. score 내림차순.

##### `items[]`

- `post_id` (uuid) — SOLARI post id.
- `slug` (string) — Instagram shortcode.
- `account_id / author_id / username` (string) — 작성 계정. account_id가 현재 이름이에요.
- `caption` (string) — 캡션 텍스트.
- `user_bio` (string) — 작성자 bio — 검색 대상 텍스트에 포함돼요.
- `transcription_text` (string | null) — 영상 음성 전사문.
- `posted_at` (timestamp) — 게시 시각(UTC).
- `like_count / comment_count` (integer) — 인게이지먼트 스냅샷.
- `follower_count` (integer) — 작성자 팔로워 수.
- `score` (number) — 관련도 점수. 이 응답 안에서만 비교할 수 있어요.
- `highlight` (object) — 필드별 매치된 조각: caption, user_bio, transcription_text.
- `is_video` (boolean) — 해당 포스트가 영상인지 여부.

#### 예시

```console
$ solari instagram content search query="이니스프리 그린티" limit=3
```

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

```json
{
  "query": "이니스프리 그린티",
  "region": "KR",
  "total": 10000,
  "took_ms": 1586,
  "items": [
    {
      "post_id": "019f12d8-3e72-78e9-b7e5-39293bc56f23",
      "author_id": "019f12d8-3e0f-7c74-afc6-e14405bd1523",
      "username": "hanydiary",
      "caption": "[이니스프리에디터 4기 1-2 : 그린티 PDRN 아이&립 세럼] #이니스프리 #그린티PDRN 💚 자세한 포스팅은 프로필 링크 참고해주세요 :)",
      "user_bio": "대외활동 | 휴학생 | 취준일기 🪽과 학생회 2년 연임 🪽이니스프리 대학생 에디터 3기 / 4기",
      "transcription_text": null,
      "posted_at": "2026-02-16T05:44:45Z",
      "like_count": 3,
      "comment_count": 3,
      "follower_count": 972,
      "score": 140.43787,
      "slug": "DUzrl1UkoJb",
      "highlight": {
        "caption": [
          "[<mark>이니스프리</mark>에디터 4기 1-2 : <mark>그린티</mark> PDRN 아이&립 세럼] #이니스프리 #그린티PDRN 💚 자세한 포스팅은 프로필 링크 참고해주세요 :)"
        ],
        "user_bio": [
          "대외활동 | 휴학생 | 취준일기 🪽과 학생회 2년 연임 🪽<mark>이니스프리</mark> 대학생 에디터 3기 / 4기"
        ],
        "transcription_text": []
      },
      "is_video": false,
      "media_url": null,
      "thumbnail_url": null,
      "account_id": "019f12d8-3e0f-7c74-afc6-e14405bd1523"
    },
    "… 2 more"
  ]
}
```

#### MCP 호출로 쓰면

```json
{
  "name": "solari_instagram_content_search",
  "arguments": {
    "query": "이니스프리 그린티",
    "limit": 3
  }
}
```

#### 주의사항

- 인덱스는 KR, JP, US, TW만 커버하며 대략 최근 6개월치를 담아요. 그보다 오래된 since는 아무것도 반환하지 않아요.
- total은 10,000까지 정확하고 거기서 멈춰요.
- 한국어 분석과 n-gram 부분 일치를 함께 써요.

#### 관련 도구

- [`solari_instagram_content_aggregate`](https://solari.sh/docs/tools/instagram-content-aggregate.md?lang=ko)
- [`solari_instagram_content_batch`](https://solari.sh/docs/tools/instagram-content-batch.md?lang=ko)
- [`solari_tiktok_content_search`](https://solari.sh/docs/tools/tiktok-content-search.md?lang=ko)

### solari instagram content trending

> 리전에서 지금 트렌딩 중인 Instagram 포스트.

- **CLI**: `solari instagram content trending`
- **MCP 도구**: `solari_instagram_content_trending`
- **권한**: `solari:read` — 로그인한 SOLARI 계정이면 쓸 수 있어요.

해당 리전에서 현재 트렌딩 중인 Instagram 포스트를 크리에이터 프로필 필드와 함께 반환해요. 이전 응답의 next_cursor를 통한 커서 페이지네이션을 지원해요. 브랜드 account_id 또는 username으로 랭킹을 개인화할 수 있어요. 로그인된 SOLARI 계정이면 누구나 사용할 수 있어요. 속도 기반으로 가속 중인 포스트가 필요하면 solari_instagram_content_rising을 대신 사용하세요.

**언제 쓰나** — "지금 뭐가 먹히고 있나?" 볼륨이 아니라 속도가 필요하면 content rising을 사용하세요.

**무엇이 돌아오나** — 작성자 프로필 필드가 붙은 트렌딩 포스트, 커서로 페이징돼요.

#### 파라미터

- `region` (string, 선택, 기본값 "KR") — KR, JP, US 같은 리전 코드.
- `limit` (integer, 선택, ≥ 1) — 페이지당 최대 포스트 수, 기본값 20. 50을 넘는 값은 50으로 잘려요.
- `cursor` (string, 선택) — 이전 응답의 next_cursor에서 받은 불투명(opaque) 페이지네이션 커서.
- `account_id` (string, 선택, uuid, pattern ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$) — 브랜드 친화도 개인화를 위한 선택적 브랜드 account_id (SOLARI 계정 UUID).
- `username` (string, 선택, ≤ 64 chars) — 브랜드 친화도 개인화를 위한 선택적 브랜드 Instagram 핸들. account_id가 지정되면 무시돼요.

#### 응답

##### `Response`

- `items` (object[]) — 트렌딩 포스트.
- `total_count` (integer) — 피드의 크기.
- `region` (string) — 적용된 리전.
- `content_type` (string) — 피드 종류 태그.
- `next_cursor` (string | null) — 다음 페이지를 요청할 때 cursor로 다시 넘기세요.

##### `items[]`

- `post_id` (uuid) — SOLARI post id. 다른 content 툴에 그대로 넣으면 돼요.
- `slug` (string) — Instagram 숏코드 — 공개 URL에서 /p/ 또는 /reel/ 뒤의 구간.
- `author_id` (uuid) — 작성 계정의 account_id.
- `username` (string) — 작성자 핸들.
- `full_name` (string | null) — 프로필 표시 이름.
- `profile_pic_url` (string | null) — 프로필 사진 URL.
- `follower_count` (integer | null) — 스냅샷 시점의 작성자 팔로워 수.
- `region` (string | null) — 작성자에게 할당된 리전 코드.
- `posted_at` (timestamp) — 게시 시각 (UTC).
- `media_type` (string) — image, video, 또는 carousel.
- `play_count` (integer | null) — 영상 재생 수. image 포스트에서는 null.
- `like_count` (integer | null) — 스냅샷 시점의 좋아요 수.
- `text` (string | null) — 캡션 텍스트.
- `media_url` (string) — 원본 미디어 URL.
- `thumbnail_url` (string) — 썸네일 URL.
- `score` (number | null) — 피드 랭킹 점수. 하나의 응답 안에서만 비교 가능해요.
- `efficiency_score` (number | null) — 작성자 팔로워 수 대비 성과.
- `est_percentile` (number | null) — 리전 내 추정 백분위, 0–1.
- `total_views_3m` (integer | null) — 최근 3개월간 작성자의 누적 조회 수.
- `median_views_3m` (integer | null) — 최근 3개월간 작성자의 조회 수 중앙값.
- `recent_collab_brands` (string[]) — 작성자가 최근에 협업한 브랜드.
- `item_type` (string) — 아이템 종류 태그. content 피드에서는 post.
- `content_source` (string | null) — 이 아이템을 노출시킨 파이프라인.
- `is_saved` (boolean | null) — SOLARI 앱에 저장된 아이템인지 여부.
- `updated_at` (timestamp | null) — 지표 스냅샷이 마지막으로 갱신된 시각.

#### 예시

```console
$ solari instagram content trending region=KR limit=2
```

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

```json
{
  "items": [
    {
      "item_type": "content",
      "post_id": "01a055fe-d72c-7005-8709-eef67b4be6f0",
      "author_id": "018ecc27-f8e7-7100-9339-bb050ea44a7f",
      "username": "sixpackpiggy",
      "full_name": "Jinmin Park",
      "profile_pic_url": "https://dcr.bzine.co/instagram/users/sixpackpiggy/profile-picture",
      "follower_count": 93442,
      "region": "KR",
      "posted_at": "2026-08-29T02:02:20Z",
      "media_type": "video",
      "play_count": 286749,
      "like_count": null,
      "score": 96.69330916066565,
      "efficiency_score": null,
      "est_percentile": 96.69330916066565,
      "updated_at": "2026-09-03T04:51:42.797111Z",
      "media_url": "https://smr-images-b.bzine.co/users/018ecc27-f8e7-7100-9339-bb050ea44a7f/posts/01a055fe-d72c-7005-8709-eef67b4be6f0/medias/01a055fe-d964-7d73-9a77-d06823a2abc2.mp4",
      "thumbnail_url": "https://bzine.co/cdn-cgi/media/width=480,mode=frame,time=0ms/https://smr-images.bzine.co/users/018ecc27-f8e7-7100-9339-bb050ea44a7f/posts/01a055fe-d72c-7005-8709-eef67b4be6f0/medias/01a055fe-d964-7d73-9a77-d06823a2abc2.m …",
      "slug": "Dcmzs05SAae",
      "text": "How dedicated are you to your Korean skincare? 💅@patinaosaka \n#koreanskincare #osaka #japan #kbeauty #traveling",
      "brand_match_score": null,
      "recent_collab_brands": [],
      "total_views_3m": 1875678,
      "median_views_3m": 57780,
      "is_saved": false,
      "content_source": null
    },
    "… 1 more"
  ],
  "total_count": 213635,
  "region": "KR",
  "content_type": "trending",
  "next_cursor": "eyJhcyI6ICIyMDI2LTA5LTAzVDA1OjIwOjIzLjM4Mzk3NCswMDowMCIsICJzYyI6ICIyMDI2LTA5LTAzVDA0OjQ0OjQ3LjkzNTI1OCswMDowMCIsICJzcCI6ICIwMWEwNTVmZS1mOWIyLTdiNmYtYjY1OS05ZGE1OTM3NjgzMWMifQ=="
}
```

#### MCP 호출로 쓰면

```json
{
  "name": "solari_instagram_content_trending",
  "arguments": {
    "region": "KR",
    "limit": 2
  }
}
```

#### 주의사항

- 브랜드 account_id 또는 핸들을 넘기면 브랜드 친화도 기준으로 랭킹이 개인화돼요.
- 페이지네이션은 offset이 아니라 커서 방식이에요 — next_cursor를 다음 호출에 넣으세요.

#### 관련 도구

- [`solari_instagram_content_rising`](https://solari.sh/docs/tools/instagram-content-rising.md?lang=ko)
- [`solari_instagram_content_trend_clusters`](https://solari.sh/docs/tools/instagram-content-trend-clusters.md?lang=ko)

### solari instagram content rising

> 기준선보다 빠르게 가속 중인 Instagram 포스트.

- **CLI**: `solari instagram content rising`
- **MCP 도구**: `solari_instagram_content_rising`
- **권한**: `solari:read` — 로그인한 SOLARI 계정이면 쓸 수 있어요.

해당 리전에서 최근 성과가 기준선보다 빠르게 가속 중인 Instagram 포스트. 커서 페이지네이션과 브랜드 account_id 또는 username을 통한 선택적 브랜드 개인화를 포함해 solari_instagram_content_trending과 동일한 형태예요. 로그인된 SOLARI 계정이면 누구나 사용할 수 있어요.

**언제 쓰나** — 절대 수치보다 모멘텀이 중요할 때 — 정점에 도달하기 전의 포스트를 잡아내요.

**무엇이 돌아오나** — content trending과 동일한 형태이며, 랭킹만 달라요.

#### 파라미터

- `region` (string, 선택, 기본값 "KR") — KR, JP, US 같은 리전 코드.
- `limit` (integer, 선택, ≥ 1) — 페이지당 최대 포스트 수, 기본값 20. 50을 넘는 값은 50으로 잘려요.
- `cursor` (string, 선택) — 이전 응답의 next_cursor에서 받은 불투명(opaque) 페이지네이션 커서.
- `account_id` (string, 선택, uuid, pattern ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$) — 브랜드 친화도 개인화를 위한 선택적 브랜드 account_id (SOLARI 계정 UUID).
- `username` (string, 선택, ≤ 64 chars) — 브랜드 친화도 개인화를 위한 선택적 브랜드 Instagram 핸들. account_id가 지정되면 무시돼요.

#### 응답

##### `Response`

- `items` (object[]) — 상승 중인 포스트.
- `total_count` (integer) — 피드의 크기.
- `region` (string) — 적용된 리전.
- `content_type` (string) — 피드 종류 태그.
- `next_cursor` (string | null) — 다음 페이지를 요청할 때 cursor로 다시 넘기세요.

##### `items[]`

- `post_id` (uuid) — SOLARI post id. 다른 content 툴에 그대로 넣으면 돼요.
- `slug` (string) — Instagram 숏코드 — 공개 URL에서 /p/ 또는 /reel/ 뒤의 구간.
- `author_id` (uuid) — 작성 계정의 account_id.
- `username` (string) — 작성자 핸들.
- `full_name` (string | null) — 프로필 표시 이름.
- `profile_pic_url` (string | null) — 프로필 사진 URL.
- `follower_count` (integer | null) — 스냅샷 시점의 작성자 팔로워 수.
- `region` (string | null) — 작성자에게 할당된 리전 코드.
- `posted_at` (timestamp) — 게시 시각 (UTC).
- `media_type` (string) — image, video, 또는 carousel.
- `play_count` (integer | null) — 영상 재생 수. image 포스트에서는 null.
- `like_count` (integer | null) — 스냅샷 시점의 좋아요 수.
- `text` (string | null) — 캡션 텍스트.
- `media_url` (string) — 원본 미디어 URL.
- `thumbnail_url` (string) — 썸네일 URL.
- `score` (number | null) — 피드 랭킹 점수. 하나의 응답 안에서만 비교 가능해요.
- `efficiency_score` (number | null) — 작성자 팔로워 수 대비 성과.
- `est_percentile` (number | null) — 리전 내 추정 백분위, 0–1.
- `total_views_3m` (integer | null) — 최근 3개월간 작성자의 누적 조회 수.
- `median_views_3m` (integer | null) — 최근 3개월간 작성자의 조회 수 중앙값.
- `recent_collab_brands` (string[]) — 작성자가 최근에 협업한 브랜드.
- `item_type` (string) — 아이템 종류 태그. content 피드에서는 post.
- `content_source` (string | null) — 이 아이템을 노출시킨 파이프라인.
- `is_saved` (boolean | null) — SOLARI 앱에 저장된 아이템인지 여부.
- `updated_at` (timestamp | null) — 지표 스냅샷이 마지막으로 갱신된 시각.

#### 예시

```console
$ solari instagram content rising region=KR limit=2
```

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

```json
{
  "items": [
    {
      "item_type": "content",
      "post_id": "01a0495a-4e46-73d5-a111-a818248b665b",
      "author_id": "019e4a24-ee85-78e9-8763-602930999853",
      "username": "iiiwantkitty",
      "full_name": "주 령",
      "profile_pic_url": "https://dcr.bzine.co/instagram/users/iiiwantkitty/profile-picture",
      "follower_count": 706,
      "region": "KR",
      "posted_at": "2026-08-28T07:38:46Z",
      "media_type": "video",
      "play_count": 48092,
      "like_count": null,
      "score": 0.1292899036795201,
      "efficiency_score": 0.1292899036795201,
      "est_percentile": 84.68488691008565,
      "updated_at": "2026-09-03T05:20:45.496271Z",
      "media_url": "https://smr-images-b.bzine.co/users/019e4a24-ee85-78e9-8763-602930999853/posts/01a0495a-4e46-73d5-a111-a818248b665b/medias/01a0495a-4fc0-7352-92dd-a04afe898589.mp4",
      "thumbnail_url": "https://bzine.co/cdn-cgi/media/width=480,mode=frame,time=0ms/https://smr-images-a.bzine.co/users/019e4a24-ee85-78e9-8763-602930999853/posts/01a0495a-4e46-73d5-a111-a818248b665b/medias/01a0495a-4fc0-7352-92dd-a04afe898589 …",
      "slug": "Dck0Wj8xeq3",
      "text": "이정도가 아니면 뮤트라고 하지말자..⭐️ 뮤트톤 친구 입술에 빡빡 발라주고싶음\n\n컬러 보자마자 아 내꺼하자ㅡㅡ 하고 바로 겟한 것\n\n그레이애쉬,, 핑크 ,, 브라운 다 들어간 밑힌 컬러 이거 뮤트톤들이 바르면 진짜 분위기 미처버리는 립이걸랑 영상보다 실물이 더 뮤트!\n\n입술에 올리면 좀더 투명하게 올라가면서 회끼도는데 뉴트럴하면서도 팥앙금 같은 고런 깔 느낌\n안쪽에만 톡톡 발라서 쌩얼립으로도 …",
      "brand_match_score": null,
      "recent_collab_brands": [
        "apieu_cosmetics",
        "… 8 more"
      ],
      "total_views_3m": 2389749,
      "median_views_3m": 5215,
      "is_saved": false,
      "content_source": null
    },
    "… 1 more"
  ],
  "total_count": 291665,
  "region": "KR",
  "content_type": "rising",
  "next_cursor": "eyJhcyI6ICIyMDI2LTA5LTAzVDA1OjIwOjQ5LjA3Mjg3MiswMDowMCIsICJzYyI6ICIyMDI2LTA5LTAzVDA1OjE5OjQwLjc1NzUwOCswMDowMCIsICJzcCI6ICIwMWEwNDNmOC1hODdlLTdiMWItYjFiNi1iODliMTU2YjU0ODgifQ=="
}
```

#### MCP 호출로 쓰면

```json
{
  "name": "solari_instagram_content_rising",
  "arguments": {
    "region": "KR",
    "limit": 2
  }
}
```

#### 주의사항

- 파라미터와 응답이 content trending과 같으며, 브랜드 개인화도 포함돼요.

#### 관련 도구

- [`solari_instagram_content_trending`](https://solari.sh/docs/tools/instagram-content-trending.md?lang=ko)
- [`solari_instagram_content_trend_clusters`](https://solari.sh/docs/tools/instagram-content-trend-clusters.md?lang=ko)

### solari instagram content trend clusters

> SOLARI 트렌드 다이제스트 — 최근 콘텐츠를 이름 붙은 테마로 묶어요.

- **CLI**: `solari instagram content trend clusters`
- **MCP 도구**: `solari_instagram_content_trend_clusters`
- **권한**: `solari:read` — 로그인한 SOLARI 계정이면 쓸 수 있어요.

SOLARI 트렌드 다이제스트. 한 리전의 최근 콘텐츠 트렌드 클러스터를 클러스터 메타데이터와 소속 포스트와 함께 반환하며, 브랜드 account_id나 username을 주면 브랜드 연관도로 재정렬할 수도 있어요. 로그인된 SOLARI 계정이면 누구나 사용할 수 있어요.

**언제 쓰나** — 개별 포스트가 아니라 지금 흐름의 윤곽을 읽을 때.

**무엇이 돌아오나** — 이름 붙은 클러스터. 규모, 변화, 소속 포스트 미리보기를 포함해요.

#### 파라미터

- `region` (string, 선택, 기본값 "KR") — 리전 코드. KR, JP, US 등.
- `since_days` (integer, 선택, 기본값 7, 1–90) — 트렌드 클러스터를 볼 조회 기간(일), 1에서 90 사이.
- `limit` (integer, 선택, ≥ 1) — 반환되는 트렌드 클러스터 최대 개수, 기본값 20. 24를 넘는 값은 24로 잘려요.
- `account_id` (string, 선택, uuid, pattern ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$) — 브랜드 연관도 재정렬에 쓸 선택적 브랜드 account_id(SOLARI 계정 UUID).
- `username` (string, 선택, ≤ 64 chars) — 브랜드 연관도 재정렬에 쓸 선택적 브랜드 Instagram 핸들. account_id가 설정되면 무시돼요.
- `brand_aware` (boolean, 선택, 기본값 true) — account_id가 주어지면 브랜드 연관도로 클러스터를 재정렬해요.

#### 응답

##### `Response`

- `success` (boolean) — 다이제스트가 생성되었는지 여부.
- `trend_count` (integer) — 반환된 클러스터 수.
- `header_text` (string) — 다이제스트 헤드라인.
- `region / since_days` (string · integer) — 적용된 리전과 조회 기간.
- `brand_aware` (boolean) — 브랜드 연관도 재정렬이 요청되었는지 여부.
- `als_applied` (boolean) — 연관도 모델이 실제로 실행되었는지 여부.
- `trends` (object[]) — 클러스터.

##### `trends[]`

- `cluster_id` (string) — 클러스터 id.
- `name` (string) — 클러스터 이름.
- `bullets` (string[]) — 클러스터를 설명하는 문장.
- `count` (integer) — 소속 포스트 수.
- `count_delta` (integer) — 직전 기간 대비 소속 포스트 수 변화.
- `growth_pct` (number) — 증가율, 퍼센트.
- `avg_play_delta` (number) — 평균 재생 수 변화.
- `distinct_creators` (integer) — 클러스터에 기여한 크리에이터 수.
- `creator_delta` (integer) — 크리에이터 수 변화.
- `is_new` (boolean) — 이 클러스터가 이번 기간에 처음 등장했는지 여부.
- `member_thumbnails` (object[]) — 소속 포스트의 썸네일 미리보기.

#### 예시

```console
$ solari instagram content trend clusters region=KR since_days=7 limit=2
```

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

```json
{
  "success": true,
  "trend_count": 2,
  "header_text": "최근 7일 인기 트렌드 2개 (브랜드 컨텍스트 없음)",
  "brand_aware": true,
  "als_applied": false,
  "region": "KR",
  "since_days": 7,
  "directive": null,
  "trends": [
    {
      "cluster_id": "01a05857-7727-74d8-8da5-4e95981aca8d",
      "name": "GV90의 미래형 하이테크 기능",
      "bullets": [
        "화면이 회전하거나 시트가 뒤로 돌아가는 등 물리적으로 변형되는 자동차 내부 장치들을 직접 시연함",
        "… 1 more"
      ],
      "count": 7,
      "count_delta": 0,
      "growth_pct": 0,
      "avg_play_delta": 0,
      "creator_delta": 0,
      "distinct_creators": 3,
      "is_new": false,
      "early_zone_creator_count": null,
      "early_zone_creator_ratio": null,
      "als_member_count": null,
      "mean_als_score": null,
      "annotation": null,
      "group": null,
      "member_thumbnails": [
        {
          "post_id": "01a030df-c4b3-739c-9214-44b3b9463c7b",
          "thumbnail_url": "https://bzine.co/cdn-cgi/media/width=480,mode=frame,time=100ms/https://smr-images-c.bzine.co/users/018cb4c9-da89-7b02-8efd-53ccb65c26c9/posts/01a030df-c4b3-739c-9214-44b3b9463c7b/medias/01a030df-c7c3-788e-8775-1096728e07 …",
          "slug": "DcP6jgRMTRv",
          "username": "sol.bpd",
          "media_url": "https://smr-images-c.bzine.co/users/018cb4c9-da89-7b02-8efd-53ccb65c26c9/posts/01a030df-c4b3-739c-9214-44b3b9463c7b/medias/01a030df-c7c3-788e-8775-1096728e07f2.mp4",
          "media_type": "video",
          "play_count": 1947419,
          "posted_at": "2026-08-20T04:37:17+00:00"
        },
        "… 3 more"
      ]
    },
    "… 1 more"
  ],
  "insights": null,
  "insight_query": null
}
```

#### MCP 호출로 쓰면

```json
{
  "name": "solari_instagram_content_trend_clusters",
  "arguments": {
    "region": "KR",
    "since_days": 7,
    "limit": 2
  }
}
```

#### 주의사항

- 무거운 호출 — 게이트웨이가 120초를 허용해요.
- since_days는 1–90 범위예요. limit은 24에서 상한이 걸려요.
- 브랜드를 주면 brand_aware 재정렬이 켜져요. 원래 정렬을 유지하려면 brand_aware=false로 두세요.

#### 관련 도구

- [`solari_instagram_content_trending`](https://solari.sh/docs/tools/instagram-content-trending.md?lang=ko)
- [`solari_instagram_content_rising`](https://solari.sh/docs/tools/instagram-content-rising.md?lang=ko)

### solari instagram content aggregate

> 포스트를 나열하는 대신 세어요 — 계정, 포맷, 해시태그, 멘션, 키워드 기준.

- **CLI**: `solari instagram content aggregate`
- **MCP 도구**: `solari_instagram_content_aggregate`
- **권한**: `solari:read` — 로그인한 SOLARI 계정이면 쓸 수 있어요.

추적 중인 포스트에 대한 카운트와 인게이지먼트 롤업. 개별 포스트가 아니라 숫자로 답하는 질문에 써요: 계정별 월간 포스트 수, 특정 주제를 지배하는 해시태그, 포맷별 평균 좋아요. account, post_type, hashtag, mention, caption_keyword, transcription_keyword 로 그룹핑하고, 선택적으로 각 그룹을 day, week, month 로 쪼갤 수 있어요. post_count는 항상 반환돼요. metrics를 지정하면 좋아요/댓글/조회수의 합계와 평균, 평균 팔로워 수, 고유 계정 수를 함께 받아요. 자유 텍스트 query, usernames, hashtags, mentions, post_types 로 대상을 좁혀요. mentions로 필터링하고 account로 그룹핑하면 특정 핸들을 태그한 계정이 어디인지 알 수 있어요. 커버리지: KR, JP, US, TW 리전, 대략 최근 6개월치 — 그보다 오래된 since는 잘려서 실제 적용된 값이 응답에 되돌아와요. 버킷은 큰 것부터 정렬되며, truncated=true는 limit이 반환한 것보다 더 많은 그룹이 있었다는 뜻이에요. 카운트가 아니라 포스트 자체가 필요하면 solari_instagram_content_search를 쓰세요. 로그인된 SOLARI 계정이면 누구나 사용할 수 있어요.

**언제 쓰나** — 숫자로 답하는 질문: 계정별 월간 포스트 수, 특정 주제를 지배하는 해시태그, 포맷별 평균 좋아요.

**무엇이 돌아오나** — 그룹별 카운트와 인게이지먼트 롤업. 큰 그룹부터.

#### 파라미터

- `region` (enum, 선택, 기본값 "KR") — 집계할 리전. 이 네 개 리전만 인덱싱되어 있어요. 값: `KR`, `JP`, `US`, `TW`.
- `group_by` (enum, 선택) — 그룹핑 기준 차원. 생략하면 필터링된 전체를 단일 total 버킷으로 집계해요. 값: `account`, `post_type`, `hashtag`, `mention`, `caption_keyword`, `transcription_keyword`.
- `interval` (enum, 선택) — 쪼갤 캘린더 단위. 단독으로 쓰면 기간당 버킷 하나를 반환하고, group_by와 함께 쓰면 각 그룹이 시계열을 가져요. 값: `day`, `week`, `month`.
- `metrics` (string[], 선택) — 항상 반환되는 post_count 외의 추가 지표. 지표 값은 스냅샷이라 실시간 수치보다 늦을 수 있어요. 값: `like_sum`, `like_avg`, `comment_sum`, `comment_avg`, `view_sum`, `view_avg`, `follower_avg`, `account_count`.
- `query` (string, 선택) — 캡션, 크리에이터 bio, 영상 전사문에 매칭되는 자유 텍스트 필터.
- `usernames` (string[], 선택) — 이 Instagram 핸들로 한정해요.
- `hashtags` (string[], 선택) — 이 해시태그를 모두 담은 포스트로 한정해요.
- `mentions` (string[], 선택) — 이 핸들을 모두 태그한 포스트로 한정해요. group_by=account와 함께 쓰면 특정 핸들을 태그한 계정을 순위로 볼 수 있어요.
- `post_types` (string[], 선택) — 이 포스트 포맷으로 한정해요.
- `since` (string, 선택, pattern ^\d{4}-\d{2}-\d{2}$) — 이 UTC 날짜 이후(당일 포함, YYYY-MM-DD)의 포스트만. 기본값은 183일 전이며, 이 값이 허용되는 가장 이른 경계이기도 해요.
- `until` (string, 선택, pattern ^\d{4}-\d{2}-\d{2}$) — 이 UTC 날짜 이전(당일 포함, YYYY-MM-DD)의 포스트만.
- `limit` (integer, 선택, ≥ 1) — group_by가 설정됐을 때 반환되는 최대 그룹 수, 기본값 20. 50을 넘는 값은 50으로 잘려요.

#### 응답

##### `Response`

- `region` (string) — 집계가 수행된 리전.
- `since` (date) — 실제로 적용된 시작 날짜. 보존 기간보다 오래된 요청은 잘려서 보정된 값이 여기로 되돌아와요.
- `until` (date | null) — 실제로 적용된 종료 날짜.
- `group_by` (string | null) — 적용된 그룹핑 차원.
- `interval` (string | null) — 적용된 캘린더 단위.
- `total_posts` (integer) — 필터에 매칭된 포스트 수. 그룹이 겹치면 버킷 카운트의 합과 다를 수 있어요.
- `truncated` (boolean) — limit이 반환한 것보다 더 많은 그룹이 있었으면 true.
- `buckets` (object[]) — 그룹당 엔트리 하나. 큰 것부터.

##### `buckets[]`

- `key` (string) — 그룹 값 — 핸들, 해시태그, 포맷 등. group_by를 생략하면 단일 total 버킷이 돼요.
- `metrics.post_count` (integer) — 포스트 수. 항상 반환돼요.
- `metrics.like_sum / like_avg` (number | null) — 좋아요 합계와 평균. metrics로 요청했을 때만.
- `metrics.comment_sum / comment_avg` (number | null) — 댓글 합계와 평균.
- `metrics.view_sum / view_avg` (number | null) — 조회수 합계와 평균.
- `metrics.share_sum / collect_sum` (number | null) — TikTok 전용 지표. Instagram에서는 항상 null이에요.
- `metrics.follower_avg` (number | null) — 작성 계정들의 평균 팔로워 수.
- `metrics.account_count` (integer | null) — 그룹 내 고유 계정 수.
- `series` (object[] | null) — 기간별 분해. interval이 설정됐을 때 존재해요.

#### 예시

```console
$ solari instagram content aggregate group_by=hashtag query="이니스프리" metrics='["like_avg","view_sum","account_count"]' limit=5
```

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

```json
{
  "region": "KR",
  "since": "2026-03-04",
  "until": null,
  "group_by": "hashtag",
  "interval": null,
  "total_posts": 1647,
  "truncated": true,
  "buckets": [
    {
      "key": "이니스프리",
      "metrics": {
        "post_count": 772,
        "like_sum": null,
        "like_avg": 320.7240932642487,
        "comment_sum": null,
        "comment_avg": null,
        "view_sum": 9400953,
        "view_avg": null,
        "share_sum": null,
        "share_avg": null,
        "collect_sum": null,
        "collect_avg": null,
        "follower_avg": null,
        "account_count": 587
      },
      "series": null
    },
    {
      "key": "광고",
      "metrics": {
        "post_count": 548,
        "like_sum": null,
        "like_avg": 373.04021937842776,
        "comment_sum": null,
        "comment_avg": null,
        "view_sum": 5463711,
        "view_avg": null,
        "share_sum": null,
        "share_avg": null,
        "collect_sum": null,
        "collect_avg": null,
        "follower_avg": null,
        "account_count": 381
      },
      "series": null
    },
    "… 3 more"
  ]
}
```

#### MCP 호출로 쓰면

```json
{
  "name": "solari_instagram_content_aggregate",
  "arguments": {
    "group_by": "hashtag",
    "query": "이니스프리",
    "metrics": [
      "like_avg",
      "view_sum",
      "account_count"
    ],
    "limit": 5
  }
}
```

#### 주의사항

- post_count는 항상 반환돼요. 나머지는 metrics에 명시하지 않는 한 null이에요.
- mentions로 필터링하고 account로 그룹핑하면 "어떤 계정이 이 핸들을 태그했나?"에 답할 수 있어요.
- 인덱스는 KR, JP, US, TW를 대략 최근 6개월치로 커버해요. since의 기본값이자 하한은 183일 전이며, 그보다 오래된 값은 잘려서 실제 적용된 값이 응답에 되돌아와요.
- interval만 지정하면 기간당 버킷 하나를 반환하고, group_by와 함께 쓰면 각 그룹이 시계열을 가져요.
- 포스트 자체가 답이라면 content search를 쓰세요.

#### 관련 도구

- [`solari_instagram_content_search`](https://solari.sh/docs/tools/instagram-content-search.md?lang=ko)
- [`solari_tiktok_content_aggregate`](https://solari.sh/docs/tools/tiktok-content-aggregate.md?lang=ko)

### solari instagram tag search

> 정확한 해시태그 하나 또는 @멘션이 달린 포스트 전부.

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

정확히 일치하는 태그 하나가 달린 추적 중인 포스트를 전부, 내용까지 채워서 돌려줘요 — '#ootd'는 해시태그, '@handle'은 그 계정 멘션이고, 수집 최신순에 커서 페이징이에요. 태그 전체가 정확히 일치해야 하는 매칭이며 추적한 전 기간·전 리전을 커버해요(solari_instagram_content_search는 자유 텍스트 검색이지만 4개 리전·약 6개월만 봐요). 로그인된 SOLARI 계정이면 누구나 사용할 수 있어요.

**언제 쓰나** — 캠페인 해시태그가 실제로 얼마나 퍼졌는지 재거나, 특정 계정을 멘션한 포스트를 전부 찾을 때예요. 추적한 전 기간에 대해 태그 전체가 정확히 일치하는 것만 찾아요. 텍스트 안 아무데나 있는 키워드를 찾는 건 content search 쪽이지만, 그쪽은 4개 리전·약 6개월만 봐요.

**무엇이 돌아오나** — 태그가 달린 포스트를 수집 최신순으로 채워서, 다음 페이지용 커서와 함께 돌려줘요.

#### 파라미터

- `query` (string, 필수, ≤ 200 chars) — 정확한 태그 하나. '#ootd' 또는 'ootd'는 해시태그를, '@oliveyoung_official'은 그 계정 멘션을 찾아요. 공백과 와일드카드는 안 돼요.
- `limit` (integer, 선택, ≥ 1) — 페이지당 포스트 수, 기본값 20. 1000을 넘는 값은 1000으로 잘려요. 페이지를 크게 잡아도 비용은 더 들지 않아요.
- `cursor` (string, 선택) — 이전 응답의 next_cursor. 첫 페이지에서는 생략하세요.

#### 응답

##### `Response`

- `query` (string) — 실제로 조회에 쓰인 태그 값. 앞의 # 이나 @ 는 빠져 있어요.
- `tag_kind` (string) — hashtag 또는 mention — query를 어느 쪽으로 읽었는지예요.
- `matched_tags` (integer) — query가 매칭한 저장된 태그 표기의 개수. 1보다 큰 게 정상이에요 — 멘션은 핸들과 그 계정의 숫자 id 양쪽에, 한글 해시태그는 두 가지 유니코드 표기 양쪽에 매칭되거든요. 0이면 그 태그가 한 번도 등장한 적 없다는 뜻이에요.
- `items` (object[]) — 찾은 포스트들.
- `found` (integer) — 실제로 채워진 포스트 수. 태그 색인이 갱신된 뒤에 삭제된 포스트가 있으면 페이지 크기보다 작아져요.
- `next_cursor` (string | null) — 다음 페이지를 받으려면 이 값을 cursor로 넘기세요. 마지막 페이지면 null이에요.
- `mirror_synced_at` (timestamp | null) — 태그 색인이 마지막으로 갱신된 시각(UTC). 이 시각 이후에 올라온 포스트에는 아직 태그가 안 붙어 있을 수 있어요.

##### `items[]`

- `id` (uuid) — 포스트 id.
- `slug` (string) — Instagram 숏코드.
- `text` (string) — 캡션 텍스트.
- `posted_at` (timestamp) — 발행 시각(UTC).
- `username / user_id / account_id` (string) — 작성 계정. account_id가 현재 쓰는 이름이에요.
- `like_count / comment_count` (integer) — 반응 스냅샷.
- `play_count` (integer | null) — 영상 재생 수.
- `media_type` (string) — 포스트 형식.

#### 예시

```console
$ solari instagram tag search query=#ootd limit=3
```

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

```json
{
  "query": "ootd",
  "tag_kind": "hashtag",
  "matched_tags": 1,
  "items": [
    {
      "id": "01a06a16-781f-7578-822b-1c326e72f28d",
      "slug": "DW1jniHiVSU",
      "text": "御殿場是一個一天逛不完的地方 希望下次有時間可以慢慢逛 —— OOTD —— Pants：LAKOLE / Shirt：HARE #LYNN__OOTD #日常穿搭 #ootd …",
      "posted_at": "2026-04-07T16:16:21Z",
      "virtual_campaign": null,
      "username": "llling_yinnnnn",
      "user_id": "019dbc46-1a67-7ef5-b95a-2fb466790d04",
      "account_id": "019dbc46-1a67-7ef5-b95a-2fb466790d04",
      "profile_picture_url": null,
      "like_count": 3,
      "comment_count": 4,
      "media_type": "post",
      "play_count": null,
      "media": []
    },
    {
      "id": "01a06a16-552d-7099-ae0a-77e6b68de960",
      "slug": "DaS66VzJBPW",
      "text": "SEOUL OOTD — 這次搭配了四種完全不同風格 #ootd #lynn__ootd #穿搭販賣機 #韓國穿搭",
      "posted_at": "2026-07-02T15:33:13Z",
      "virtual_campaign": null,
      "username": "llling_yinnnnn",
      "user_id": "019dbc46-1a67-7ef5-b95a-2fb466790d04",
      "account_id": "019dbc46-1a67-7ef5-b95a-2fb466790d04",
      "profile_picture_url": null,
      "like_count": 32,
      "comment_count": 1,
      "media_type": "reel",
      "play_count": 888,
      "media": []
    },
    "… 1 more"
  ],
  "found": 3,
  "next_cursor": "01a06a16-552d-7099-ae0a-77e6b68de960",
  "mirror_synced_at": "2026-09-03T21:47:19Z"
}
```

#### MCP 호출로 쓰면

```json
{
  "name": "solari_instagram_tag_search",
  "arguments": {
    "query": "#ootd",
    "limit": 3
  }
}
```

#### 주의사항

- 정렬 기준은 발행일이 아니라 수집 시각이에요 — 한 계정의 포스트는 한 번에 몰아서 수집되기 때문에, 연속된 항목이 같은 작성자인 경우가 잦고 posted_at은 들쭉날쭉해요. 발행 순서가 중요하면 직접 posted_at으로 정렬하세요.
- 태그 색인은 하루에 한 번 다시 만들어요. 최근 몇 시간 안의 포스트에는 아직 태그가 안 붙어 있을 수 있고, 정확한 기준 시각은 mirror_synced_at에 있어요. 캡션과 반응 수치는 항상 최신이에요.
- 페이지가 아무리 커도 계산 비용은 같아요. 50개짜리 20페이지보다 1000개짜리 1페이지가 나아요.
- 태그 전체가 정확히 일치해야 해요. '#ootd'는 '#ootdkorea'와 매칭되지 않고 와일드카드도 없어요.
- 앞에 @를 붙이면 그 계정을 멘션한 포스트를 찾아요: 'query=@oliveyoung_official'.

#### 관련 도구

- [`solari_instagram_content_search`](https://solari.sh/docs/tools/instagram-content-search.md?lang=ko)
- [`solari_instagram_content_aggregate`](https://solari.sh/docs/tools/instagram-content-aggregate.md?lang=ko)

### 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)

### solari tiktok account profile

> SOLARI가 아는 TikTok 계정 하나의 모든 정보.

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

TikTok 계정 하나의 전체 SOLARI 프로필: username(핸들), nickname, bio, 팔로워/팔로잉/좋아요/영상 수, region, verified/private/commerce 플래그, profile_url, 그리고 최근 포스트 미리보기(recent_posts)가 함께 담겨요. 계정은 account_id(solari_tiktok_account_search 가 반환하는 TikTok 계정 UUID) 또는 username(TikTok 핸들)으로 지정해요. 아직 추적 중이 아닌 핸들은 첫 요청 때 실시간으로 수집해요(10~40초 소요, 응답의 fetched_on_demand=true, 백그라운드 크롤이 도착하기 전까지는 가장 최근 포스트만 조회할 수 있어요). 그 뒤에도 not-found 에러가 나면 해당 핸들은 TikTok에 존재하지 않아요. 로그인된 SOLARI 계정이면 누구나 사용할 수 있어요.

**언제 쓰나** — TikTok 계정 심층 분석의 첫 호출. 최근 포스트가 함께 담겨 와요.

**무엇이 돌아오나** — 프로필 필드, 최근 포스트 미리보기, 추적 상태.

#### 파라미터

- `account_id` (string, 선택, uuid, pattern ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$) — TikTok 계정의 account_id(SOLARI 계정 UUID). 이 값 또는 username 중 하나를 넘기세요.
- `username` (string, 선택, ≤ 64 chars) — TikTok 핸들. 앞의 @는 있어도 없어도 돼요. account_id가 설정되면 무시돼요.

#### 응답

##### `Response`

- `account_id` (uuid) — TikTok account_id.
- `username / nickname / bio` (string) — 핸들, 표시 이름, bio 텍스트.
- `bio_links` (string[]) — bio 안의 링크.
- `follower_count / following_count` (integer) — 팔로워와 팔로잉.
- `heart_count` (integer) — 계정 전체 누적 좋아요.
- `video_count` (integer) — 게시한 영상 수.
- `is_verified / is_private` (boolean) — 인증 및 비공개 플래그.
- `is_commerce_user / commerce_user_category` (boolean · string) — 커머스 상태와 카테고리.
- `region / language` (string | null) — 지역 및 언어 코드.
- `avatar_url / profile_url` (string) — 아바타와 공개 프로필 링크.
- `tracked` (boolean) — 이 계정이 정기 크롤 대상인지 여부.
- `sync_status` (string) — 크롤 상태.
- `synced_at` (timestamp) — 마지막 크롤 시각.
- `recent_posts` (object[]) — 최근 포스트 미리보기.
- `fetched_on_demand` (boolean) — 이 요청이 해당 계정을 처음 끌어온 경우 true.

##### `recent_posts[]`

- `post_id` (uuid) — SOLARI post id. Instagram post id와는 다른 네임스페이스예요.
- `video_id` (string) — 공개된 TikTok 숫자 id — /video/ 또는 /photo/ 뒤의 숫자.
- `url` (string) — 공개 TikTok 퍼머링크.
- `account_id` (uuid) — 작성자의 TikTok account_id.
- `username` (string) — 작성자 핸들.
- `post_type` (string) — video(단일 클립) 또는 carousel(이미지 슬라이드쇼).
- `posted_at` (timestamp) — 게시 시각(UTC).
- `caption` (string) — 캡션 텍스트.
- `duration_seconds` (integer) — 영상 길이.
- `width / height` (integer) — 영상 해상도.
- `play_count` (integer) — 재생 수.
- `like_count` (integer) — 좋아요 수.
- `comment_count` (integer) — 댓글 수.
- `share_count` (integer) — 공유 수.
- `collect_count` (integer) — 저장 수.
- `is_ad` (boolean) — TikTok이 해당 포스트를 광고로 표시했는지 여부.
- `is_pinned` (boolean) — 프로필 상단 고정 여부.
- `aigc_label_type` (string | null) — TikTok이 붙인 경우의 AI 생성 콘텐츠 라벨.
- `original_language_code` (string | null) — 원본 언어 코드.
- `cover_url` (string) — 커버 이미지 URL.
- `video_url` (string) — 영상 파일 URL.
- `images` (string[]) — 캐러셀 슬라이드. video 포스트에서는 비어 있어요.
- `hashtags` (string[]) — 캡션에서 파싱한 해시태그.
- `mentions` (string[]) — 캡션에 멘션된 핸들.
- `transcript` (string | null) — 음성 전사문. include_transcript=true일 때만 채워져요.

#### 예시

```console
$ solari tiktok account profile username=innisfree_official
```

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

```json
{
  "account_id": "019b2137-f76e-7b33-9437-26044fa7b1ed",
  "username": "innisfree_official",
  "nickname": "Innisfreeofficial",
  "bio": "NATURE MEETS KOREAN SKIN SCIENCE",
  "bio_links": [
    "https://linktr.ee/innisfree_official"
  ],
  "follower_count": 143900,
  "following_count": 14,
  "heart_count": 2200000,
  "video_count": 767,
  "is_verified": true,
  "is_private": false,
  "is_commerce_user": true,
  "commerce_user_category": "Beauty",
  "region": "KR",
  "language": null,
  "avatar_url": "https://p16-common-sign.tiktokcdn-eu.com/tos-alisg-avt-0068/3f8e48dc4a284a8ead37e93175ebdb86~tplv-tiktokx-cropcenter:720:720.jpeg?dr=10399&refresh_token=04b90255&x-expires=1788541200&x-signature=Gd3gJu4HyBZPCr%2FqEevyDs6 …",
  "profile_url": "https://www.tiktok.com/@innisfree_official",
  "sync_status": "OK",
  "tracked": true,
  "synced_at": "2026-09-02T17:16:05.835000Z",
  "recent_posts": [
    {
      "post_id": "01a0631e-f0df-7e9d-a09b-d84bc31d3834",
      "video_id": "7680375687139642645",
      "url": "https://www.tiktok.com/@innisfree_official/video/7680375687139642645",
      "account_id": "019b2137-f76e-7b33-9437-26044fa7b1ed",
      "username": "innisfree_official",
      "post_type": "video",
      "posted_at": "2026-09-02T12:00:00Z",
      "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  Green Tea Ceramide Mist: Touch-free, fa …",
      "duration_seconds": 23,
      "width": 1080,
      "height": 1920,
      "play_count": 493,
      "like_count": 37,
      "comment_count": 2,
      "share_count": 0,
      "collect_count": 3,
      "is_ad": false,
      "is_pinned": false,
      "aigc_label_type": null,
      "original_language_code": null,
      "cover_url": "https://smr-images-a.bzine.co/tiktok/users/019b2137-f76e-7b33-9437-26044fa7b1ed/posts/01a0631e-f0df-7e9d-a09b-d84bc31d3834/medias/cover.jpg",
      "video_url": "https://smr-images-a.bzine.co/tiktok/users/019b2137-f76e-7b33-9437-26044fa7b1ed/posts/01a0631e-f0df-7e9d-a09b-d84bc31d3834/medias/origin.mp4",
      "images": [],
      "hashtags": [],
      "mentions": [],
      "transcript": null
    },
    "… 5 more"
  ],
  "fetched_on_demand": false
}
```

#### MCP 호출로 쓰면

```json
{
  "name": "solari_tiktok_account_profile",
  "arguments": {
    "username": "innisfree_official"
  }
}
```

#### 주의사항

- 추적 중이 아닌 핸들은 첫 요청 때 실시간으로 수집해요. 10~40초가 걸리고, fetched_on_demand=true로 표시되며, 백그라운드 크롤이 도착하기 전까지는 가장 최근 포스트만 존재해요.
- 그 뒤에도 not-found 에러가 나면 해당 핸들은 TikTok에 존재하지 않아요.

#### 관련 도구

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

### solari tiktok account posts

> TikTok 계정 하나의 포스트를 최신순으로 페이지 단위로 훑어요.

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

TikTok 계정 하나의 포스트를 최신순으로, 페이지네이션과 필터와 함께 반환해요. 계정은 account_id(solari_tiktok_account_search가 주는 TikTok 계정 UUID) 또는 username(TikTok 핸들)으로 지정해요. 각 항목에는 post_id(SOLARI 포스트 UUID), video_id(공개 숫자 TikTok id)와 url, post_type(video 또는 carousel), posted_at, caption, duration_seconds, play/like/comment/share/collect 카운트, is_ad, cover_url, images(캐러셀 슬라이드), hashtags, mentions가 담기고, include_transcript=true면 transcript도 담겨요. 전사문은 길기 때문에 include_transcript는 기본적으로 꺼져 있어요. 음성 내용이 중요할 때만 켜세요. 응답에는 found, account_id, username, total, has_more, items가 실려요. limit과 offset으로 페이지를 넘기고, since/until(UTC 날짜, 양끝 포함)과 post_type으로 범위를 좁혀요. 아직 추적 중이 아닌 핸들은 첫 요청 때 실시간으로 수집되며(10~40초 소요), fetched_on_demand=true는 백그라운드 크롤이 들어오기 전까지 가장 최근 포스트만 사용할 수 있다는 표시예요. found=false는 그 핸들이 TikTok에 존재하지 않는다는 뜻이에요. 로그인한 모든 SOLARI 계정에서 사용할 수 있어요.

**언제 쓰나** — 프로필 미리보기보다 더 깊이 파고들 때, 또는 기간과 포맷으로 범위를 좁힐 때.

**무엇이 돌아오나** — 포스트. 선택적으로 음성 전사문 포함.

#### 파라미터

- `account_id` (string, 선택, uuid, pattern ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$) — TikTok 계정의 account_id(SOLARI 계정 UUID). 이 값 또는 username 중 하나를 주세요.
- `username` (string, 선택, ≤ 64 chars) — TikTok 핸들. 앞의 @는 있어도 없어도 돼요. account_id가 설정되면 무시돼요.
- `limit` (integer, 선택, ≥ 1) — 페이지당 포스트 수, 기본값 12. 200을 넘는 값은 200으로 잘려요.
- `offset` (integer, 선택, 기본값 0, ≥ 0) — 페이지네이션 offset, 기본값 0.
- `since` (string, 선택, pattern ^\d{4}-\d{2}-\d{2}$) — 이 UTC 날짜 이후의 포스트만. YYYY-MM-DD, 해당일 포함.
- `until` (string, 선택, pattern ^\d{4}-\d{2}-\d{2}$) — 이 UTC 날짜 이전의 포스트만. YYYY-MM-DD, 해당일 포함.
- `post_type` (enum, 선택) — 이 포맷의 포스트만. video는 단일 클립, carousel은 이미지 슬라이드쇼예요. 값: `video`, `carousel`.
- `include_transcript` (boolean, 선택, 기본값 false) — 각 항목에 음성 전사문을 붙여요. 전사문이 길어서 기본값은 꺼짐.

#### 응답

##### `Response`

- `found` (boolean) — false면 그 핸들이 TikTok에 존재하지 않는다는 뜻이에요.
- `account_id / username` (string) — 확인된 계정.
- `total` (integer) — 필터에 맞는 포스트 수.
- `has_more` (boolean) — 다음 페이지가 있는지 여부.
- `items` (object[]) — 포스트. 최신순.
- `fetched_on_demand` (boolean) — 지금까지 가장 최근 포스트만 사용할 수 있으면 true.

##### `items[]`

- `post_id` (uuid) — SOLARI 포스트 id. Instagram 포스트 id와는 다른 네임스페이스예요.
- `video_id` (string) — 공개 숫자 TikTok id — /video/ 또는 /photo/ 뒤에 오는 숫자.
- `url` (string) — 공개 TikTok 퍼머링크.
- `account_id` (uuid) — 작성자의 TikTok account_id.
- `username` (string) — 작성자 핸들.
- `post_type` (string) — video(단일 클립) 또는 carousel(이미지 슬라이드쇼).
- `posted_at` (timestamp) — 게시 시각(UTC).
- `caption` (string) — 캡션 텍스트.
- `duration_seconds` (integer) — 영상 길이.
- `width / height` (integer) — 영상 해상도.
- `play_count` (integer) — 재생 수.
- `like_count` (integer) — 좋아요 수.
- `comment_count` (integer) — 댓글 수.
- `share_count` (integer) — 공유 수.
- `collect_count` (integer) — 저장 수.
- `is_ad` (boolean) — TikTok이 이 포스트를 광고로 표시했는지 여부.
- `is_pinned` (boolean) — 프로필 상단에 고정됨.
- `aigc_label_type` (string | null) — TikTok이 붙인 경우의 AI 생성 콘텐츠 라벨.
- `original_language_code` (string | null) — 원본 언어 코드.
- `cover_url` (string) — 커버 이미지 URL.
- `video_url` (string) — 영상 파일 URL.
- `images` (string[]) — 캐러셀 슬라이드. video 포스트에서는 비어 있어요.
- `hashtags` (string[]) — 캡션에서 파싱한 해시태그.
- `mentions` (string[]) — 캡션에서 멘션된 핸들.
- `transcript` (string | null) — 음성 전사문. include_transcript=true일 때만 채워져요.

#### 예시

```console
$ solari tiktok account posts username=innisfree_official limit=2
```

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

```json
{
  "found": true,
  "account_id": "019b2137-f76e-7b33-9437-26044fa7b1ed",
  "username": "innisfree_official",
  "total": 87,
  "has_more": true,
  "items": [
    {
      "post_id": "01a0631e-f0df-7e9d-a09b-d84bc31d3834",
      "video_id": "7680375687139642645",
      "url": "https://www.tiktok.com/@innisfree_official/video/7680375687139642645",
      "account_id": "019b2137-f76e-7b33-9437-26044fa7b1ed",
      "username": "innisfree_official",
      "post_type": "video",
      "posted_at": "2026-09-02T12:00:00Z",
      "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  Green Tea Ceramide Mist: Touch-free, fa …",
      "duration_seconds": 23,
      "width": 1080,
      "height": 1920,
      "play_count": 493,
      "like_count": 37,
      "comment_count": 2,
      "share_count": 0,
      "collect_count": 3,
      "is_ad": false,
      "is_pinned": false,
      "aigc_label_type": null,
      "original_language_code": null,
      "cover_url": "https://smr-images-b.bzine.co/tiktok/users/019b2137-f76e-7b33-9437-26044fa7b1ed/posts/01a0631e-f0df-7e9d-a09b-d84bc31d3834/medias/cover.jpg",
      "video_url": "https://smr-images-a.bzine.co/tiktok/users/019b2137-f76e-7b33-9437-26044fa7b1ed/posts/01a0631e-f0df-7e9d-a09b-d84bc31d3834/medias/origin.mp4",
      "images": [],
      "hashtags": [],
      "mentions": [],
      "transcript": null
    },
    "… 1 more"
  ],
  "fetched_on_demand": false
}
```

#### MCP 호출로 쓰면

```json
{
  "name": "solari_tiktok_account_posts",
  "arguments": {
    "username": "innisfree_official",
    "limit": 2
  }
}
```

#### 주의사항

- 전사문은 길기 때문에 include_transcript는 기본적으로 꺼져 있어요. 음성 내용이 중요할 때만 켜세요.
- 페이지당 최대 200개.

#### 관련 도구

- [`solari_tiktok_account_profile`](https://solari.sh/docs/tools/tiktok-account-profile.md?lang=ko)
- [`solari_tiktok_content_detail`](https://solari.sh/docs/tools/tiktok-content-detail.md?lang=ko)
- [`solari_instagram_account_posts`](https://solari.sh/docs/tools/instagram-account-posts.md?lang=ko)

### solari tiktok content detail

> TikTok 포스트 하나의 전체 정보.

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

TikTok 포스트 하나의 상세 정보. solari_tiktok_account_posts 엔트리와 같은 item 형태이며, 전사문이 있으면 함께 담겨요. 포스트는 post_id(solari_tiktok_account_posts, solari_tiktok_content_search, solari_tiktok_account_profile 이 반환하는 SOLARI post UUID), video_id(공개된 TikTok 숫자 video id), 또는 url(vm.tiktok.com·vt.tiktok.com 단축 링크를 포함한 모든 공개 TikTok 포스트 URL. upstream에서 해석돼요)로 지정해요. 아직 추적 중이 아닌 video_id나 url은 첫 요청 때 실시간으로 수집하며(10~40초 소요) 이 경우 fetched_on_demand=true로 표시돼요. 포스트가 존재하지 않거나 비공개일 때, 또는 post_id를 알 수 없을 때 item은 null이에요. 로그인된 SOLARI 계정이면 누구나 사용할 수 있어요.

**언제 쓰나** — post_id, video_id, 또는 공개 URL로 포스트 하나를 열 때.

**무엇이 돌아오나** — account-posts 형태의 item 하나. 전사문이 있으면 함께 담겨요.

#### 파라미터

- `post_id` (string, 선택, uuid, pattern ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$) — SOLARI post_id UUID. 이 값, video_id, url 중 하나를 넘기세요.
- `video_id` (string, 선택, pattern ^\d{15,20}$) — 공개된 TikTok 숫자 video id. 포스트 URL의 /video/ 또는 /photo/ 뒤의 숫자예요. post_id가 설정되면 무시돼요.
- `url` (string, 선택, ≤ 512 chars) — https://www.tiktok.com/@<handle>/video/<id> 같은 공개 TikTok 포스트 URL, 또는 vm.tiktok.com / vt.tiktok.com 단축 링크. post_id나 video_id가 설정되면 무시돼요.

#### 응답

##### `Response`

- `item` (object | null) — 포스트. 존재하지 않거나 비공개면 null이에요.
- `fetched_on_demand` (boolean) — 이 요청이 해당 포스트를 처음 끌어온 경우 true.

##### `item`

- `post_id` (uuid) — SOLARI post id. Instagram post id와는 다른 네임스페이스예요.
- `video_id` (string) — 공개된 TikTok 숫자 id — /video/ 또는 /photo/ 뒤의 숫자.
- `url` (string) — 공개 TikTok 퍼머링크.
- `account_id` (uuid) — 작성자의 TikTok account_id.
- `username` (string) — 작성자 핸들.
- `post_type` (string) — video(단일 클립) 또는 carousel(이미지 슬라이드쇼).
- `posted_at` (timestamp) — 게시 시각(UTC).
- `caption` (string) — 캡션 텍스트.
- `duration_seconds` (integer) — 영상 길이.
- `width / height` (integer) — 영상 해상도.
- `play_count` (integer) — 재생 수.
- `like_count` (integer) — 좋아요 수.
- `comment_count` (integer) — 댓글 수.
- `share_count` (integer) — 공유 수.
- `collect_count` (integer) — 저장 수.
- `is_ad` (boolean) — TikTok이 해당 포스트를 광고로 표시했는지 여부.
- `is_pinned` (boolean) — 프로필 상단 고정 여부.
- `aigc_label_type` (string | null) — TikTok이 붙인 경우의 AI 생성 콘텐츠 라벨.
- `original_language_code` (string | null) — 원본 언어 코드.
- `cover_url` (string) — 커버 이미지 URL.
- `video_url` (string) — 영상 파일 URL.
- `images` (string[]) — 캐러셀 슬라이드. video 포스트에서는 비어 있어요.
- `hashtags` (string[]) — 캡션에서 파싱한 해시태그.
- `mentions` (string[]) — 캡션에 멘션된 핸들.
- `transcript` (string | null) — 음성 전사문. include_transcript=true일 때만 채워져요.

#### 예시

```console
$ solari tiktok content detail video_id=7680375687139642645 include_transcript=true
```

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

```json
{
  "item": {
    "post_id": "01a0631e-f0df-7e9d-a09b-d84bc31d3834",
    "video_id": "7680375687139642645",
    "url": "https://www.tiktok.com/@innisfree_official/video/7680375687139642645",
    "account_id": "019b2137-f76e-7b33-9437-26044fa7b1ed",
    "username": "innisfree_official",
    "post_type": "video",
    "posted_at": "2026-09-02T12:00:00Z",
    "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  Green Tea Ceramide Mist: Touch-free, fa …",
    "duration_seconds": 23,
    "width": 1080,
    "height": 1920,
    "play_count": 493,
    "like_count": 37,
    "comment_count": 2,
    "share_count": 0,
    "collect_count": 3,
    "is_ad": false,
    "is_pinned": false,
    "aigc_label_type": null,
    "original_language_code": null,
    "cover_url": "https://smr-images-b.bzine.co/tiktok/users/019b2137-f76e-7b33-9437-26044fa7b1ed/posts/01a0631e-f0df-7e9d-a09b-d84bc31d3834/medias/cover.jpg",
    "video_url": "https://smr-images-c.bzine.co/tiktok/users/019b2137-f76e-7b33-9437-26044fa7b1ed/posts/01a0631e-f0df-7e9d-a09b-d84bc31d3834/medias/origin.mp4",
    "images": [],
    "hashtags": [],
    "mentions": [],
    "transcript": null
  },
  "fetched_on_demand": false
}
```

#### MCP 호출로 쓰면

```json
{
  "name": "solari_tiktok_content_detail",
  "arguments": {
    "video_id": "7680375687139642645"
  }
}
```

#### 주의사항

- vm.tiktok.com과 vt.tiktok.com 단축 링크를 받으며, upstream에서 해석돼요.
- 추적 중이 아닌 video_id나 URL은 첫 요청 때 실시간으로 수집해요 — 10~40초가 걸려요.

#### 관련 도구

- [`solari_tiktok_content_batch`](https://solari.sh/docs/tools/tiktok-content-batch.md?lang=ko)
- [`solari_tiktok_account_posts`](https://solari.sh/docs/tools/tiktok-account-posts.md?lang=ko)

### solari tiktok content batch

> 한 번의 호출로 TikTok 포스트 id를 최대 100개까지 실제 데이터로 채워요.

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

solari_tiktok_content_detail의 배치 버전. TikTok 포스트를 SOLARI 포스트 UUID로 한 번에 최대 100개까지 채워서 반환하며, 항목 형태는 solari_tiktok_account_posts의 항목과 같아요. 추적 중이 아닌 id는 빠지므로 found가 요청한 개수보다 적을 수 있어요. 전사문은 길기 때문에 include_transcript는 기본적으로 꺼져 있어요. solari_tiktok_account_posts, solari_tiktok_content_search, solari_tiktok_account_profile이 준 post_id 목록을 그대로 넣으면 돼요. TikTok post_ids는 Instagram post_ids와 별개예요. 로그인한 모든 SOLARI 계정에서 사용할 수 있어요.

**언제 쓰나** — 검색이나 계정 포스트에서 얻은 id 목록을 한꺼번에 펼칠 때.

**무엇이 돌아오나** — 요청한 id 중에서 찾은 포스트.

#### 파라미터

- `post_ids` (uuid[], 필수, 1–100 items, uuid) — 채울 SOLARI 포스트 UUID. 호출당 최대 100개. TikTok video id가 아니에요.
- `sort` (enum, 선택, 기본값 "recent") — 항목 정렬: posted_at 내림차순(recent) 또는 engagement 내림차순. 값: `recent`, `engagement`.
- `include_transcript` (boolean, 선택, 기본값 false) — 각 항목에 음성 전사문을 붙여요. 전사문이 길어서 기본값은 꺼짐.

#### 응답

##### `Response`

- `requested` (integer) — 보낸 id 개수.
- `found` (integer) — 찾아낸 개수.
- `items` (object[]) — 찾은 포스트.

##### `items[]`

- `post_id` (uuid) — SOLARI 포스트 id. Instagram 포스트 id와는 다른 네임스페이스예요.
- `video_id` (string) — 공개 숫자 TikTok id — /video/ 또는 /photo/ 뒤에 오는 숫자.
- `url` (string) — 공개 TikTok 퍼머링크.
- `account_id` (uuid) — 작성자의 TikTok account_id.
- `username` (string) — 작성자 핸들.
- `post_type` (string) — video(단일 클립) 또는 carousel(이미지 슬라이드쇼).
- `posted_at` (timestamp) — 게시 시각(UTC).
- `caption` (string) — 캡션 텍스트.
- `duration_seconds` (integer) — 영상 길이.
- `width / height` (integer) — 영상 해상도.
- `play_count` (integer) — 재생 수.
- `like_count` (integer) — 좋아요 수.
- `comment_count` (integer) — 댓글 수.
- `share_count` (integer) — 공유 수.
- `collect_count` (integer) — 저장 수.
- `is_ad` (boolean) — TikTok이 이 포스트를 광고로 표시했는지 여부.
- `is_pinned` (boolean) — 프로필 상단에 고정됨.
- `aigc_label_type` (string | null) — TikTok이 붙인 경우의 AI 생성 콘텐츠 라벨.
- `original_language_code` (string | null) — 원본 언어 코드.
- `cover_url` (string) — 커버 이미지 URL.
- `video_url` (string) — 영상 파일 URL.
- `images` (string[]) — 캐러셀 슬라이드. video 포스트에서는 비어 있어요.
- `hashtags` (string[]) — 캡션에서 파싱한 해시태그.
- `mentions` (string[]) — 캡션에서 멘션된 핸들.
- `transcript` (string | null) — 음성 전사문. include_transcript=true일 때만 채워져요.

#### 예시

```console
$ solari tiktok content batch post_ids='["01a0631e-f0df-7e9d-a09b-d84bc31d3834"]'
```

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

```json
{
  "requested": 1,
  "found": 1,
  "items": [
    {
      "post_id": "01a0631e-f0df-7e9d-a09b-d84bc31d3834",
      "video_id": "7680375687139642645",
      "url": "https://www.tiktok.com/@innisfree_official/video/7680375687139642645",
      "account_id": "019b2137-f76e-7b33-9437-26044fa7b1ed",
      "username": "innisfree_official",
      "post_type": "video",
      "posted_at": "2026-09-02T12:00:00Z",
      "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  Green Tea Ceramide Mist: Touch-free, fa …",
      "duration_seconds": 23,
      "width": 1080,
      "height": 1920,
      "play_count": 493,
      "like_count": 37,
      "comment_count": 2,
      "share_count": 0,
      "collect_count": 3,
      "is_ad": false,
      "is_pinned": false,
      "aigc_label_type": null,
      "original_language_code": null,
      "cover_url": "https://smr-images-b.bzine.co/tiktok/users/019b2137-f76e-7b33-9437-26044fa7b1ed/posts/01a0631e-f0df-7e9d-a09b-d84bc31d3834/medias/cover.jpg",
      "video_url": "https://smr-images-b.bzine.co/tiktok/users/019b2137-f76e-7b33-9437-26044fa7b1ed/posts/01a0631e-f0df-7e9d-a09b-d84bc31d3834/medias/origin.mp4",
      "images": [],
      "hashtags": [],
      "mentions": [],
      "transcript": null
    }
  ]
}
```

#### MCP 호출로 쓰면

```json
{
  "name": "solari_tiktok_content_batch",
  "arguments": {
    "post_ids": [
      "01a0631e-f0df-7e9d-a09b-d84bc31d3834"
    ]
  }
}
```

#### 주의사항

- SOLARI 포스트 UUID만 받아요. 숫자로 된 TikTok video id는 여기 들어가지 않아요 — 그건 content detail에 video_id로 넣으세요.
- TikTok 포스트 id와 Instagram 포스트 id는 별개의 네임스페이스예요.

#### 관련 도구

- [`solari_tiktok_content_detail`](https://solari.sh/docs/tools/tiktok-content-detail.md?lang=ko)
- [`solari_tiktok_content_search`](https://solari.sh/docs/tools/tiktok-content-search.md?lang=ko)

### solari tiktok content search

> TikTok 캡션과 영상 전사문을 가로지르는 키워드 검색.

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

추적 중인 TikTok 포스트에 대한 렉시컬 키워드 검색. 캡션과 영상 전사문에 매칭하며(한국어 분석 + n-gram 부분 일치), 관련도 순으로 정렬되고 매치 하이라이트가 함께 와요. 각 item은 post_id, video_id, url, 작성자 account_id/username, caption, transcription_text, post_type, posted_at, 재생/좋아요/댓글/공유/저장 수, follower_count, duration_seconds, is_ad, cover_url, score, highlight를 담아요. post_id는 solari_tiktok_content_detail이나 solari_tiktok_content_batch에, 계정 참조는 solari_tiktok_account_* 툴에 넘기면 돼요. 커버리지: KR, JP, US, TW 리전만 검색할 수 있고 대략 최근 6개월치 포스트를 담아요. total은 10,000까지 정확하고 거기서 포화해요. since/until(UTC 날짜)로 범위를 좁혀요. 로그인된 SOLARI 계정이면 누구나 사용할 수 있어요.

**언제 쓰나** — 주제로, 또는 화면에서 실제로 말한 내용으로 TikTok 포스트를 찾을 때.

**무엇이 돌아오나** — 관련도 순 히트. 하이라이트와 전사문 텍스트 포함.

#### 파라미터

- `query` (string, 필수) — 캡션과 영상 전사문에 매칭되는 자유 텍스트 키워드 쿼리.
- `region` (enum, 선택, 기본값 "KR") — 검색할 리전. 이 네 개 리전만 인덱싱되어 있어요. 값: `KR`, `JP`, `US`, `TW`.
- `limit` (integer, 선택, ≥ 1) — 최대 히트 수, 기본값 20. 100을 넘는 값은 100으로 잘려요.
- `offset` (integer, 선택, 기본값 0, ≥ 0) — 페이지네이션 offset, 기본값 0. 9800을 넘는 값은 9800으로 잘려요.
- `since` (string, 선택, pattern ^\d{4}-\d{2}-\d{2}$) — 이 UTC 날짜 이후(당일 포함, YYYY-MM-DD)의 포스트만. 약 6개월보다 오래된 데이터는 인덱싱되지 않아요.
- `until` (string, 선택, pattern ^\d{4}-\d{2}-\d{2}$) — 이 UTC 날짜 이전(당일 포함, YYYY-MM-DD)의 포스트만.

#### 응답

##### `Response`

- `query / region` (string) — 적용된 query와 region.
- `total` (integer) — 전체 매치 수. 10,000까지 정확하고 그 뒤로는 포화해요.
- `took_ms` (integer) — 검색 소요 시간.
- `items` (object[]) — 히트 목록. score 내림차순.

##### `items[]`

- `post_id / video_id / url` (string) — 포스트 식별자와 공개 링크.
- `account_id / username` (string) — 작성 계정.
- `caption` (string) — 캡션 텍스트.
- `user_bio` (string) — 작성자 bio.
- `transcription_text` (string | null) — 음성 전사문 — 검색 대상 텍스트에 포함돼요.
- `transcription_language` (string | null) — 전사문 언어 코드.
- `post_type` (string) — video 또는 carousel.
- `posted_at` (timestamp) — 게시 시각(UTC).
- `duration_seconds` (integer) — 영상 길이.
- `play_count / like_count / comment_count / share_count / collect_count` (integer) — 인게이지먼트 스냅샷.
- `follower_count` (integer) — 작성자 팔로워 수.
- `is_ad` (boolean) — TikTok 자체 광고 플래그.
- `cover_url` (string) — 커버 이미지.
- `score` (number) — 관련도 점수.
- `highlight` (object) — 필드별 매치된 조각.

#### 예시

```console
$ solari tiktok content search query="올리브영 세일" limit=3
```

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

```json
{
  "query": "올리브영 세일",
  "region": "KR",
  "total": 4041,
  "took_ms": 29,
  "items": [
    {
      "post_id": "01a05c46-9a08-7e92-a40e-b1a039103118",
      "video_id": "7679484556189207815",
      "url": "https://www.tiktok.com/@flos_bonita/video/7679484556189207815",
      "account_id": "0196cb39-87a7-7be3-ac4a-4a80b7818a90",
      "username": "flos_bonita",
      "caption": "태닝한 산리오 키링이라니…☀️🥹💗 푸드올로지 X 산리오 콜라보 실물 너무 귀엽잖아!! 헬로키티·쿠로미·한교동·마이멜로디까지🎀 제품마다 다른 키링이라 산리오 덕후들 취향 제대로 저격💘 올영 세일 시작했으니 얼른 구경해봐요👀🛒 #푸드올로지 #태닝키티 #올리브영추천템 #올영세일",
      "user_bio": "화미 프로필 링크",
      "transcription_text": "살리오 덕후라면 절대 그냥 넘길 수 없는 영상 오늘부터 시작인 올리브영 세일과 함께 푸드올로지와 살리오 콜라보 나왔어요 이번 콜라보는 젤리 폼 앰플 젤리 3 종으로 피디아렌 앰플 젤리 글루타치원 씨 앰플 젤리 히알루론산 앰플 젤리까지 제품마다 귀여운 살리오 굿즈도 함께 만나 볼 수 있는데 헬로키티 크로미 한교동부터 마이 멜로디까지 저는 역시 헬로키티 더 쿠답게 키티 키링으로 폼구 최애 캐릭터 …",
      "transcription_language": "ko",
      "post_type": "video",
      "posted_at": "2026-08-29T16:02:22Z",
      "duration_seconds": 37,
      "play_count": 955,
      "like_count": 26,
      "comment_count": 0,
      "share_count": 0,
      "collect_count": 5,
      "follower_count": 1345,
      "is_ad": true,
      "cover_url": "https://p16-common-sign.tiktokcdn-eu.com/tos-alisg-p-0037/oEu4VAolaEBAAYjMAjBtiyCIAABiPp9TOCAME~tplv-tiktokx-origin.image?dr=10395&x-expires=1788426000&x-signature=FAP0C10M1M1gEwD4YMB03pYd0YA%3D&t=4d5b0474&ps=13740610&sh …",
      "score": 53.787056,
      "highlight": {
        "caption": [
          "헬로키티·쿠로미·한교동·마이멜로디까지🎀 제품마다 다른 키링이라 산리오 덕후들 취향 제대로 저격💘 올<mark>영</mark> <mark>세일</mark> 시작했으니 얼른 구경해봐요👀🛒 #푸드올로지 #태닝키티 #올리브영추천템 #올영세일"
        ],
        "user_bio": [],
        "transcription_text": [
          "살리오 덕후라면 절대 그냥 넘길 수 없는 영상 오늘부터 시작인 <mark>올리브</mark><mark>영</mark> <mark>세일</mark>과 함께 푸드올로지와 살리오 콜라보 나왔어요 이번 콜라보는 젤리 폼 앰플 젤리 3 종으로 피디아렌 앰플 젤리 글루타치원 씨 앰플 젤리 히알루론산 앰플 젤리까지 제품마다 귀여운 살리오 굿즈도 함께",
          "… 1 more"
        ]
      }
    },
    "… 2 more"
  ]
}
```

#### MCP 호출로 쓰면

```json
{
  "name": "solari_tiktok_content_search",
  "arguments": {
    "query": "올리브영 세일",
    "limit": 3
  }
}
```

#### 주의사항

- 인덱스는 KR, JP, US, TW를 대략 최근 6개월치로 커버해요.
- offset은 9,800에서 상한이 걸려요. 더 깊이 보려면 날짜 범위를 좁혀 다시 검색해 보세요.
- total은 10,000까지 정확하고 거기서 멈춰요.

#### 관련 도구

- [`solari_tiktok_content_aggregate`](https://solari.sh/docs/tools/tiktok-content-aggregate.md?lang=ko)
- [`solari_tiktok_content_batch`](https://solari.sh/docs/tools/tiktok-content-batch.md?lang=ko)
- [`solari_instagram_content_search`](https://solari.sh/docs/tools/instagram-content-search.md?lang=ko)

### solari tiktok content aggregate

> TikTok 포스트를 나열하는 대신 집계해요.

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

추적 중인 TikTok 포스트에 대한 건수와 인게이지먼트 집계로, 개별 포스트가 아니라 숫자로 답하는 질문에 써요: 계정별 월간 포스트 수, 특정 주제를 지배하는 해시태그, 포맷별 평균 재생 수. account, post_type, hashtag, mention, caption_keyword로 그룹핑하고, 각 그룹을 day, week, month 단위로 나눌 수 있어요. post_count는 항상 반환돼요. metrics로 like/comment/view/share/collect의 합계와 평균(view_* 지표는 재생 수를 세어요), 평균 팔로워 수, 고유 계정 수를 요청해요. 자유 텍스트 query(캡션과 영상 전사문), usernames, hashtags, mentions, post_types (video, carousel)로 대상을 좁혀요. mentions로 필터링하고 account로 그룹핑하면 특정 핸들을 태그한 계정이 무엇인지 알 수 있어요. 커버리지: KR, JP, US, TW 리전이며 대략 최근 6개월치를 보유해요. 그보다 오래된 since는 잘리며, 실제 적용된 값이 응답에 그대로 실려요. 버킷은 큰 것부터 정렬돼요. truncated=true는 limit이 반환한 것보다 더 많은 그룹이 있었다는 뜻이에요. 건수가 아니라 포스트 자체가 필요하면 solari_tiktok_content_search를 사용하세요. 로그인된 SOLARI 계정이면 누구나 사용할 수 있어요.

**언제 쓰나** — 수치 질문: 계정별 업로드 주기, 주제 내 해시태그 분포, 포맷별 평균 재생 수.

**무엇이 돌아오나** — 그룹별 건수와 인게이지먼트 집계, 큰 그룹부터.

#### 파라미터

- `region` (enum, 선택, 기본값 "KR") — 집계할 리전. 이 네 개 리전만 인덱싱되어 있어요. 값: `KR`, `JP`, `US`, `TW`.
- `group_by` (enum, 선택) — 그룹핑 기준 차원. 생략하면 필터링된 전체를 단일 total 버킷으로 집계해요. 값: `account`, `post_type`, `hashtag`, `mention`, `caption_keyword`.
- `interval` (enum, 선택) — 나눌 캘린더 간격. 단독으로 쓰면 기간당 버킷 하나를 반환하고, group_by와 함께 쓰면 각 그룹이 시계열을 가져요. 값: `day`, `week`, `month`.
- `metrics` (string[], 선택) — 항상 반환되는 post_count 외에 추가로 받을 지표. view_* 지표는 재생 수를 세어요. 지표 값은 스냅샷이라 실시간 수치보다 늦을 수 있어요. 값: `like_sum`, `like_avg`, `comment_sum`, `comment_avg`, `view_sum`, `view_avg`, `share_sum`, `share_avg`, `collect_sum`, `collect_avg`, `follower_avg`, `account_count`.
- `query` (string, 선택) — 캡션과 영상 전사문에 매칭되는 자유 텍스트 필터.
- `usernames` (string[], 선택) — 이 TikTok 핸들들로 제한해요.
- `hashtags` (string[], 선택) — 이 해시태그를 모두 가진 포스트로 제한해요.
- `mentions` (string[], 선택) — 이 핸들들을 모두 태그한 포스트로 제한해요. group_by=account와 함께 쓰면 특정 핸들을 태그한 계정의 순위를 낼 수 있어요.
- `post_types` (string[], 선택) — 이 포스트 포맷들로 제한해요. 값: `video`, `carousel`.
- `since` (string, 선택, pattern ^\d{4}-\d{2}-\d{2}$) — 이 UTC 날짜 이후의 포스트만, YYYY-MM-DD 형식이며 해당일 포함. 기본값은 183일 전이고, 이 값이 허용되는 가장 이른 경계이기도 해요.
- `until` (string, 선택, pattern ^\d{4}-\d{2}-\d{2}$) — 이 UTC 날짜 이전의 포스트만, YYYY-MM-DD 형식이며 해당일 포함.
- `limit` (integer, 선택, ≥ 1) — group_by가 지정됐을 때 반환되는 최대 그룹 수, 기본값 20. 50을 넘는 값은 50으로 잘려요.

#### 응답

##### `Response`

- `region` (string) — 집계가 수행된 리전.
- `since` (date) — 실제로 적용된 시작 날짜. 보관 기간보다 오래된 요청은 잘려서 여기에 그대로 실려요.
- `until` (date | null) — 실제로 적용된 종료 날짜.
- `group_by` (string | null) — 적용된 그룹핑 차원.
- `interval` (string | null) — 적용된 캘린더 간격.
- `total_posts` (integer) — 필터에 매칭된 포스트 수. 그룹이 겹치면 버킷 건수의 합과 다를 수 있어요.
- `truncated` (boolean) — limit이 반환한 것보다 더 많은 그룹이 있었을 때 true.
- `buckets` (object[]) — 그룹당 항목 하나, 큰 것부터.

##### `buckets[]`

- `key` (string) — 그룹 값 — 핸들, 해시태그, 포맷 등. group_by를 생략하면 단일 total 버킷이에요.
- `metrics.post_count` (integer) — 포스트 수. 항상 반환돼요.
- `metrics.like_sum / like_avg` (number | null) — 좋아요 합계와 평균. metrics로 요청했을 때만.
- `metrics.comment_sum / comment_avg` (number | null) — 댓글 합계와 평균.
- `metrics.view_sum / view_avg` (number | null) — 재생 수 합계와 평균.
- `metrics.share_sum / collect_sum` (number | null) — 공유와 저장 합계, 그리고 대응하는 _avg 변형.
- `metrics.follower_avg` (number | null) — 작성 계정들의 평균 팔로워 수.
- `metrics.account_count` (integer | null) — 그룹 내 고유 계정 수.
- `series` (object[] | null) — 기간별 분해. interval이 지정됐을 때 존재해요.

#### 예시

```console
$ solari tiktok content aggregate group_by=account query="이니스프리" metrics='["view_sum","like_avg","account_count"]' limit=5
```

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

```json
{
  "region": "KR",
  "since": "2026-03-04",
  "until": null,
  "group_by": "account",
  "interval": null,
  "total_posts": 20,
  "truncated": true,
  "buckets": [
    {
      "key": "merryview_",
      "metrics": {
        "post_count": 2,
        "like_sum": null,
        "like_avg": 2378.5,
        "comment_sum": null,
        "comment_avg": null,
        "view_sum": 179504,
        "view_avg": null,
        "share_sum": null,
        "share_avg": null,
        "collect_sum": null,
        "collect_avg": null,
        "follower_avg": null,
        "account_count": 1
      },
      "series": null
    },
    {
      "key": "_kimdayun_",
      "metrics": {
        "post_count": 1,
        "like_sum": null,
        "like_avg": 1829,
        "comment_sum": null,
        "comment_avg": null,
        "view_sum": 102000,
        "view_avg": null,
        "share_sum": null,
        "share_avg": null,
        "collect_sum": null,
        "collect_avg": null,
        "follower_avg": null,
        "account_count": 1
      },
      "series": null
    },
    "… 3 more"
  ]
}
```

#### MCP 호출로 쓰면

```json
{
  "name": "solari_tiktok_content_aggregate",
  "arguments": {
    "group_by": "account",
    "query": "이니스프리",
    "metrics": [
      "view_sum",
      "like_avg",
      "account_count"
    ],
    "limit": 5
  }
}
```

#### 주의사항

- view_* 지표는 재생 수를 세어요.
- Instagram 버전과 달리 share_*와 collect_*에 실제로 값이 채워지며, transcription_keyword 그룹핑은 없어요.
- 인덱스는 KR, JP, US, TW를 대략 최근 6개월치 커버해요. since의 하한은 183일 전이며, 그보다 오래된 값은 잘려서 응답에 그대로 실려요.

#### 관련 도구

- [`solari_tiktok_content_search`](https://solari.sh/docs/tools/tiktok-content-search.md?lang=ko)
- [`solari_instagram_content_aggregate`](https://solari.sh/docs/tools/instagram-content-aggregate.md?lang=ko)