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