# solari fetch instagram hashtag posts

> 해시태그 게시물을 한 페이지 바로 수집합니다.

- **CLI**: `solari fetch instagram hashtag posts`
- **MCP 도구**: `solari_fetch_instagram_hashtag_posts`
- **권한**: `solari:read`
- **이용 가능 플랜**: 무료 체험 · Plus · Pro · Enterprise
- **크레딧**: 1

Instagram 해시태그 피드를 한 페이지 바로 수집합니다. 게시물을 저장하고 피드 순서대로 돌려줍니다. 호출할 때마다 Instagram에 요청하니 catalog tag search를 먼저 확인하세요.

**언제 쓰나요** — catalog tag search에 해시태그가 없거나 오래된 데이터만 있을 때, 또는 지금 시점의 인기 게시물이나 릴스가 필요할 때 쓰세요.

**돌려주는 값** — 그 페이지의 게시물(이미 저장됨)과 다음 페이지 cursor.

## 파라미터

- `hashtag` (string, 필수, ≤ 150 chars) — 해시태그. #은 붙여도 되고 빼도 됩니다.
- `tab` (enum, 선택) — recent, top, clips(릴스) 중 하나. 값: `recent`, `top`, `clips`.
- `cursor` (string, 선택, ≤ 8192 chars) — 이전 페이지에서 받은 next_cursor.

## 응답

### `Response`

- `ingested` (boolean) — 이번 호출에서 게시물을 하나 이상 저장했으면 true.
- `fetched_on_demand` (boolean) — 항상 true. 호출할 때마다 바로 수집합니다.
- `hashtag` (string) — 수집에 쓴 해시태그. #은 뺀 값입니다.
- `tab` (string) — 이 페이지를 가져온 피드.
- `is_hidden` (boolean) — Instagram이 이 해시태그의 피드를 주지 않으면 true. 숨겨졌거나, 제한됐거나, 없는 해시태그입니다. 이때 items는 비어 있습니다.
- `hidden_reason` (string | null) — 숨겨진 해시태그에 Instagram이 붙인 안내 문구.
- `found` (integer) — items에 담긴 게시물 수.
- `fetched_count` (integer) — Instagram이 이 페이지에서 돌려준 게시물 수. 일부를 저장하지 못하면 found보다 큽니다.
- `items` (object[]) — 이 페이지의 게시물 목록. 피드 순서.
- `next_cursor` (string | null) — 다음 페이지를 요청할 때 cursor에 넣으세요. 피드가 끝나면 null.
- `note` (string) — 다음에 일어날 일.
- `next` (string) — 나중에 같은 태그를 읽는 카탈로그 명령.

### `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 fetch instagram hashtag posts hashtag=ootd tab=top
```

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

```json
{
  "ingested": true,
  "fetched_on_demand": true,
  "hashtag": "ootd",
  "tab": "top",
  "is_hidden": false,
  "hidden_reason": null,
  "found": 1,
  "fetched_count": 1,
  "items": [
    {
      "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": []
    }
  ],
  "next_cursor": "eyJwIjoxLCJtIjoiUVZGRC4uLiJ9",
  "note": "These posts were collected live and are stored now. solari_catalog_instagram_tag_search lists them after its next daily refresh.",
  "next": "solari catalog instagram tag search query=#ootd"
}
```

## MCP 호출

```json
{
  "name": "solari_fetch_instagram_hashtag_posts",
  "arguments": {
    "hashtag": "ootd",
    "tab": "top"
  }
}
```

## 주의사항

- 한 페이지는 게시물 20~30개 정도이고 몇 초 걸립니다.
- cursor는 그 cursor를 받은 해시태그와 tab에서만 쓸 수 있습니다.
- 피드는 next_cursor가 null일 때만 끝납니다. found가 0인데 next_cursor가 있는 페이지도 올 수 있습니다. 그럴 때는 계속 다음 페이지를 요청하세요.
- 숨겨진 해시태그, 제한된 해시태그, 철자가 틀린 해시태그 모두 Instagram은 같은 응답을 줍니다. is_hidden=true이고 게시물이 없습니다. hashtag search로 철자를 확인하세요.
- 게시물은 바로 저장되지만 catalog tag search에는 다음 일일 갱신 뒤에 나옵니다.
- 방금 수집한 게시물은 미디어 파일 저장에 시간이 조금 걸려서 처음에는 asset_url이 null일 수 있습니다.
- likes_hidden이 true면 like_count를 쓰지 마세요. 작성자가 좋아요를 숨겨서 null이거나 실제 값이 아닐 수 있습니다.

## 관련 도구

- [`solari_fetch_instagram_hashtag_search`](https://clip-pub.bzine.co/docs/tools/fetch-instagram-hashtag-search.md?lang=ko)
- [`solari_catalog_instagram_tag_search`](https://clip-pub.bzine.co/docs/tools/catalog-instagram-tag-search.md?lang=ko)
- [`solari_catalog_instagram_content_batch`](https://clip-pub.bzine.co/docs/tools/catalog-instagram-content-batch.md?lang=ko)