# solari catalog instagram tag search

> 해시태그나 멘션이 들어간 게시물을 찾을 때 씁니다.

- **CLI**: `solari catalog instagram tag search`
- **MCP 도구**: `solari_catalog_instagram_tag_search`
- **권한**: `solari:read`
- **이용 가능 플랜**: 무료 체험 · Plus · Pro · Enterprise
- **크레딧**: 1

수집한 전체 기록에서 해시태그나 멘션을 정확히 일치하는 것으로 찾습니다. 본문 어디에든 들어간 키워드를 찾으려면 콘텐츠 검색을 쓰세요.

**언제 쓰나요** — 캠페인 해시태그의 도달을 보거나, 어떤 계정을 멘션한 게시물을 찾을 때.

**돌려주는 값** — 태그가 들어간 게시물. 최근에 수집한 순서입니다.

## 파라미터

- `query` (string, 필수, ≤ 200 chars) — 해시태그(#ootd) 또는 멘션(@username).
- `limit` (integer, 선택, 기본값 20, 1–1000) — 한 페이지에 받을 게시물 수.
- `cursor` (string, 선택) — 이전 페이지에서 받은 next_cursor.

## 응답

### `Response`

- `query` (string) — 실제로 조회한 태그. 앞의 #나 @는 뺍니다.
- `tag_kind` (string) — hashtag 또는 mention. 검색어를 어느 쪽으로 읽었는지 알려 줍니다.
- `matched_tags` (integer) — 저장된 표기 중 일치한 개수. 0이면 이 태그가 한 번도 수집되지 않았다는 뜻입니다.
- `items` (object[]) — 찾은 게시물.
- `found` (integer) — 상세 정보까지 불러온 게시물 수.
- `next_cursor` (string | null) — 다음 페이지를 받을 때 cursor로 넣습니다. 마지막 페이지면 null.
- `mirror_synced_at` (timestamp | null) — 태그 색인을 마지막으로 갱신한 시각(UTC).

### `items[]`

- `id` (uuid) — 게시물 id.
- `slug` (string) — Instagram shortcode.
- `text` (string) — 캡션.
- `posted_at` (timestamp) — 게시 시각(UTC).
- `username / user_id / account_id` (string) — 작성 계정.
- `like_count / comment_count` (integer) — 참여.
- `play_count` (integer | null) — 영상 재생 수.
- `media_type` (string) — 게시물 형식.
- `assets` (object[]) — 순서대로 담긴 미디어 파일. 각 파일에 asset_url, media_type, video_duration이 있습니다.
- `assets[].asset_url` (string | null) — 원본 크기 이미지나 영상을 바로 받는 다운로드 링크. 저장된 파일이 없으면 null.

## 예시

```console
$ solari catalog 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_catalog_instagram_tag_search",
  "arguments": {
    "query": "#ootd",
    "limit": 3
  }
}
```

## 주의사항

- 정렬 기준은 posted_at이 아니라 수집 시각입니다. 게시 시각이 중요하면 posted_at으로 직접 정렬하세요.
- 태그 색인은 매일 갱신됩니다. mirror_synced_at이 기준 시각입니다.
- 정확히 일치해야 찾습니다. #ootd로는 #ootdkorea가 나오지 않습니다. 멘션은 앞에 @를 붙이세요.
- likes_hidden이 true면 like_count를 쓰지 마세요. 작성자가 좋아요를 숨겨서 null이거나 실제 값이 아닐 수 있습니다.

## 관련 도구

- [`solari_catalog_instagram_content_search`](https://clip-pub.bzine.co/docs/tools/catalog-instagram-content-search.md?lang=ko)
- [`solari_insight_instagram_content_aggregate`](https://clip-pub.bzine.co/docs/tools/insight-instagram-content-aggregate.md?lang=ko)
- [`solari_insight_instagram_hashtag_posts`](https://clip-pub.bzine.co/docs/tools/insight-instagram-hashtag-posts.md?lang=ko)