# solari instagram content aggregate

> Count posts instead of listing them — by account, format, hashtag, mention, or keyword.

- **CLI**: `solari instagram content aggregate`
- **MCP tool**: `solari_instagram_content_aggregate`
- **Access**: `solari:read` — Works with any signed-in SOLARI account.

Counts and engagement rollups over tracked posts, for questions answered by numbers rather than by individual posts: posts per account per month, which hashtags dominate a topic, average likes by format. Group by account, post_type, hashtag, mention, caption_keyword, or transcription_keyword, and optionally split each group by day, week, or month. post_count always comes back; request metrics for like/comment/view sums and averages, mean follower count, and distinct account counts. Narrow the set with a free-text query, usernames, hashtags, mentions, or post_types. Filtering by mentions and grouping by account answers which accounts tagged a given handle. Coverage: regions KR, JP, US, and TW, holding roughly the most recent 6 months — a since older than that is clamped and the applied value is echoed back. Buckets are largest-first; truncated=true means more groups existed than limit returned. Use solari_instagram_content_search when the posts themselves are needed instead of counts. Works with any signed-in SOLARI account.

**When to use it** — Numeric questions: posts per account per month, which hashtags dominate a topic, average likes by format.

**What comes back** — Per-group counts and engagement rollups, largest group first.

## Parameters

- `region` (enum, optional, default "KR") — Region to aggregate. Only these four regions are indexed. Values: `KR`, `JP`, `US`, `TW`.
- `group_by` (enum, optional) — Dimension to group by. Omit to aggregate the whole filtered set into a single total bucket. Values: `account`, `post_type`, `hashtag`, `mention`, `caption_keyword`, `transcription_keyword`.
- `interval` (enum, optional) — Calendar interval to split by. Alone it returns one bucket per period; combined with group_by each group carries a series. Values: `day`, `week`, `month`.
- `metrics` (string[], optional) — Extra metrics beyond post_count, which is always returned. Metric values are snapshots and can lag live counts. Values: `like_sum`, `like_avg`, `comment_sum`, `comment_avg`, `view_sum`, `view_avg`, `follower_avg`, `account_count`.
- `query` (string, optional) — Free-text filter matched against captions, creator bios, and video transcriptions.
- `usernames` (string[], optional) — Restrict to these Instagram handles.
- `hashtags` (string[], optional) — Restrict to posts carrying every one of these hashtags.
- `mentions` (string[], optional) — Restrict to posts that tag every one of these handles. Pair with group_by=account to rank the accounts tagging a given handle.
- `post_types` (string[], optional) — Restrict to these post formats.
- `since` (string, optional, pattern ^\d{4}-\d{2}-\d{2}$) — Only posts on or after this UTC date, YYYY-MM-DD inclusive. Defaults to 183 days ago, which is also the earliest accepted bound.
- `until` (string, optional, pattern ^\d{4}-\d{2}-\d{2}$) — Only posts on or before this UTC date, YYYY-MM-DD inclusive.
- `limit` (integer, optional, ≥ 1) — Maximum groups returned when group_by is set, default 20. Values above 50 are clamped to 50.

## Response

### `Response`

- `region` (string) — Region the aggregation ran over.
- `since` (date) — Start date actually applied. A request older than the retention window is clamped and echoed back here.
- `until` (date | null) — End date actually applied.
- `group_by` (string | null) — Grouping dimension applied.
- `interval` (string | null) — Calendar interval applied.
- `total_posts` (integer) — Posts matching the filters. Can differ from the sum of bucket counts when groups overlap.
- `truncated` (boolean) — true when more groups existed than limit returned.
- `buckets` (object[]) — One entry per group, largest first.

### `buckets[]`

- `key` (string) — The group value — handle, hashtag, format, and so on. A single total bucket when group_by is omitted.
- `metrics.post_count` (integer) — Post count. Always returned.
- `metrics.like_sum / like_avg` (number | null) — Like total and mean. Only when requested via metrics.
- `metrics.comment_sum / comment_avg` (number | null) — Comment total and mean.
- `metrics.view_sum / view_avg` (number | null) — View total and mean.
- `metrics.share_sum / collect_sum` (number | null) — TikTok-only metrics; always null on Instagram.
- `metrics.follower_avg` (number | null) — Mean follower count of the authoring accounts.
- `metrics.account_count` (integer | null) — Distinct accounts in the group.
- `series` (object[] | null) — Per-period breakdown, present when interval is set.

## Example

```console
$ solari instagram content aggregate group_by=hashtag query="이니스프리" metrics='["like_avg","view_sum","account_count"]' limit=5
```

_Long strings and repeated array entries are trimmed for readability._

```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"
  ]
}
```

## As an MCP call

```json
{
  "name": "solari_instagram_content_aggregate",
  "arguments": {
    "group_by": "hashtag",
    "query": "이니스프리",
    "metrics": [
      "like_avg",
      "view_sum",
      "account_count"
    ],
    "limit": 5
  }
}
```

## Notes

- post_count always comes back. Everything else is null unless named in metrics.
- Filtering by mentions and grouping by account answers "which accounts tagged this handle?".
- The index covers KR, JP, US, and TW over roughly the most recent 6 months. since defaults to — and bottoms out at — 183 days ago; an older value is clamped and the applied value is echoed back.
- interval alone returns one bucket per period; combined with group_by, each group carries a series.
- When the posts themselves are the answer, use content search.

## Related tools

- [`solari_instagram_content_search`](https://solari.sh/docs/tools/instagram-content-search.md)
- [`solari_tiktok_content_aggregate`](https://solari.sh/docs/tools/tiktok-content-aggregate.md)