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