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