# SOLARI

> SOLARI CLI and MCP — creator and brand intelligence from your terminal.

## Overview

With SOLARI CLI and MCP, you can use Instagram, TikTok, and Threads data that SOLARI has collected — from a terminal, a script, or an agent. catalog looks up accounts and posts SOLARI already has. insight returns rankings, similar accounts, ads, and trends SOLARI computed. fetch adds one exact handle to the catalog as an account or as posts.

```console
$ solari insight instagram account similar username=oliveyoung_official limit=10
$ solari insight instagram brand lookalike content username=innisfreeofficial limit=10
$ solari insight instagram content trend clusters region=KR since_days=7
```

## Install

**macOS**

Shell:
```bash
curl -fsSL https://solari.sh/install | sh
```
Homebrew:
```bash
brew install brandazine/solari/solari
```
npm:
```bash
npm install -g @brandazine/solari
```
uv:
```bash
uv tool install solari-cli
```
uv tool puts the CLI in its own environment and on your PATH, so it never collides with a project's dependencies.

**Windows**

PowerShell:
```powershell
irm https://solari.sh/install.ps1 | iex
```
npm:
```bash
npm install -g @brandazine/solari
```
uv:
```bash
uv tool install solari-cli
```
uv tool puts the CLI in its own environment and on your PATH, so it never collides with a project's dependencies.

**Linux**

Shell:
```bash
curl -fsSL https://solari.sh/install | sh
```
npm:
```bash
npm install -g @brandazine/solari
```
uv:
```bash
uv tool install solari-cli
```
uv tool puts the CLI in its own environment and on your PATH, so it never collides with a project's dependencies.

```console
$ solari --version
1.0.0-alpha.9
```

## Quickstart

```console
$ solari auth login          # opens a browser; sign in with your SOLARI account
$ solari                     # catalog, insight, and fetch
$ solari catalog instagram account   # a group path lists its tools
$ solari catalog instagram account search --help    # parameters, without calling

$ solari catalog instagram account search query=oliveyoung brands_only=true limit=3
```

Find an account_id, then pass it on:

```console
$ solari catalog instagram account search query=innisfree brands_only=true --json \
    | jq -r '.content[0].text | fromjson | .items[0].account_id'
018cabce-14cc-7544-8890-7811ec33ef74

$ solari insight instagram brand ad stats username=innisfreeofficial
$ solari insight instagram brand top collaborators username=innisfreeofficial limit=20
```

query_type=bio searches what accounts write about themselves:

```console
$ solari catalog instagram account search query="협찬 문의" query_type=bio region=KR limit=10
$ solari catalog instagram account search query=skincare query_type=bio brands_only=true limit=20
```

## The command model

```console
$ solari insight instagram brand              # lists the group
$ solari brand overview --help        # unambiguous trailing paths resolve while browsing
$ solari insight instagram brand overview username=innisfreeofficial   # calls
```

Arguments are key=value pairs. Arrays accept JSON or a comma-separated list.

```bash
solari catalog instagram content batch post_ids='["019f505f-…","019f5060-…"]'
solari catalog instagram content batch post_ids=019f505f-…,019f5060-…
```

- `solari help all` — Every command, tool, and parameter on one page. Add --json for a machine-readable version.
- `solari get <path ...>` — Runs a tool. A half-finished path fails instead of listing.
- `solari cache refresh` — Refresh the tool list on your machine now.

## Authentication

- `solari auth login` — Opens your browser. Where it cannot — over SSH, or when an agent is running the command — it prints the sign-in link instead.
- `solari auth list` — List the SOLARI accounts you are signed in to.
- `solari auth switch <account>` — Switch to another account you are already signed in to, without opening a browser.
- `solari auth status` — Server, account, and when the sign-in runs out. Exit code 3 means sign in again.
- `solari auth logout` — Sign out. Add --all to sign out of every account at once.

If the browser cannot hand you back to the machine you ran the command on — over SSH, or inside a container — finish signing in, then copy the address out of the browser's address bar and paste it into the prompt that is waiting for it.

## Output and piping

Results go to stdout. Prompts go to stderr, so a pipe only carries data.

- `--json` — Raw JSON. The payload is the JSON string at content[0].text.
- `--ndjson` — One JSON object per line. Envelope fields like total go to stderr.
- `--refresh` — Fetch the tool list from the server, skipping the local copy.
- `--verbose, -v` — Log progress to stderr. Secrets are hidden.

```console
$ solari insight instagram brand ad posts username=innisfreeofficial months=24 limit=200 --ndjson >> ads.ndjson
$ jq -s 'group_by(.username) | map({creator: .[0].username, posts: length})' ads.ndjson
```

## Configuration

Settings live in ~/.solari/config.json. An environment variable overrides for that one command.

```console
$ solari config list
$ solari config set server https://solari.sh
$ solari config unset server
```

- `server · SOLARI_SERVER` — SOLARI server. Default https://solari.sh.
- `cacheTtl · SOLARI_CACHE_TTL` — How long, in seconds, the tool list on your machine counts as current. Default 900; 0 always asks the server.
- `cacheShadow · SOLARI_CACHE_SHADOW` — After answering from your machine, quietly update the tool list in the background. Default true.
- `callTimeout · SOLARI_CALL_TIMEOUT` — Seconds to wait for a tool call. Default 150.
- `catalogTimeout · SOLARI_CATALOG_TIMEOUT` — Seconds to wait for the tool list. Default 8.
- `SOLARI_TOKEN` — A bearer access token (from solari auth token) that stands in for the stored sign-in on every command. See From your own code.
- `SOLARI_HOME` — Keep SOLARI's files somewhere other than ~/.solari.
- `SOLARI_NO_UPDATE_CHECK=1` — Turn the daily update check off entirely. NO_UPDATE_NOTIFIER=1 does the same.

## Agents

```text
set up solari.sh/get-started.md
```

solari init registers the CLI with agents on this machine. solari init --remove undoes it.

```bash
solari init            # checkbox of every CLI (all on; space toggles, enter installs)
solari init claude     # just one target
solari init --yes      # skip the picker, install all
solari init --remove
```

Use the CLI in a terminal, in scripts, and with agents that run commands. Use MCP for apps that connect to servers themselves, like Claude Desktop and ChatGPT.

### Machine-readable docs

Add .md to any page URL. The whole reference is also one file.

- `/get-started.md` — Agent setup page.
- `/llms.txt` — An index of the documentation, in the llms.txt format.
- `/llms-full.txt` — The entire documentation — guide and every tool — concatenated into one Markdown file.
- `/docs/tools.md` — Any page, as Markdown. Add ?lang=ko or ?lang=ja for the other languages.

## From your own code

The same read-only tools the CLI runs are served as a REST API at https://solari.sh/mcp/api/v1, with official TypeScript and Python SDKs on top, and as an MCP server for agents. One access token works for all of them.

### Get a token

```console
$ solari auth token
$ solari auth token --json
```

Prints the access token of the signed-in account, refreshing it first when it has run out. --json adds expires_at, the endpoint, and the account. A token is good for eight hours; treat it as a secret, because it reads your SOLARI account until then.

### Run the CLI without a browser

```console
$ export SOLARI_TOKEN=<token from a signed-in machine>
$ solari catalog instagram account search query=nike --json
```

With SOLARI_TOKEN set, every command runs with no sign-in on that machine — CI jobs, containers, servers with no browser. The CLI never touches ~/.solari/credentials.json then, and the tool cache is keyed by the token, so app tools from another account never leak in. For jobs that outlive a token, keep a signed-in ~/.solari (or point SOLARI_HOME at one) instead: the CLI refreshes it on its own.

### Call the REST API

```console
$ curl -sS https://solari.sh/mcp/api/v1/tools/solari_catalog_instagram_account_search \
  -H "Authorization: Bearer $(solari auth token)" \
  -H "Content-Type: application/json" \
  -d '{"query":"nike","limit":3}'
```

POST the tool's arguments as a JSON object to /tools/<name>; the response is the tool's JSON payload. GET /tools lists every tool with its input schema, and errors come back as { error: { code, message } }. The full reference, including every error code, is on the API page.

### Use an SDK

```ts
import { Solari } from "@brandazine/solari-sdk";

const solari = new Solari({ token: process.env.SOLARI_TOKEN });
const hits = await solari.tools.catalog.instagram.account.search({ query: "nike", limit: 3 });
```

```python
from solari_sdk import Solari

solari = Solari()  # reads SOLARI_TOKEN
hits = solari.tools.catalog.instagram.account.search(query="nike", limit=3)
```

npm install @brandazine/solari-sdk, or pip install solari-sdk. Both are thin wrappers over the REST API with no dependencies; dotted paths join into tool names under the solari_ prefix.

### Or MCP from code

Any MCP client can also call https://solari.sh/mcp directly with the same bearer token. The endpoint is stateless, so a single tools/call request works without an initialize handshake.

## Connect over MCP

Remote MCP address:

```text
https://solari.sh/mcp
```

The first connection opens a browser to sign in.

### Claude Desktop

Open Settings and choose Customize at the bottom of the sidebar.

![The Claude Desktop settings sidebar, with Customize at the bottom.](https://finder-dev-pub.bzine.co/docs/claude-desktop-settings.webp)

_Settings → Customize_

Go to Connectors, press Add, and fill in the dialog: a name for the connectors list, and the address above.

![The Add custom connector dialog in Claude Desktop, with a name and the SOLARI MCP address filled in.](https://finder-dev-pub.bzine.co/docs/claude-desktop-add-connector.webp)

_Connectors → Add → Add custom connector_

Continue walks you through sign-in once. After that SOLARI sits in your connectors list and its tools are available in any chat. claude.ai works the same way.

### Claude Code

```bash
claude mcp add --transport http solari https://solari.sh/mcp
```

Claude Code asks you to sign in the first time it reaches the server. /mcp shows the connection and lets you start that yourself.

### ChatGPT

ChatGPT connects the same way as Claude Desktop: add the address as a custom connector under Settings → Connectors, then sign in. Custom connectors are a paid-plan feature in ChatGPT.

### Other hosts

Other apps that support remote MCP servers can connect too. Most of them take an entry like this in their settings file:

```json
{
  "mcpServers": {
    "solari": {
      "url": "https://solari.sh/mcp"
    }
  }
}
```

> Some apps can only run MCP servers installed on your own machine. Those cannot reach SOLARI directly — use the CLI instead.

## Errors and exit codes

- `0` — Success.
- `1` — The tool or the server failed.
- `2` — You typed something the CLI could not use — an unknown path, a missing argument, or a bad value.
- `3` — You need to sign in. Only a person can finish the browser sign-in, so an agent should say so rather than keep trying.

### Common tool errors

- `auth expired, reconnect the connector` — Your sign-in ran out. Run solari auth login again, or reconnect the connector in your app.
- `SOLARI access denied (403)` — SOLARI refused the call. Sign in again.
- `rate limited, retry shortly` — Too many calls in a short window. Wait a moment and try again.
- `SOLARI upstream timed out` — The call took too long — 90 seconds for most tools, 120 for the aggregate and trend-cluster ones. Narrow the range or lower the limit and try again.

## Data coverage

- content search and content aggregate: KR, JP, US, TW, about the last 6 months.
- Account, brand, and post tools: full history, no region cap.
- KR has the deepest coverage of every region.
- Counts are exact up to 10,000. TikTok search stops paging at 9,800.

### Identifiers

- account_id is per platform. Instagram and TikTok ids are not interchangeable.
- Pass account_id or username. account_id wins if both are set.
- post_id is per platform. Public ids are slug (Instagram) or video_id (TikTok).

## FAQ

### I want to change SOLARI data.

No. Every tool is read-only.

### I want to use this with Claude.

Yes. Run solari init to introduce the CLI to the agents on your machine, or connect to the MCP server directly.

### Search says there are no results.

Account search matches the username or display name as written. For content search, use KR, JP, US, or TW, and dates inside the last six months.

### I want to know if there's a fee.

SOLARI CLI is free to use for now. We will announce pricing before anything changes.

## Tool reference

Every CLI and MCP tool, grouped as catalog (collected rows), insight (SOLARI-computed answers), and fetch (ingest one handle as an account or as posts). CLI paths use spaces; MCP names use underscores.

### solari catalog instagram account search

> Find collected Instagram accounts by username, name, or a phrase in their bio. Use this to get an account_id.

- **CLI**: `solari catalog instagram account search`
- **MCP tool**: `solari_catalog_instagram_account_search`
- **Access**: `solari:read` — Works with any signed-in SOLARI account.
- **Required plan**: Free
- **Credit**: 0

Search SOLARI's catalog of collected Instagram accounts by username, display name, or words in their bio. This is not Instagram's own search. The account_id you get is what the other Instagram tools need.

**When to use it** — When you have a name or username, and not an account_id yet.

**What comes back** — Matching accounts, closest first.

#### Parameters

- `query` (string, required) — Username, display name, or — with query_type=bio — words from the profile bio.
- `query_type` (enum, optional, default "auto") — Where to look: username, display name, bio, or all of those (auto). Values: `auto`, `username`, `full_name`, `bio`.
- `brands_only` (boolean, optional, default false) — Only known brand accounts. Turn this on when looking up a brand.
- `limit` (integer, optional, ≥ 1) — How many accounts to return.
- `region` (string, optional, ≤ 8 chars) — Country code such as KR or JP. Leave this off to search everywhere.

#### Response

##### `Response`

- `found` (boolean) — Whether anyone matched.
- `items` (object[]) — Accounts that matched, closest first.

##### `items[]`

- `account_id` (uuid) — account_id for the other Instagram tools.
- `username` (string) — Instagram username.
- `full_name` (string) — Display name.
- `biography` (string) — Profile bio.
- `follower_count` (integer) — Follower count.
- `region` (string) — Region code.
- `is_verified` (boolean) — Verification badge.
- `profile_pic_url` (string) — Profile picture URL.

#### Example

```console
$ solari catalog instagram account search query=oliveyoung brands_only=true limit=5
```

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

```json
{
  "found": true,
  "items": [
    {
      "account_id": "018cab6d-1648-7071-9734-c47a2be2fd19",
      "username": "oliveyoung_official",
      "full_name": "올리브영 OLIVE YOUNG",
      "biography": "ALL LIVE YOUNG 🫒\nALL LIVE BETTER @olivebetter.official",
      "follower_count": 1199628,
      "region": "KR",
      "is_verified": true,
      "profile_pic_url": "https://dcr.bzine.co/instagram/users/oliveyoung_official/profile-picture"
    },
    {
      "account_id": "018dc63c-31b5-740f-bde0-2c00931385e1",
      "username": "oliveyoung_global",
      "full_name": "OLIVE YOUNG Global",
      "biography": "Korea's No.1 Health & Beauty Store\n✈️ FREE SHIPPING on orders over $60",
      "follower_count": 535949,
      "region": "KR",
      "is_verified": true,
      "profile_pic_url": "https://dcr.bzine.co/instagram/users/oliveyoung_global/profile-picture"
    },
    {
      "account_id": "018cabcf-e60e-70af-95eb-eff777ce5195",
      "username": "oliveyoung_magazine",
      "full_name": "올리브영 매거진",
      "biography": "내 일상과 가까운 뷰티 매거진",
      "follower_count": 142316,
      "region": "KR",
      "is_verified": false,
      "profile_pic_url": "https://dcr.bzine.co/instagram/users/oliveyoung_magazine/profile-picture"
    },
    "… 2 more"
  ]
}
```

#### As an MCP call

```json
{
  "name": "solari_catalog_instagram_account_search",
  "arguments": {
    "query": "oliveyoung",
    "brands_only": true,
    "limit": 5
  }
}
```

#### Notes

- The name has to appear in the username or display name. Nicknames and abbreviations usually miss.
- For a brand, set brands_only=true so fan accounts drop out.
- region keeps only the specified country. Leave it off unless you need one.

#### Related tools

- [`solari_catalog_instagram_account_profile`](https://finder-dev-pub.bzine.co/docs/tools/catalog-instagram-account-profile.md)
- [`solari_catalog_instagram_account_posts`](https://finder-dev-pub.bzine.co/docs/tools/catalog-instagram-account-posts.md)
- [`solari_catalog_tiktok_account_search`](https://finder-dev-pub.bzine.co/docs/tools/catalog-tiktok-account-search.md)

### solari insight instagram account similar

> Use this to find similar Instagram accounts.

- **CLI**: `solari insight instagram account similar`
- **MCP tool**: `solari_insight_instagram_account_similar`
- **Access**: `solari:read` — Works with any signed-in SOLARI account.
- **Required plan**: Free
- **Credit**: 0

Find Instagram accounts in a similar network. This is about nearby accounts, not who has run ads together.

**When to use it** — When you want similar accounts. For ad partners, use brand top collaborators.

**What comes back** — Similar accounts, closest first.

#### Parameters

- `username` (string, required) — Instagram username, without @.
- `limit` (integer, optional, ≥ 1) — How many similar accounts to return.

#### Response

##### `Response`

- `user_id` (uuid) — Id of the starting account.
- `user` (object) — Profile of the starting account.
- `params` (object) — Settings that were actually used.
- `results` (object[]) — Similar accounts, score descending.
- `diagnostics` (object) — How the search was run.

##### `results[]`

- `user_id` (uuid) — account_id of the similar account.
- `username` (string) — Username.
- `full_name / bio` (string) — Display name and bio.
- `score` (number) — Similarity score for this response.
- `follower_count` (integer) — Follower count.
- `region` (string) — Region code.
- `has_collaborated` (boolean) — Whether they have an ad collab with the seed.
- `last_collaboration_date` (date | null) — Most recent collab date.
- `recent_media` (object[]) — Recent post previews.

#### Example

```console
$ solari insight instagram account similar username=oliveyoung_official limit=8
```

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

```json
{
  "user_id": "018cab6d-1648-7071-9734-c47a2be2fd19",
  "user": {
    "user_id": "018cab6d-1648-7071-9734-c47a2be2fd19",
    "username": "oliveyoung_official",
    "full_name": "올리브영 OLIVE YOUNG",
    "profile_pic_url": "https://dcr.bzine.co/instagram/users/oliveyoung_official/profile-picture",
    "follower_count": 1199628,
    "region": "KR",
    "is_verified": null
  },
  "params": {
    "k": 8,
    "hops": 3,
    "max_rank_to_use": 25
  },
  "results": [
    {
      "user_id": "018cabd4-926b-7a58-b0cb-11dfc7c37006",
      "username": "gs25_official",
      "score": 0.1515,
      "profile_pic_url": "https://dcr.bzine.co/instagram/users/gs25_official/profile-picture",
      "follower_count": 1017802,
      "median_views": null,
      "full_name": "대한민국 대표 편의점 GS25",
      "bio": "더 재미있게 더 실속있게\n오늘 가장 최신의 트렌드를 만나는\n#25매거진 #재미있는GS25 #라이프스타일플랫폼",
      "region": "KR",
      "has_collaborated": false,
      "last_collaboration_date": null,
      "recent_media": [
        {
          "post_id": "01a062a3-a504-7fe5-b53f-7cd291ffceff",
          "media_type": "image",
          "source_url": "https://bzine.co/cdn-cgi/image/fit=scale-down,width=480/https://smr-images.bzine.co/users/018cabd4-926b-7a58-b0cb-11dfc7c37006/posts/01a062a3-a504-7fe5-b53f-7cd291ffceff/medias/01a062a3-a7f8-702c-994f-bd426afe5d74.jpg",
          "thumbnail_url": "https://bzine.co/cdn-cgi/image/fit=scale-down,width=480/https://smr-images.bzine.co/users/018cabd4-926b-7a58-b0cb-11dfc7c37006/posts/01a062a3-a504-7fe5-b53f-7cd291ffceff/medias/01a062a3-a7f8-702c-994f-bd426afe5d74.jpg",
          "slug": "Dcx-Nrij7IV",
          "media_url": "https://bzine.co/cdn-cgi/image/fit=scale-down,width=480/https://smr-images.bzine.co/users/018cabd4-926b-7a58-b0cb-11dfc7c37006/posts/01a062a3-a504-7fe5-b53f-7cd291ffceff/medias/01a062a3-a7f8-702c-994f-bd426afe5d74.jpg",
          "play_count": null,
          "posted_at": "2026-09-02T10:00:09+00:00"
        },
        "… 3 more"
      ],
      "collaborated_with": []
    },
    "… 7 more"
  ],
  "diagnostics": {
    "neighbors_used": 4930,
    "unique_terms": 25,
    "build_ms": 7664,
    "algorithm": "distance_weighted_jaccard",
    "max_rank_used": 25,
    "target_related_count": 25
  }
}
```

#### As an MCP call

```json
{
  "name": "solari_insight_instagram_account_similar",
  "arguments": {
    "username": "oliveyoung_official",
    "limit": 8
  }
}
```

#### Notes

- Pass a username, not an account_id.
- For who has run ads with a brand, use brand top collaborators.

#### Related tools

- [`solari_catalog_instagram_account_search`](https://finder-dev-pub.bzine.co/docs/tools/catalog-instagram-account-search.md)
- [`solari_insight_instagram_brand_top_collaborators`](https://finder-dev-pub.bzine.co/docs/tools/insight-instagram-brand-top-collaborators.md)

### solari insight instagram brand overview

> An Instagram brand's profile and ad history.

- **CLI**: `solari insight instagram brand overview`
- **MCP tool**: `solari_insight_instagram_brand_overview`
- **Access**: `solari:read` — Works with any signed-in SOLARI account.
- **Required plan**: Free
- **Credit**: 0

A brand's profile, plus the creator ids and ad post ids behind its ads. Pass those post ids to content batch to load the posts.

**When to use it** — When you are starting brand analysis. For exact ad counts, use brand ad stats.

**What comes back** — Brand profile, plus creator ids and ad post ids.

#### Parameters

- `username` (string, required) — Brand Instagram username, without @.
- `full` (boolean, optional, default false) — Return the full id lists instead of the first 20.

#### Response

##### `Response`

- `information` (object) — Brand profile: user_id, username, full_name, bio, follower_count.
- `all_influencers_id` (uuid[]) — account_ids of creators who produced ads for the brand. First 20 by default.
- `all_influencers_count` (integer) — Total creators before truncation.
- `all_influencers_truncated` (boolean) — true when the list is a preview.
- `all_campaign_posts_id` (uuid[]) — Ad post ids. First 20 by default.
- `all_campaign_posts_count` (integer) — Total posts before truncation.
- `all_campaign_posts_truncated` (boolean) — true when the list is a preview.

#### Example

```console
$ solari insight instagram brand overview username=innisfreeofficial
```

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

```json
{
  "information": {
    "user_id": "018cabce-14cc-7544-8890-7811ec33ef74",
    "username": "innisfreeofficial",
    "full_name": "INNISFREE | 이니스프리",
    "bio": "NATURE MEETS KOREAN SKIN SCIENCE",
    "follower_count": 847619,
    "brand_id": null
  },
  "all_influencers_id": [
    "01935f3d-8188-727e-a0bb-09e54aadfdac",
    "018caf6e-abfd-73da-88ad-11a56c39358b",
    "019a0061-b1d4-7adb-8ea4-1c5572dca38c",
    "… 17 more"
  ],
  "all_campaign_ids": [],
  "all_campaign_posts_id": [
    "019f505f-f8be-7e88-ae08-6fba999950b1",
    "019f5060-3449-779e-a08b-d6d49add90cd",
    "019f4342-3357-7418-916c-da1c44468308",
    "… 17 more"
  ],
  "post_id_to_campaign_id": {},
  "all_influencers_count": 93,
  "all_influencers_truncated": true,
  "all_campaign_posts_count": 100,
  "all_campaign_posts_truncated": true
}
```

#### As an MCP call

```json
{
  "name": "solari_insight_instagram_brand_overview",
  "arguments": {
    "username": "innisfreeofficial"
  }
}
```

#### Notes

- Pass a username, not an account_id. Unknown usernames return 404.
- full=true returns up to 100 ids each. For exact totals, use brand ad stats.

#### Related tools

- [`solari_insight_instagram_brand_ad_stats`](https://finder-dev-pub.bzine.co/docs/tools/insight-instagram-brand-ad-stats.md)
- [`solari_catalog_instagram_content_batch`](https://finder-dev-pub.bzine.co/docs/tools/catalog-instagram-content-batch.md)
- [`solari_insight_instagram_brand_ad_posts`](https://finder-dev-pub.bzine.co/docs/tools/insight-instagram-brand-ad-posts.md)

### solari insight instagram brand ad stats

> How much an Instagram brand has advertised.

- **CLI**: `solari insight instagram brand ad stats`
- **MCP tool**: `solari_insight_instagram_brand_ad_stats`
- **Access**: `solari:read` — Works with any signed-in SOLARI account.
- **Required plan**: Free
- **Credit**: 0

Exact counts for a brand's recent ads: sponsored posts, creators, and a play-count sum.

**When to use it** — When the answer is a number. Don't count ids from brand overview.

**What comes back** — Ad post count, creator count, and a play-count sum.

#### Parameters

- `username` (string, required) — Brand Instagram username, without @.

#### Response

##### `Response`

- `total_ad_posts` (integer) — Sponsored posts in the window. Exact.
- `unique_creator_count` (integer) — Distinct collaborating creators.
- `total_play_count` (integer) — Sum of plays.
- `play_count_covered_posts` (integer) — Posts included in the play sum. Lower than total_ad_posts means a lower bound.
- `window_months` (integer) — Length of the window in months.

#### Example

```console
$ solari insight instagram brand ad stats username=innisfreeofficial
```

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

```json
{
  "total_ad_posts": 405,
  "unique_creator_count": 360,
  "total_play_count": 27357941,
  "play_count_covered_posts": 405,
  "window_months": 3
}
```

#### As an MCP call

```json
{
  "name": "solari_insight_instagram_brand_ad_stats",
  "arguments": {
    "username": "innisfreeofficial"
  }
}
```

#### Notes

- Pass a username, not an account_id.

#### Related tools

- [`solari_insight_instagram_brand_ad_posts`](https://finder-dev-pub.bzine.co/docs/tools/insight-instagram-brand-ad-posts.md)
- [`solari_insight_instagram_brand_overview`](https://finder-dev-pub.bzine.co/docs/tools/insight-instagram-brand-overview.md)

### solari insight instagram brand ad posts

> An Instagram brand's ad posts.

- **CLI**: `solari insight instagram brand ad posts`
- **MCP tool**: `solari_insight_instagram_brand_ad_posts`
- **Access**: `solari:read` — Works with any signed-in SOLARI account.
- **Required plan**: Free
- **Credit**: 0

A brand's ad posts, with the creator attached.

**When to use it** — When you want the posts themselves, not just the totals.

**What comes back** — Ad posts. The total is exact only when sort=recent.

#### Parameters

- `username` (string, required) — Brand Instagram username, without @.
- `sort` (enum, optional, default "recent") — recent walks the full window. engagement ranks a recent slice. Values: `recent`, `engagement`.
- `months` (integer, optional, ≥ 1) — How many months back to look.
- `limit` (integer, optional, ≥ 1) — How many posts per page.
- `offset` (integer, optional, default 0, ≥ 0) — How many posts to skip.

#### Response

##### `Response`

- `items` (object[]) — Sponsored posts.
- `total` (integer) — Exact count across the window when sort=recent.
- `has_more` (boolean) — Whether there is another page.
- `ranking_window` (integer | null) — How far engagement ranking looked. Set when order covers a slice, not the whole window.

##### `items[]`

- `id` (uuid) — Post id.
- `slug` (string) — Instagram shortcode.
- `text` (string) — Caption.
- `posted_at` (timestamp) — Published at (UTC).
- `username / user_id / account_id` (string) — The authoring creator.
- `like_count / comment_count / play_count` (integer) — Engagement.
- `media_type` (string) — Post format.
- `media / media_url / thumbnail_url` (string) — Media links.
- `virtual_campaign` (object | null) — Campaign grouping, when one is resolved.

#### Example

```console
$ solari insight instagram brand ad posts username=innisfreeofficial limit=2
```

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

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

#### As an MCP call

```json
{
  "name": "solari_insight_instagram_brand_ad_posts",
  "arguments": {
    "username": "innisfreeofficial",
    "limit": 2
  }
}
```

#### Notes

- Pass a username. Unknown usernames return 404.
- sort=engagement only ranks a recent slice. ranking_window tells you how far it looked.

#### Related tools

- [`solari_insight_instagram_brand_ad_stats`](https://finder-dev-pub.bzine.co/docs/tools/insight-instagram-brand-ad-stats.md)
- [`solari_insight_instagram_account_ad_posts`](https://finder-dev-pub.bzine.co/docs/tools/insight-instagram-account-ad-posts.md)

### solari insight instagram brand top collaborators

> Creators who have collaborated with an Instagram brand.

- **CLI**: `solari insight instagram brand top collaborators`
- **MCP tool**: `solari_insight_instagram_brand_top_collaborators`
- **Access**: `solari:read` — Works with any signed-in SOLARI account.
- **Required plan**: Free
- **Credit**: 0

Creators who have run ads for a brand, ranked by how often.

**When to use it** — When you want to see who a brand has worked with. The creator-side view is account collabs.

**What comes back** — Creators ordered by collaboration count.

#### Parameters

- `account_id` (string, optional, uuid, pattern ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$) — Pass the brand's account_id or username.
- `username` (string, optional, ≤ 64 chars) — Brand username. Ignored when account_id is set.
- `promotion` (enum, optional, default "all") — All posts, promotion posts only, or non-promotion only. Values: `all`, `true_only`, `false_only`.
- `limit` (integer, optional, ≥ 1) — How many creators to return.
- `offset` (integer, optional, default 0, ≥ 0) — How many creators to skip.

#### Response

##### `Response`

- `brand_id` (uuid) — The resolved brand account_id.
- `promotion_filter` (string) — The promotion filter applied.
- `items` (object[]) — Creators, collaboration count descending.
- `total_count` (integer) — Creators matching the filter.

##### `items[]`

- `creator_id` (uuid) — Creator account_id.
- `username / full_name` (string) — Username and display name.
- `profile_pic_url` (string) — Profile picture.
- `follower_count` (integer) — Follower count.
- `collaboration_count` (integer) — Collaboration posts with the brand.

#### Example

```console
$ solari insight instagram brand top collaborators username=innisfreeofficial limit=5
```

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

```json
{
  "brand_id": "018cabce-14cc-7544-8890-7811ec33ef74",
  "promotion_filter": "all",
  "items": [
    {
      "creator_id": "0195474c-8ee3-7690-a385-71b2913e31b5",
      "username": "donge_cos",
      "full_name": "💞동이💞",
      "profile_pic_url": "https://dcr.bzine.co/instagram/users/donge_cos/profile-picture",
      "follower_count": 83354,
      "collaboration_count": 31
    },
    {
      "creator_id": "018ecc75-55d8-70a7-a348-d370aa504ed9",
      "username": "beinny_motd",
      "full_name": "베이니 BEINNY",
      "profile_pic_url": "https://dcr.bzine.co/instagram/users/beinny_motd/profile-picture",
      "follower_count": 205754,
      "collaboration_count": 29
    },
    "… 3 more"
  ],
  "total_count": 2331
}
```

#### As an MCP call

```json
{
  "name": "solari_insight_instagram_brand_top_collaborators",
  "arguments": {
    "username": "innisfreeofficial",
    "limit": 5
  }
}
```

#### Notes

- To load their posts, pass creator_id values to brand collaborator posts, 100 at a time.

#### Related tools

- [`solari_insight_instagram_brand_collaborator_posts`](https://finder-dev-pub.bzine.co/docs/tools/insight-instagram-brand-collaborator-posts.md)
- [`solari_insight_instagram_account_collabs`](https://finder-dev-pub.bzine.co/docs/tools/insight-instagram-account-collabs.md)

### solari insight instagram brand collaborator posts

> Ad posts from creators who collaborated with a brand.

- **CLI**: `solari insight instagram brand collaborator posts`
- **MCP tool**: `solari_insight_instagram_brand_collaborator_posts`
- **Access**: `solari:read` — Works with any signed-in SOLARI account.
- **Required plan**: Free
- **Credit**: 0

Load ad posts from up to 100 creators for a brand. This is all-time, not a recent window.

**When to use it** — When you need posts from many creators at once.

**What comes back** — Per-creator totals and the posts, sorted by engagement.

#### Parameters

- `account_id` (string, optional, uuid, pattern ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$) — Pass the brand's account_id or username.
- `username` (string, optional, ≤ 64 chars) — Brand username. Ignored when account_id is set.
- `account_ids` (uuid[], required, 1–100 items, uuid) — Creator account_ids to load, up to 100.

#### Response

##### `Response`

- `(top level)` (object[]) — Creators, as a top-level array.

##### `[]`

- `user_id` (uuid) — Creator account_id.
- `username / full_name` (string) — Username and display name.
- `follower_count` (integer) — Follower count.
- `post_count` (integer) — Posts targeting the brand.
- `reels_count / images_count` (integer) — Breakdown by format.
- `posts` (object[]) — The posts: id, slug, text, posted_at, like_count, comment_count, play_count.
- `like_count_avg / comment_count_avg` (number | null) — Mean engagement, when computed.

#### Example

```console
$ solari insight instagram brand collaborator posts username=innisfreeofficial account_ids='["0195474c-8ee3-7690-a385-71b2913e31b5","018ecc75-55d8-70a7-a348-d370aa504ed9"]'
```

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

```json
[
  {
    "user_id": "018ecc75-55d8-70a7-a348-d370aa504ed9",
    "username": "beinny_motd",
    "full_name": "베이니 BEINNY",
    "post_count": 29,
    "follower_count": 205754,
    "reels_count": 1,
    "images_count": 28,
    "posts": [
      {
        "id": "019c98bc-a666-717d-a5fe-ea96f1345042",
        "slug": "ByVKkIbnQ8S",
        "text": "#이니스프리 에서 새롭게 출시된 #구름블러틴트 ☁️💓\n비비드 코튼 잉크 블러버젼이에용\n.\n요즘 이런 블러틴트류 많이 출시돼서 넘 행복해요🥺💛\n이니스프리 블러틴트는 보송보송한 마무리지만 꽤 촉촉하고 가볍게 발리더라구요! 발림성 넘 좋았어요✨\n총 8가지 컬러인데 그중 제 맘에 드는 4가지 컬러는 입술에 발색해서 보여드려용 :) 특히 로즈+핑크 섞인듯한 2호 #로제핑크 완전 추천👍🏻✨\n가격은 9, …",
        "posted_at": "2019-06-05T14:02:19Z",
        "virtual_campaign": null,
        "like_count": 2399,
        "comment_count": 20,
        "play_count": null,
        "username": "beinny_motd",
        "user_id": "018ecc75-55d8-70a7-a348-d370aa504ed9"
      },
      "… 10 more"
    ],
    "like_count_avg": null,
    "comment_count_avg": null,
    "synced_at": null
  },
  "… 1 more"
]
```

#### As an MCP call

```json
{
  "name": "solari_insight_instagram_brand_collaborator_posts",
  "arguments": {
    "username": "innisfreeofficial",
    "account_ids": [
      "0195474c-8ee3-7690-a385-71b2913e31b5",
      "018ecc75-55d8-70a7-a348-d370aa504ed9"
    ]
  }
}
```

#### Notes

- account_ids can be a JSON array or a comma-separated list, up to 100.

#### Related tools

- [`solari_insight_instagram_brand_top_collaborators`](https://finder-dev-pub.bzine.co/docs/tools/insight-instagram-brand-top-collaborators.md)
- [`solari_insight_instagram_brand_overview`](https://finder-dev-pub.bzine.co/docs/tools/insight-instagram-brand-overview.md)

### solari insight instagram brand lookalike content

> Use this to find posts similar to a brand's ads.

- **CLI**: `solari insight instagram brand lookalike content`
- **MCP tool**: `solari_insight_instagram_brand_lookalike_content`
- **Access**: `solari:read` — Works with any signed-in SOLARI account.
- **Required plan**: Free
- **Credit**: 0

Find posts similar to a brand's top-performing ads. Useful for creative references.

**When to use it** — When you want references, not a measure of ad volume.

**What comes back** — Similar posts, plus the brand ads used as the starting point.

#### Parameters

- `account_id` (string, optional, uuid, pattern ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$) — Pass the brand's account_id or username.
- `username` (string, optional, ≤ 64 chars) — Brand username. Ignored when account_id is set.
- `limit` (integer, optional, ≥ 1) — How many similar posts to return.
- `region` (string, optional, default "KR") — Country code such as KR or JP.

#### Response

##### `Response`

- `items` (object[]) — Lookalike posts.
- `basis` (object[]) — The brand's own ad posts used as seeds.
- `region` (string) — Region the search was scoped to.

##### `items[] · basis[]`

- `post_id` (uuid) — Post id for other content tools.
- `slug` (string) — Shortcode from the public URL.
- `author_id` (uuid) — Author account_id.
- `username` (string) — Author username.
- `full_name` (string | null) — Display name.
- `profile_pic_url` (string | null) — Profile picture URL.
- `follower_count` (integer | null) — Author follower count.
- `region` (string | null) — Author region.
- `posted_at` (timestamp) — Published at (UTC).
- `media_type` (string) — image, video, or carousel.
- `play_count` (integer | null) — Video plays. Null for images.
- `like_count` (integer | null) — Likes.
- `text` (string | null) — Caption.
- `media_url` (string) — Media URL.
- `thumbnail_url` (string) — Thumbnail URL.
- `score` (number | null) — Ranking score for this response.
- `efficiency_score` (number | null) — Performance vs. the author's followers.
- `est_percentile` (number | null) — Region percentile, 0–1.
- `total_views_3m` (integer | null) — Author views in the last 3 months.
- `median_views_3m` (integer | null) — Author median views in the last 3 months.
- `recent_collab_brands` (string[]) — Brands the author recently collaborated with.
- `item_type` (string) — Item kind. post in these feeds.
- `content_source` (string | null) — Which feed surfaced this item.
- `is_saved` (boolean | null) — Whether it's saved in SOLARI.
- `updated_at` (timestamp | null) — When metrics were last refreshed.

#### Example

```console
$ solari insight instagram brand lookalike content username=innisfreeofficial limit=3
```

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

```json
{
  "items": [
    {
      "item_type": "content",
      "post_id": "019ecb92-a677-7421-8ed6-752efe3d99d0",
      "author_id": "0196cb39-870a-7a76-9773-0b95789c877d",
      "username": "boo_rookie",
      "full_name": null,
      "profile_pic_url": null,
      "follower_count": null,
      "region": null,
      "posted_at": "2026-06-11T08:14:37Z",
      "media_type": "video",
      "play_count": 427258,
      "like_count": null,
      "score": null,
      "efficiency_score": null,
      "est_percentile": null,
      "updated_at": null,
      "media_url": "https://smr-images-b.bzine.co/users/0196cb39-870a-7a76-9773-0b95789c877d/posts/019ecb92-a677-7421-8ed6-752efe3d99d0/medias/019ecb92-a92e-7fc8-b644-69b930f2e197.mp4",
      "thumbnail_url": "https://bzine.co/cdn-cgi/media/width=480,mode=frame,time=100ms/https://smr-images-a.bzine.co/users/0196cb39-870a-7a76-9773-0b95789c877d/posts/019ecb92-a677-7421-8ed6-752efe3d99d0/medias/019ecb92-a92e-7fc8-b644-69b930f2e1 …",
      "slug": "DZcD8KXxKwd",
      "text": null,
      "brand_match_score": null,
      "recent_collab_brands": [],
      "total_views_3m": null,
      "median_views_3m": null,
      "is_saved": null,
      "content_source": "lookalikes_by_top_ad"
    },
    "… 2 more"
  ],
  "basis": [
    {
      "item_type": "content",
      "post_id": "01a04c73-3ec3-7873-9e84-334c644abfe4",
      "author_id": "0196c474-c96e-71ad-aceb-61af051c81d3",
      "username": "hwitto_",
      "full_name": null,
      "profile_pic_url": null,
      "follower_count": null,
      "region": null,
      "posted_at": null,
      "media_type": "video",
      "play_count": 155729,
      "like_count": null,
      "score": null,
      "efficiency_score": null,
      "est_percentile": null,
      "updated_at": null,
      "media_url": "https://smr-images-a.bzine.co/users/0196c474-c96e-71ad-aceb-61af051c81d3/posts/01a04c73-3ec3-7873-9e84-334c644abfe4/medias/01a04c73-4036-7a83-a52a-97b0058e6732.mp4",
      "thumbnail_url": "https://bzine.co/cdn-cgi/media/width=480,mode=frame,time=100ms/https://smr-images.bzine.co/users/0196c474-c96e-71ad-aceb-61af051c81d3/posts/01a04c73-3ec3-7873-9e84-334c644abfe4/medias/01a04c73-4036-7a83-a52a-97b0058e6732 …",
      "slug": "DckGrZ6vZiU",
      "text": null,
      "brand_match_score": null,
      "recent_collab_brands": [],
      "total_views_3m": null,
      "median_views_3m": null,
      "is_saved": null,
      "content_source": "lookalikes_by_top_ad"
    },
    "… 5 more"
  ],
  "region": "KR"
}
```

#### As an MCP call

```json
{
  "name": "solari_insight_instagram_brand_lookalike_content",
  "arguments": {
    "username": "innisfreeofficial",
    "limit": 3
  }
}
```

#### Notes

- If basis is empty, there are no ad posts to start from yet.

#### Related tools

- [`solari_insight_instagram_brand_ad_posts`](https://finder-dev-pub.bzine.co/docs/tools/insight-instagram-brand-ad-posts.md)
- [`solari_catalog_instagram_content_search`](https://finder-dev-pub.bzine.co/docs/tools/catalog-instagram-content-search.md)

### solari catalog instagram account profile

> An Instagram account's profile, performance, and recent posts.

- **CLI**: `solari catalog instagram account profile`
- **MCP tool**: `solari_catalog_instagram_account_profile`
- **Access**: `solari:read` — Works with any signed-in SOLARI account.
- **Required plan**: Free
- **Credit**: 0

An Instagram account's profile, view metrics, and a preview of recent posts and collaborations.

**When to use it** — When you want a full picture of an account. Recent posts and collabs come with it.

**What comes back** — Profile, performance, and recent posts and collabs.

#### Parameters

- `account_id` (string, optional, uuid, pattern ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$) — Pass account_id or username.
- `username` (string, optional, ≤ 64 chars) — Instagram username. Ignored when account_id is set.

#### Response

##### `Response`

- `user_id` (uuid) — The account_id.
- `username / full_name / bio` (string) — Username, display name, and bio.
- `follower_count / following_count` (integer) — Follower and following counts.
- `total_post_count` (integer) — Lifetime post count.
- `post_count_3m` (integer) — Posts in the last 3 months.
- `is_verified` (boolean) — Verification badge.
- `account_type` (string) — Account character inferred by SOLARI (brand, creator, …).
- `median_views_cur` (integer) — Median views in the current window.
- `total_views_cur` (integer) — Total views in the current window.
- `ad_count_cur` (integer) — Sponsored posts in the current window.
- `median_views_growth_m1` (number) — Median-view change vs. the previous month, as a ratio.
- `total_views_growth_m1` (number) — Total-view change vs. the previous month, as a ratio.
- `median_views_region_pct` (number) — Median-view percentile within the region, 0–1.
- `total_views_region_pct` (number) — Total-view percentile within the region, 0–1.
- `recent_posts` (object[]) — Recent post previews.
- `recent_collabs` (object[]) — Recent ad-collaboration previews.
- `fetched_on_demand` (boolean) — true if the account was fetched live on this call.

#### Example

```console
$ solari catalog instagram account profile username=innisfreeofficial
```

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

```json
{
  "user_id": "018cabce-14cc-7544-8890-7811ec33ef74",
  "username": "innisfreeofficial",
  "full_name": "INNISFREE | 이니스프리",
  "bio": "NATURE MEETS KOREAN SKIN SCIENCE",
  "profile_pic_url": "https://dcr.bzine.co/instagram/users/innisfreeofficial/profile-picture",
  "follower_count": 847619,
  "total_post_count": 4131,
  "post_count_3m": 100,
  "following_count": 17,
  "is_verified": true,
  "median_views_cur": 12409,
  "ad_count_cur": 0,
  "total_views_cur": 685771,
  "median_views_growth_m1": 0.04956440835659308,
  "total_views_growth_m1": 0.39407867587418205,
  "median_views_region_pct": 0.1736183168163037,
  "total_views_region_pct": 0.1457900950723917,
  "recent_posts": [
    {
      "post_id": "01a06275-d974-7fda-98ee-dd3ee15b4dcf",
      "slug": "DcyMAmUh6FZ",
      "media_type": "video",
      "media_url": "https://smr-images-b.bzine.co/users/018cabce-14cc-7544-8890-7811ec33ef74/posts/01a06275-d974-7fda-98ee-dd3ee15b4dcf/medias/01a06275-db2b-77f7-a020-b4beb744771f.mp4",
      "thumbnail_url": "https://bzine.co/cdn-cgi/media/width=480,mode=frame,time=0ms/https://smr-images.bzine.co/users/018cabce-14cc-7544-8890-7811ec33ef74/posts/01a06275-d974-7fda-98ee-dd3ee15b4dcf/medias/01a06275-db2b-77f7-a020-b4beb744771f.m …",
      "text": "Deeply hydrated skin—NO OFF HOURS. 💚\nwherever the day takes MINGYU (@min9yu_k)—his hydration stays SUPERCHARGED ⚡️\n\nGreen Tea Ceramide Milk: Lightweight milky toner that won‘t clog your pores\nGreen Tea Ceramide Mist: Tou …",
      "play_count": 22467,
      "like_count": 3224,
      "video_media_count": 0,
      "media_count": 1
    },
    "… 5 more"
  ],
  "recent_collabs": [],
  "account_type": "brand",
  "fetched_on_demand": false
}
```

#### As an MCP call

```json
{
  "name": "solari_catalog_instagram_account_profile",
  "arguments": {
    "username": "innisfreeofficial"
  }
}
```

#### Notes

- This reads the catalog only. If the username is missing, call solari fetch instagram account username=… then retry.
- A not-found error means the handle is not in the catalog.

#### Related tools

- [`solari_catalog_instagram_account_posts`](https://finder-dev-pub.bzine.co/docs/tools/catalog-instagram-account-posts.md)
- [`solari_insight_instagram_account_collabs`](https://finder-dev-pub.bzine.co/docs/tools/insight-instagram-account-collabs.md)
- [`solari_catalog_tiktok_account_profile`](https://finder-dev-pub.bzine.co/docs/tools/catalog-tiktok-account-profile.md)

### solari catalog instagram account posts

> Posts from an Instagram account.

- **CLI**: `solari catalog instagram account posts`
- **MCP tool**: `solari_catalog_instagram_account_posts`
- **Access**: `solari:read` — Works with any signed-in SOLARI account.
- **Required plan**: Free
- **Credit**: 0

List an Instagram account's posts with media, tags, and likes. You can filter by date or format.

**When to use it** — When you need more posts than the profile preview, or a date range or format.

**What comes back** — Posts, including carousel slides and tagged accounts or hashtags.

#### Parameters

- `account_id` (string, optional, uuid, pattern ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$) — Pass account_id or username.
- `username` (string, optional, ≤ 64 chars) — Instagram username. Ignored when account_id is set.
- `limit` (integer, optional, ≥ 1) — How many posts per page.
- `offset` (integer, optional, default 0, ≥ 0) — How many posts to skip.
- `since` (string, optional, pattern ^\d{4}-\d{2}-\d{2}$) — Only posts on or after this UTC date (YYYY-MM-DD).
- `until` (string, optional, pattern ^\d{4}-\d{2}-\d{2}$) — Only posts on or before this UTC date (YYYY-MM-DD).
- `post_type` (enum, optional) — Limit to reel, video, photo, or carousel. Values: `reel`, `video`, `photo`, `carousel`.

#### Response

##### `Response`

- `found` (boolean) — false if the username is not on Instagram.
- `account_id / username` (string) — The resolved account.
- `total` (integer) — Posts matching the filters.
- `has_more` (boolean) — Whether there is another page.
- `items` (object[]) — Posts, newest first.
- `fetched_on_demand` (boolean) — true when only the most recent posts are available so far.

##### `items[]`

- `post_id` (uuid) — SOLARI post id.
- `slug` (string) — Instagram shortcode.
- `url` (string) — Public permalink.
- `post_type` (string) — reel, video, photo, or carousel.
- `posted_at` (timestamp) — Published at (UTC).
- `text` (string) — Caption.
- `like_count / comment_count / play_count` (integer) — Engagement.
- `media_count` (integer) — Number of medias.
- `is_paid_partnership` (boolean | null) — Instagram paid-partnership label.
- `medias` (object[]) — Every media in carousel order.
- `medias[].tags` (object[]) — Accounts and hashtags tagged on the media.
- `thumbnail_url` (string) — Thumbnail.

#### Example

```console
$ solari catalog instagram account posts username=innisfreeofficial limit=2
```

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

```json
{
  "found": true,
  "account_id": "018cabce-14cc-7544-8890-7811ec33ef74",
  "username": "innisfreeofficial",
  "fetched_on_demand": false,
  "total": 4196,
  "has_more": true,
  "items": [
    {
      "post_id": "01a06275-d974-7fda-98ee-dd3ee15b4dcf",
      "slug": "DcyMAmUh6FZ",
      "url": "https://www.instagram.com/p/DcyMAmUh6FZ/",
      "post_type": "reel",
      "posted_at": "2026-09-02T12:00:06+00:00",
      "text": "Deeply hydrated skin—NO OFF HOURS. 💚\nwherever the day takes MINGYU (@min9yu_k)—his hydration stays SUPERCHARGED ⚡️\n\nGreen Tea Ceramide Milk: Lightweight milky toner that won‘t clog your pores\nGreen Tea Ceramide Mist: Tou …",
      "like_count": 3224,
      "comment_count": 57,
      "play_count": 22467,
      "media_count": 1,
      "is_paid_partnership": false,
      "medias": [
        {
          "media_type": "video",
          "media_url": "https://smr-images-b.bzine.co/users/018cabce-14cc-7544-8890-7811ec33ef74/posts/01a06275-d974-7fda-98ee-dd3ee15b4dcf/medias/01a06275-db2b-77f7-a020-b4beb744771f.mp4",
          "thumbnail_url": "https://bzine.co/cdn-cgi/media/width=480,mode=frame,time=0ms/https://smr-images.bzine.co/users/018cabce-14cc-7544-8890-7811ec33ef74/posts/01a06275-d974-7fda-98ee-dd3ee15b4dcf/medias/01a06275-db2b-77f7-a020-b4beb744771f.m …",
          "video_duration": 23.868000030517578,
          "tags": []
        }
      ],
      "thumbnail_url": "https://bzine.co/cdn-cgi/media/width=480,mode=frame,time=0ms/https://smr-images.bzine.co/users/018cabce-14cc-7544-8890-7811ec33ef74/posts/01a06275-d974-7fda-98ee-dd3ee15b4dcf/medias/01a06275-db2b-77f7-a020-b4beb744771f.m …"
    },
    "… 1 more"
  ]
}
```

#### As an MCP call

```json
{
  "name": "solari_catalog_instagram_account_posts",
  "arguments": {
    "username": "innisfreeofficial",
    "limit": 2
  }
}
```

#### Notes

- since and until are UTC dates, and both ends are included.
- post_type=reel is short-form video. video is a non-reel video.
- This reads the catalog only. If the username is missing, call solari fetch instagram posts username=… then retry.

#### Related tools

- [`solari_catalog_instagram_account_profile`](https://finder-dev-pub.bzine.co/docs/tools/catalog-instagram-account-profile.md)
- [`solari_catalog_instagram_content_detail`](https://finder-dev-pub.bzine.co/docs/tools/catalog-instagram-content-detail.md)
- [`solari_catalog_tiktok_account_posts`](https://finder-dev-pub.bzine.co/docs/tools/catalog-tiktok-account-posts.md)

### solari insight instagram account collabs

> An Instagram creator's recent collaborations.

- **CLI**: `solari insight instagram account collabs`
- **MCP tool**: `solari_insight_instagram_account_collabs`
- **Access**: `solari:read` — Works with any signed-in SOLARI account.
- **Required plan**: Free
- **Credit**: 0

Recent collaboration content from an Instagram creator.

**When to use it** — When you want to see who a creator has collaborated with. The brand-side view is brand top collaborators.

**What comes back** — Recent collaboration content.

#### Parameters

- `account_id` (string, optional, uuid, pattern ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$) — Pass the creator's account_id or username.
- `username` (string, optional, ≤ 64 chars) — Creator username. Ignored when account_id is set.
- `months` (integer, optional, ≥ 1) — How many months back to look.
- `limit` (integer, optional, ≥ 1) — How many brands per page.
- `offset` (integer, optional, default 0, ≥ 0) — How many brands to skip.

#### Response

##### `Response`

- `total` (integer) — Rows matching the filters.
- `has_more` (boolean) — Whether there are more rows.
- `items` (object[]) — Collaboration summaries, one per target brand.

##### `items[]`

- `target_account_id` (uuid) — account_id of the target brand.
- `target_username` (string) — Target brand username.
- `collab_count` (integer) — Collaboration posts with the brand.
- `last_posted_at` (timestamp) — Most recent collaboration.
- `post_id / slug` (string) — Identifiers of the sample post.
- `text` (string) — Sample post caption.
- `like_count / play_count` (integer) — Sample post engagement.
- `media_type` (string) — Sample post format.
- `thumbnail_url / media_url` (string) — Sample post media.
- `bio` (string) — Target brand bio.

#### Example

```console
$ solari insight instagram account collabs username=beinny_motd months=6 limit=3
```

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

```json
{
  "items": [
    {
      "post_id": "01a05575-7c9b-7232-8519-4a38fa061389",
      "target_user_id": "018cab85-8ef8-7dc9-ab0a-7044d463f65e",
      "target_username": "dasique_official",
      "collab_count": 2,
      "last_posted_at": "2026-08-30T05:08:56+00:00",
      "slug": "DcpugJ2kzv8",
      "text": "#광고 무겁지 않은 가을 데일리 팔레트 로즈밀크티 . .🫖🤎\n차분하고 미지근한 로즈핑크 팔레트인데\n부드러운 밀크티 무드라서 분위기가 넘 예뻐요..🥺\n\n데이지크에서 올리브영 X 산리오 콜라보\n시티팝 에디션으로 미니섀도우팔레트 4종이 출시되는데\n그 중 자주 추천드렸던 로즈밀크티, 밀크라떼가 있더라구요 !\n\nNEW 컬러 피치레코드, 모브카세트도 출시되어요🤍\n도시의 아침과 저녁 무드를 담은 데일리한 …",
      "play_count": 0,
      "media_type": "8",
      "like_count": 878,
      "video_media_count": 0,
      "media_count": 15,
      "bio": "🫒올영세일 08.30 – 09.05\nUP TO 37% SALE\n올리브영X산리오,\n🌠데이지크 🆕 미니 섀도우",
      "thumbnail_url": "https://bzine.co/cdn-cgi/image/fit=scale-down,width=480/https://smr-images-c.bzine.co/users/018ecc75-55d8-70a7-a348-d370aa504ed9/posts/01a05575-7c9b-7232-8519-4a38fa061389/medias/01a05575-7dd3-779e-9050-a6cb59578cb9.jpg",
      "media_url": "https://bzine.co/cdn-cgi/image/fit=scale-down,width=480/https://smr-images-c.bzine.co/users/018ecc75-55d8-70a7-a348-d370aa504ed9/posts/01a05575-7c9b-7232-8519-4a38fa061389/medias/01a05575-7dd3-779e-9050-a6cb59578cb9.jpg",
      "target_account_id": "018cab85-8ef8-7dc9-ab0a-7044d463f65e"
    },
    "… 2 more"
  ],
  "has_more": true,
  "total": 7
}
```

#### As an MCP call

```json
{
  "name": "solari_insight_instagram_account_collabs",
  "arguments": {
    "username": "beinny_motd",
    "months": 6,
    "limit": 3
  }
}
```

#### Notes

- For the individual ad posts, use account ad posts.

#### Related tools

- [`solari_insight_instagram_account_ad_posts`](https://finder-dev-pub.bzine.co/docs/tools/insight-instagram-account-ad-posts.md)
- [`solari_insight_instagram_brand_top_collaborators`](https://finder-dev-pub.bzine.co/docs/tools/insight-instagram-brand-top-collaborators.md)

### solari insight instagram account ad posts

> An Instagram creator's ad posts.

- **CLI**: `solari insight instagram account ad posts`
- **MCP tool**: `solari_insight_instagram_account_ad_posts`
- **Access**: `solari:read` — Works with any signed-in SOLARI account.
- **Required plan**: Free
- **Credit**: 0

Sponsored posts from an Instagram creator.

**When to use it** — When you need the ad posts themselves, not a summary.

**What comes back** — Ad posts, newest first.

#### Parameters

- `account_id` (string, optional, uuid, pattern ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$) — Pass the creator's account_id or username.
- `username` (string, optional, ≤ 64 chars) — Creator username. Ignored when account_id is set.
- `months` (integer, optional, ≥ 1) — How many months back to look.
- `limit` (integer, optional, ≥ 1) — How many rows per page.
- `offset` (integer, optional, default 0, ≥ 0) — How many rows to skip.
- `target` (string, optional, ≤ 64 chars) — Limit to one brand — account_id or username.

#### Response

##### `Response`

- `account_id / username` (string) — The resolved creator.
- `months` (integer) — Lookback window applied.
- `total` (integer) — Total rows.
- `has_more` (boolean) — Whether there is another page.
- `items` (object[]) — Post–brand pairs.

##### `items[]`

- `post_id / slug / url` (string) — Post identifiers and public link.
- `post_type` (string) — reel, video, photo, or carousel.
- `posted_at` (timestamp) — Published at (UTC).
- `text` (string) — Caption.
- `like_count / comment_count / play_count` (integer) — Engagement.
- `media_count` (integer) — Number of medias.
- `is_paid_partnership` (boolean | null) — Instagram paid-partnership label.
- `target_account_id / target_username` (string) — The brand on the row.

#### Example

```console
$ solari insight instagram account ad posts username=beinny_motd months=6 limit=2
```

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

```json
{
  "account_id": "018ecc75-55d8-70a7-a348-d370aa504ed9",
  "username": "beinny_motd",
  "months": 6,
  "total": 12,
  "has_more": true,
  "items": [
    {
      "post_id": "01a05575-7c9b-7232-8519-4a38fa061389",
      "slug": "DcpugJ2kzv8",
      "url": "https://www.instagram.com/p/DcpugJ2kzv8/",
      "post_type": "carousel",
      "posted_at": "2026-08-30T05:08:56Z",
      "text": "#광고 무겁지 않은 가을 데일리 팔레트 로즈밀크티 . .🫖🤎\n차분하고 미지근한 로즈핑크 팔레트인데\n부드러운 밀크티 무드라서 분위기가 넘 예뻐요..🥺\n\n데이지크에서 올리브영 X 산리오 콜라보\n시티팝 에디션으로 미니섀도우팔레트 4종이 출시되는데\n그 중 자주 추천드렸던 로즈밀크티, 밀크라떼가 있더라구요 !\n\nNEW 컬러 피치레코드, 모브카세트도 출시되어요🤍\n도시의 아침과 저녁 무드를 담은 데일리한 …",
      "like_count": 878,
      "comment_count": 19,
      "play_count": 0,
      "media_count": 15,
      "is_paid_partnership": null,
      "target_account_id": "018cab85-8ef8-7dc9-ab0a-7044d463f65e",
      "target_username": "dasique_official"
    },
    "… 1 more"
  ]
}
```

#### As an MCP call

```json
{
  "name": "solari_insight_instagram_account_ad_posts",
  "arguments": {
    "username": "beinny_motd",
    "months": 6,
    "limit": 2
  }
}
```

#### Notes

- target limits results to one brand. Pass the brand's account_id or username.

#### Related tools

- [`solari_insight_instagram_account_collabs`](https://finder-dev-pub.bzine.co/docs/tools/insight-instagram-account-collabs.md)
- [`solari_insight_instagram_brand_ad_posts`](https://finder-dev-pub.bzine.co/docs/tools/insight-instagram-brand-ad-posts.md)

### solari catalog instagram content detail

> An Instagram post, by id, shortcode, or URL.

- **CLI**: `solari catalog instagram content detail`
- **MCP tool**: `solari_catalog_instagram_content_detail`
- **Access**: `solari:read` — Works with any signed-in SOLARI account.
- **Required plan**: Free
- **Credit**: 0

Load an Instagram post by post_id, shortcode, or public URL.

**When to use it** — When you need a post. For many ids at once, use content batch.

**What comes back** — The post, with caption and metrics.

#### Parameters

- `post_id` (string, optional, uuid, pattern ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$) — post_id. Pass this, slug, or url.
- `slug` (string, optional, pattern ^[A-Za-z0-9_-]{3,20}$) — Instagram shortcode.
- `url` (string, optional, ≤ 512 chars) — Public Instagram post URL.

#### Response

##### `Response`

- `item` (object | null) — The post. null if it does not exist or is not public.
- `fetched_on_demand` (boolean) — true if the post was fetched live on this call.

##### `item`

- `post_id` (uuid) — Post id for other content tools.
- `slug` (string) — Shortcode from the public URL.
- `author_id` (uuid) — Author account_id.
- `username` (string) — Author username.
- `full_name` (string | null) — Display name.
- `profile_pic_url` (string | null) — Profile picture URL.
- `follower_count` (integer | null) — Author follower count.
- `region` (string | null) — Author region.
- `posted_at` (timestamp) — Published at (UTC).
- `media_type` (string) — image, video, or carousel.
- `play_count` (integer | null) — Video plays. Null for images.
- `like_count` (integer | null) — Likes.
- `text` (string | null) — Caption.
- `media_url` (string) — Media URL.
- `thumbnail_url` (string) — Thumbnail URL.
- `score` (number | null) — Ranking score for this response.
- `efficiency_score` (number | null) — Performance vs. the author's followers.
- `est_percentile` (number | null) — Region percentile, 0–1.
- `total_views_3m` (integer | null) — Author views in the last 3 months.
- `median_views_3m` (integer | null) — Author median views in the last 3 months.
- `recent_collab_brands` (string[]) — Brands the author recently collaborated with.
- `item_type` (string) — Item kind. post in these feeds.
- `content_source` (string | null) — Which feed surfaced this item.
- `is_saved` (boolean | null) — Whether it's saved in SOLARI.
- `updated_at` (timestamp | null) — When metrics were last refreshed.

#### Example

```console
$ solari catalog instagram content detail slug=DcyMAmUh6FZ
```

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

```json
{
  "item": {
    "item_type": "content",
    "post_id": "01a06275-d974-7fda-98ee-dd3ee15b4dcf",
    "author_id": "018cabce-14cc-7544-8890-7811ec33ef74",
    "username": "innisfreeofficial",
    "full_name": "INNISFREE | 이니스프리",
    "profile_pic_url": "https://dcr.bzine.co/instagram/users/innisfreeofficial/profile-picture",
    "follower_count": 847619,
    "region": null,
    "posted_at": "2026-09-02T12:00:06Z",
    "media_type": "video",
    "play_count": 22467,
    "like_count": 3224,
    "score": null,
    "efficiency_score": null,
    "est_percentile": null,
    "updated_at": null,
    "media_url": "https://smr-images-b.bzine.co/users/018cabce-14cc-7544-8890-7811ec33ef74/posts/01a06275-d974-7fda-98ee-dd3ee15b4dcf/medias/01a06275-db2b-77f7-a020-b4beb744771f.mp4",
    "thumbnail_url": "https://bzine.co/cdn-cgi/media/width=480,mode=frame,time=0ms/https://smr-images.bzine.co/users/018cabce-14cc-7544-8890-7811ec33ef74/posts/01a06275-d974-7fda-98ee-dd3ee15b4dcf/medias/01a06275-db2b-77f7-a020-b4beb744771f.m …",
    "slug": "DcyMAmUh6FZ",
    "text": "Deeply hydrated skin—NO OFF HOURS. 💚\nwherever the day takes MINGYU (@min9yu_k)—his hydration stays SUPERCHARGED ⚡️\n\nGreen Tea Ceramide Milk: Lightweight milky toner that won‘t clog your pores\nGreen Tea Ceramide Mist: Tou …",
    "brand_match_score": null,
    "recent_collab_brands": [],
    "total_views_3m": null,
    "median_views_3m": null,
    "is_saved": null,
    "content_source": null
  },
  "fetched_on_demand": false
}
```

#### As an MCP call

```json
{
  "name": "solari_catalog_instagram_content_detail",
  "arguments": {
    "slug": "DcyMAmUh6FZ"
  }
}
```

#### Notes

- url can be any /p/, /reel/, or /tv/ link — the shortcode is picked out for you.
- This reads the catalog only. Fetch does not take a post URL. If you have the author's username, call solari fetch instagram posts username=… then retry.

#### Related tools

- [`solari_catalog_instagram_content_batch`](https://finder-dev-pub.bzine.co/docs/tools/catalog-instagram-content-batch.md)
- [`solari_catalog_instagram_account_posts`](https://finder-dev-pub.bzine.co/docs/tools/catalog-instagram-account-posts.md)

### solari catalog instagram content batch

> Several Instagram posts at once.

- **CLI**: `solari catalog instagram content batch`
- **MCP tool**: `solari_catalog_instagram_content_batch`
- **Access**: `solari:read` — Works with any signed-in SOLARI account.
- **Required plan**: Free
- **Credit**: 0

Load captions and metrics for a list of post ids. Ids that cannot be found are skipped.

**When to use it** — When you have ids from brand overview or a feed and want the posts.

**What comes back** — The posts that were found.

#### Parameters

- `post_ids` (uuid[], required, 1–100 items, uuid) — post_ids to load, up to 100.
- `sort` (enum, optional, default "recent") — Order by newest, or by engagement. Values: `recent`, `engagement`.

#### Response

##### `Response`

- `items` (object[]) — The posts found.
- `requested` (integer) — How many ids were sent.
- `found` (integer) — How many resolved. Untracked ids are dropped, so this can be lower.

##### `items[]`

- `id` (uuid) — Post id.
- `slug` (string) — Instagram shortcode.
- `text` (string) — Caption.
- `posted_at` (timestamp) — Published at (UTC).
- `username / user_id / account_id` (string) — Authoring account.
- `like_count / comment_count` (integer) — Engagement.
- `play_count` (integer | null) — Video plays.
- `media_type` (string) — Post format.

#### Example

```console
$ solari catalog instagram content batch post_ids='["019f505f-f8be-7e88-ae08-6fba999950b1","019f5060-3449-779e-a08b-d6d49add90cd"]'
```

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

```json
{
  "items": [
    {
      "id": "019f505f-f8be-7e88-ae08-6fba999950b1",
      "slug": "Dam_BYyJxtR",
      "text": "#광고 ₊✩‧₊˚ @innisfreeofficial ˚₊✩‧₊ \n공들인 나의 화장.. 찜통 더위에 무너져 내릴때\n이니스프리 노세범 선 파우더 하나면 고민 끝!\n\n유분 가득한 피부.. 꺼진 부위, 모공, 요철 부각되어\n10년은 늙어보이는 몰골에서 노세범 선 파우더 바르는\n즉시 핑크빛 필터를 씌운 듯~ 뽀용 피부 완성 ⭒˚.⋆\n\n노세범 맛집 답게 과다 피지와 유분을 즉각 흡착시키고\n무엇보다 가벼 …",
      "posted_at": "2026-07-10T10:34:01Z",
      "virtual_campaign": null,
      "username": "the_ketchap",
      "user_id": "018d3b53-c0c1-71cc-a44f-204f7d850267",
      "profile_picture_url": null,
      "like_count": 38579,
      "comment_count": 31,
      "thumbnail_url": null,
      "media_url": null,
      "media": [],
      "media_type": "reel",
      "play_count": 676825,
      "account_id": "018d3b53-c0c1-71cc-a44f-204f7d850267"
    },
    "… 1 more"
  ],
  "requested": 2,
  "found": 2
}
```

#### As an MCP call

```json
{
  "name": "solari_catalog_instagram_content_batch",
  "arguments": {
    "post_ids": [
      "019f505f-f8be-7e88-ae08-6fba999950b1",
      "019f5060-3449-779e-a08b-d6d49add90cd"
    ]
  }
}
```

#### Notes

- This takes SOLARI post ids only. Shortcodes go to content detail as slug.

#### Related tools

- [`solari_catalog_instagram_content_detail`](https://finder-dev-pub.bzine.co/docs/tools/catalog-instagram-content-detail.md)
- [`solari_insight_instagram_brand_overview`](https://finder-dev-pub.bzine.co/docs/tools/insight-instagram-brand-overview.md)

### solari catalog instagram content search

> Use this to search Instagram captions, bios, and video transcripts.

- **CLI**: `solari catalog instagram content search`
- **MCP tool**: `solari_catalog_instagram_content_search`
- **Access**: `solari:read` — Works with any signed-in SOLARI account.
- **Required plan**: Free
- **Credit**: 0

Keyword search over tracked Instagram posts in KR, JP, US, and TW, covering about the last six months.

**When to use it** — When you want posts about a topic. If you need a count, use content aggregate.

**What comes back** — Posts ranked by relevance, with matching text highlighted.

#### Parameters

- `query` (string, required) — Words to search for.
- `region` (enum, optional, default "KR") — KR, JP, US, or TW. Values: `KR`, `JP`, `US`, `TW`.
- `limit` (integer, optional, ≥ 1) — How many posts per page.
- `offset` (integer, optional, default 0, ≥ 0) — How many posts to skip.
- `since` (string, optional, pattern ^\d{4}-\d{2}-\d{2}$) — Only posts on or after this UTC date (YYYY-MM-DD).
- `until` (string, optional, pattern ^\d{4}-\d{2}-\d{2}$) — Only posts on or before this UTC date (YYYY-MM-DD).

#### Response

##### `Response`

- `query / region` (string) — The query and region applied.
- `total` (integer) — Total matches. Exact up to 10,000, then saturates.
- `took_ms` (integer) — Search time.
- `items` (object[]) — Hits, score descending.

##### `items[]`

- `post_id` (uuid) — SOLARI post id.
- `slug` (string) — Instagram shortcode.
- `account_id / author_id / username` (string) — Authoring account.
- `caption` (string) — Caption.
- `user_bio` (string) — Author bio — part of the searched text.
- `transcription_text` (string | null) — Video speech transcription.
- `posted_at` (timestamp) — Published at (UTC).
- `like_count / comment_count` (integer) — Engagement.
- `follower_count` (integer) — Author follower count.
- `score` (number) — Relevance score. Comparable only within this response.
- `highlight` (object) — Matched fragments per field: caption, user_bio, transcription_text.
- `is_video` (boolean) — Whether the post is a video.

#### Example

```console
$ solari catalog instagram content search query="이니스프리 그린티" limit=3
```

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

```json
{
  "query": "이니스프리 그린티",
  "region": "KR",
  "total": 10000,
  "took_ms": 1586,
  "items": [
    {
      "post_id": "019f12d8-3e72-78e9-b7e5-39293bc56f23",
      "author_id": "019f12d8-3e0f-7c74-afc6-e14405bd1523",
      "username": "hanydiary",
      "caption": "[이니스프리에디터 4기 1-2 : 그린티 PDRN 아이&립 세럼] #이니스프리 #그린티PDRN 💚 자세한 포스팅은 프로필 링크 참고해주세요 :)",
      "user_bio": "대외활동 | 휴학생 | 취준일기 🪽과 학생회 2년 연임 🪽이니스프리 대학생 에디터 3기 / 4기",
      "transcription_text": null,
      "posted_at": "2026-02-16T05:44:45Z",
      "like_count": 3,
      "comment_count": 3,
      "follower_count": 972,
      "score": 140.43787,
      "slug": "DUzrl1UkoJb",
      "highlight": {
        "caption": [
          "[<mark>이니스프리</mark>에디터 4기 1-2 : <mark>그린티</mark> PDRN 아이&립 세럼] #이니스프리 #그린티PDRN 💚 자세한 포스팅은 프로필 링크 참고해주세요 :)"
        ],
        "user_bio": [
          "대외활동 | 휴학생 | 취준일기 🪽과 학생회 2년 연임 🪽<mark>이니스프리</mark> 대학생 에디터 3기 / 4기"
        ],
        "transcription_text": []
      },
      "is_video": false,
      "media_url": null,
      "thumbnail_url": null,
      "account_id": "019f12d8-3e0f-7c74-afc6-e14405bd1523"
    },
    "… 2 more"
  ]
}
```

#### As an MCP call

```json
{
  "name": "solari_catalog_instagram_content_search",
  "arguments": {
    "query": "이니스프리 그린티",
    "limit": 3
  }
}
```

#### Notes

- A since older than about six months returns nothing.
- total counts up to 10,000, then stops.

#### Related tools

- [`solari_insight_instagram_content_aggregate`](https://finder-dev-pub.bzine.co/docs/tools/insight-instagram-content-aggregate.md)
- [`solari_catalog_instagram_content_batch`](https://finder-dev-pub.bzine.co/docs/tools/catalog-instagram-content-batch.md)
- [`solari_catalog_tiktok_content_search`](https://finder-dev-pub.bzine.co/docs/tools/catalog-tiktok-content-search.md)

### solari insight instagram content trending

> Instagram posts that are trending now.

- **CLI**: `solari insight instagram content trending`
- **MCP tool**: `solari_insight_instagram_content_trending`
- **Access**: `solari:read` — Works with any signed-in SOLARI account.
- **Required plan**: Free
- **Credit**: 0

Trending Instagram posts in the region you set, with the author's profile attached.

**When to use it** — When you want what's working right now. For speed of growth, use content rising.

**What comes back** — Trending posts. Use next_cursor for the next page.

#### Parameters

- `region` (string, optional, default "KR") — Country code such as KR or JP.
- `limit` (integer, optional, ≥ 1) — How many posts per page.
- `cursor` (string, optional) — next_cursor from the previous page.
- `account_id` (string, optional, uuid, pattern ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$) — Brand account_id to rank toward the brand.
- `username` (string, optional, ≤ 64 chars) — Brand username to rank toward the brand. Ignored when account_id is set.

#### Response

##### `Response`

- `items` (object[]) — Trending posts.
- `total_count` (integer) — Size of the feed.
- `region` (string) — Region applied.
- `content_type` (string) — Feed kind.
- `next_cursor` (string | null) — Use as cursor on the next page.

##### `items[]`

- `post_id` (uuid) — Post id for other content tools.
- `slug` (string) — Shortcode from the public URL.
- `author_id` (uuid) — Author account_id.
- `username` (string) — Author username.
- `full_name` (string | null) — Display name.
- `profile_pic_url` (string | null) — Profile picture URL.
- `follower_count` (integer | null) — Author follower count.
- `region` (string | null) — Author region.
- `posted_at` (timestamp) — Published at (UTC).
- `media_type` (string) — image, video, or carousel.
- `play_count` (integer | null) — Video plays. Null for images.
- `like_count` (integer | null) — Likes.
- `text` (string | null) — Caption.
- `media_url` (string) — Media URL.
- `thumbnail_url` (string) — Thumbnail URL.
- `score` (number | null) — Ranking score for this response.
- `efficiency_score` (number | null) — Performance vs. the author's followers.
- `est_percentile` (number | null) — Region percentile, 0–1.
- `total_views_3m` (integer | null) — Author views in the last 3 months.
- `median_views_3m` (integer | null) — Author median views in the last 3 months.
- `recent_collab_brands` (string[]) — Brands the author recently collaborated with.
- `item_type` (string) — Item kind. post in these feeds.
- `content_source` (string | null) — Which feed surfaced this item.
- `is_saved` (boolean | null) — Whether it's saved in SOLARI.
- `updated_at` (timestamp | null) — When metrics were last refreshed.

#### Example

```console
$ solari insight instagram content trending region=KR limit=2
```

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

```json
{
  "items": [
    {
      "item_type": "content",
      "post_id": "01a055fe-d72c-7005-8709-eef67b4be6f0",
      "author_id": "018ecc27-f8e7-7100-9339-bb050ea44a7f",
      "username": "sixpackpiggy",
      "full_name": "Jinmin Park",
      "profile_pic_url": "https://dcr.bzine.co/instagram/users/sixpackpiggy/profile-picture",
      "follower_count": 93442,
      "region": "KR",
      "posted_at": "2026-08-29T02:02:20Z",
      "media_type": "video",
      "play_count": 286749,
      "like_count": null,
      "score": 96.69330916066565,
      "efficiency_score": null,
      "est_percentile": 96.69330916066565,
      "updated_at": "2026-09-03T04:51:42.797111Z",
      "media_url": "https://smr-images-b.bzine.co/users/018ecc27-f8e7-7100-9339-bb050ea44a7f/posts/01a055fe-d72c-7005-8709-eef67b4be6f0/medias/01a055fe-d964-7d73-9a77-d06823a2abc2.mp4",
      "thumbnail_url": "https://bzine.co/cdn-cgi/media/width=480,mode=frame,time=0ms/https://smr-images.bzine.co/users/018ecc27-f8e7-7100-9339-bb050ea44a7f/posts/01a055fe-d72c-7005-8709-eef67b4be6f0/medias/01a055fe-d964-7d73-9a77-d06823a2abc2.m …",
      "slug": "Dcmzs05SAae",
      "text": "How dedicated are you to your Korean skincare? 💅@patinaosaka \n#koreanskincare #osaka #japan #kbeauty #traveling",
      "brand_match_score": null,
      "recent_collab_brands": [],
      "total_views_3m": 1875678,
      "median_views_3m": 57780,
      "is_saved": false,
      "content_source": null
    },
    "… 1 more"
  ],
  "total_count": 213635,
  "region": "KR",
  "content_type": "trending",
  "next_cursor": "eyJhcyI6ICIyMDI2LTA5LTAzVDA1OjIwOjIzLjM4Mzk3NCswMDowMCIsICJzYyI6ICIyMDI2LTA5LTAzVDA0OjQ0OjQ3LjkzNTI1OCswMDowMCIsICJzcCI6ICIwMWEwNTVmZS1mOWIyLTdiNmYtYjY1OS05ZGE1OTM3NjgzMWMifQ=="
}
```

#### As an MCP call

```json
{
  "name": "solari_insight_instagram_content_trending",
  "arguments": {
    "region": "KR",
    "limit": 2
  }
}
```

#### Notes

- Pass a brand account_id or username to rank toward the brand.
- Pages use a cursor, not offset. Send back next_cursor.

#### Related tools

- [`solari_insight_instagram_content_rising`](https://finder-dev-pub.bzine.co/docs/tools/insight-instagram-content-rising.md)
- [`solari_insight_instagram_content_trend_clusters`](https://finder-dev-pub.bzine.co/docs/tools/insight-instagram-content-trend-clusters.md)

### solari insight instagram content rising

> Instagram posts that are rising fast.

- **CLI**: `solari insight instagram content rising`
- **MCP tool**: `solari_insight_instagram_content_rising`
- **Access**: `solari:read` — Works with any signed-in SOLARI account.
- **Required plan**: Free
- **Credit**: 0

Instagram posts whose recent performance is accelerating, with the author's profile attached.

**When to use it** — When growth rate matters more than current totals.

**What comes back** — Rising posts. Use next_cursor for the next page.

#### Parameters

- `region` (string, optional, default "KR") — Country code such as KR or JP.
- `limit` (integer, optional, ≥ 1) — How many posts per page.
- `cursor` (string, optional) — next_cursor from the previous page.
- `account_id` (string, optional, uuid, pattern ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$) — Brand account_id to rank toward the brand.
- `username` (string, optional, ≤ 64 chars) — Brand username to rank toward the brand. Ignored when account_id is set.

#### Response

##### `Response`

- `items` (object[]) — Rising posts.
- `total_count` (integer) — Size of the feed.
- `region` (string) — Region applied.
- `content_type` (string) — Feed kind.
- `next_cursor` (string | null) — Use as cursor on the next page.

##### `items[]`

- `post_id` (uuid) — Post id for other content tools.
- `slug` (string) — Shortcode from the public URL.
- `author_id` (uuid) — Author account_id.
- `username` (string) — Author username.
- `full_name` (string | null) — Display name.
- `profile_pic_url` (string | null) — Profile picture URL.
- `follower_count` (integer | null) — Author follower count.
- `region` (string | null) — Author region.
- `posted_at` (timestamp) — Published at (UTC).
- `media_type` (string) — image, video, or carousel.
- `play_count` (integer | null) — Video plays. Null for images.
- `like_count` (integer | null) — Likes.
- `text` (string | null) — Caption.
- `media_url` (string) — Media URL.
- `thumbnail_url` (string) — Thumbnail URL.
- `score` (number | null) — Ranking score for this response.
- `efficiency_score` (number | null) — Performance vs. the author's followers.
- `est_percentile` (number | null) — Region percentile, 0–1.
- `total_views_3m` (integer | null) — Author views in the last 3 months.
- `median_views_3m` (integer | null) — Author median views in the last 3 months.
- `recent_collab_brands` (string[]) — Brands the author recently collaborated with.
- `item_type` (string) — Item kind. post in these feeds.
- `content_source` (string | null) — Which feed surfaced this item.
- `is_saved` (boolean | null) — Whether it's saved in SOLARI.
- `updated_at` (timestamp | null) — When metrics were last refreshed.

#### Example

```console
$ solari insight instagram content rising region=KR limit=2
```

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

```json
{
  "items": [
    {
      "item_type": "content",
      "post_id": "01a0495a-4e46-73d5-a111-a818248b665b",
      "author_id": "019e4a24-ee85-78e9-8763-602930999853",
      "username": "iiiwantkitty",
      "full_name": "주 령",
      "profile_pic_url": "https://dcr.bzine.co/instagram/users/iiiwantkitty/profile-picture",
      "follower_count": 706,
      "region": "KR",
      "posted_at": "2026-08-28T07:38:46Z",
      "media_type": "video",
      "play_count": 48092,
      "like_count": null,
      "score": 0.1292899036795201,
      "efficiency_score": 0.1292899036795201,
      "est_percentile": 84.68488691008565,
      "updated_at": "2026-09-03T05:20:45.496271Z",
      "media_url": "https://smr-images-b.bzine.co/users/019e4a24-ee85-78e9-8763-602930999853/posts/01a0495a-4e46-73d5-a111-a818248b665b/medias/01a0495a-4fc0-7352-92dd-a04afe898589.mp4",
      "thumbnail_url": "https://bzine.co/cdn-cgi/media/width=480,mode=frame,time=0ms/https://smr-images-a.bzine.co/users/019e4a24-ee85-78e9-8763-602930999853/posts/01a0495a-4e46-73d5-a111-a818248b665b/medias/01a0495a-4fc0-7352-92dd-a04afe898589 …",
      "slug": "Dck0Wj8xeq3",
      "text": "이정도가 아니면 뮤트라고 하지말자..⭐️ 뮤트톤 친구 입술에 빡빡 발라주고싶음\n\n컬러 보자마자 아 내꺼하자ㅡㅡ 하고 바로 겟한 것\n\n그레이애쉬,, 핑크 ,, 브라운 다 들어간 밑힌 컬러 이거 뮤트톤들이 바르면 진짜 분위기 미처버리는 립이걸랑 영상보다 실물이 더 뮤트!\n\n입술에 올리면 좀더 투명하게 올라가면서 회끼도는데 뉴트럴하면서도 팥앙금 같은 고런 깔 느낌\n안쪽에만 톡톡 발라서 쌩얼립으로도 …",
      "brand_match_score": null,
      "recent_collab_brands": [
        "apieu_cosmetics",
        "… 8 more"
      ],
      "total_views_3m": 2389749,
      "median_views_3m": 5215,
      "is_saved": false,
      "content_source": null
    },
    "… 1 more"
  ],
  "total_count": 291665,
  "region": "KR",
  "content_type": "rising",
  "next_cursor": "eyJhcyI6ICIyMDI2LTA5LTAzVDA1OjIwOjQ5LjA3Mjg3MiswMDowMCIsICJzYyI6ICIyMDI2LTA5LTAzVDA1OjE5OjQwLjc1NzUwOCswMDowMCIsICJzcCI6ICIwMWEwNDNmOC1hODdlLTdiMWItYjFiNi1iODliMTU2YjU0ODgifQ=="
}
```

#### As an MCP call

```json
{
  "name": "solari_insight_instagram_content_rising",
  "arguments": {
    "region": "KR",
    "limit": 2
  }
}
```

#### Notes

- Parameters match content trending, including ranking toward a brand.

#### Related tools

- [`solari_insight_instagram_content_trending`](https://finder-dev-pub.bzine.co/docs/tools/insight-instagram-content-trending.md)
- [`solari_insight_instagram_content_trend_clusters`](https://finder-dev-pub.bzine.co/docs/tools/insight-instagram-content-trend-clusters.md)

### solari insight instagram content trend clusters

> Instagram trends grouped by theme.

- **CLI**: `solari insight instagram content trend clusters`
- **MCP tool**: `solari_insight_instagram_content_trend_clusters`
- **Access**: `solari:read` — Works with any signed-in SOLARI account.
- **Required plan**: Free
- **Credit**: 0

A trend digest for the region you set: named themes with size, movement, and a few member posts.

**When to use it** — When you want the shape of the moment, not a list of posts.

**What comes back** — Named clusters with a preview of member posts.

#### Parameters

- `region` (string, optional, default "KR") — Country code such as KR or JP.
- `since_days` (integer, optional, default 7, 1–90) — How many days back to look.
- `limit` (integer, optional, ≥ 1) — How many clusters to return.
- `account_id` (string, optional, uuid, pattern ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$) — Brand account_id to rank clusters for the brand.
- `username` (string, optional, ≤ 64 chars) — Brand username to rank clusters for the brand. Ignored when account_id is set.
- `brand_aware` (boolean, optional, default true) — Rank clusters for the brand. On by default when a brand is set.

#### Response

##### `Response`

- `success` (boolean) — Whether the digest was generated.
- `trend_count` (integer) — Clusters returned.
- `header_text` (string) — Digest headline.
- `region / since_days` (string · integer) — Region and lookback applied.
- `brand_aware` (boolean) — Whether brand-affinity reranking was requested.
- `als_applied` (boolean) — Whether the affinity model actually ran.
- `trends` (object[]) — The clusters.

##### `trends[]`

- `cluster_id` (string) — Cluster id.
- `name` (string) — Cluster name.
- `bullets` (string[]) — Sentences describing the cluster.
- `count` (integer) — Member posts.
- `count_delta` (integer) — Change in member posts vs. the previous period.
- `growth_pct` (number) — Growth rate, percent.
- `avg_play_delta` (number) — Change in average plays.
- `distinct_creators` (integer) — Creators contributing to the cluster.
- `creator_delta` (integer) — Change in creator count.
- `is_new` (boolean) — Whether the cluster first appeared this period.
- `member_thumbnails` (object[]) — Thumbnail previews of member posts.

#### Example

```console
$ solari insight instagram content trend clusters region=KR since_days=7 limit=2
```

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

```json
{
  "success": true,
  "trend_count": 2,
  "header_text": "최근 7일 인기 트렌드 2개 (브랜드 컨텍스트 없음)",
  "brand_aware": true,
  "als_applied": false,
  "region": "KR",
  "since_days": 7,
  "directive": null,
  "trends": [
    {
      "cluster_id": "01a05857-7727-74d8-8da5-4e95981aca8d",
      "name": "GV90의 미래형 하이테크 기능",
      "bullets": [
        "화면이 회전하거나 시트가 뒤로 돌아가는 등 물리적으로 변형되는 자동차 내부 장치들을 직접 시연함",
        "… 1 more"
      ],
      "count": 7,
      "count_delta": 0,
      "growth_pct": 0,
      "avg_play_delta": 0,
      "creator_delta": 0,
      "distinct_creators": 3,
      "is_new": false,
      "early_zone_creator_count": null,
      "early_zone_creator_ratio": null,
      "als_member_count": null,
      "mean_als_score": null,
      "annotation": null,
      "group": null,
      "member_thumbnails": [
        {
          "post_id": "01a030df-c4b3-739c-9214-44b3b9463c7b",
          "thumbnail_url": "https://bzine.co/cdn-cgi/media/width=480,mode=frame,time=100ms/https://smr-images-c.bzine.co/users/018cb4c9-da89-7b02-8efd-53ccb65c26c9/posts/01a030df-c4b3-739c-9214-44b3b9463c7b/medias/01a030df-c7c3-788e-8775-1096728e07 …",
          "slug": "DcP6jgRMTRv",
          "username": "sol.bpd",
          "media_url": "https://smr-images-c.bzine.co/users/018cb4c9-da89-7b02-8efd-53ccb65c26c9/posts/01a030df-c4b3-739c-9214-44b3b9463c7b/medias/01a030df-c7c3-788e-8775-1096728e07f2.mp4",
          "media_type": "video",
          "play_count": 1947419,
          "posted_at": "2026-08-20T04:37:17+00:00"
        },
        "… 3 more"
      ]
    },
    "… 1 more"
  ],
  "insights": null,
  "insight_query": null
}
```

#### As an MCP call

```json
{
  "name": "solari_insight_instagram_content_trend_clusters",
  "arguments": {
    "region": "KR",
    "since_days": 7,
    "limit": 2
  }
}
```

#### Notes

- This call can take up to two minutes.
- Pass a brand to rank clusters for the brand. Set brand_aware=false to keep the raw order.

#### Related tools

- [`solari_insight_instagram_content_trending`](https://finder-dev-pub.bzine.co/docs/tools/insight-instagram-content-trending.md)
- [`solari_insight_instagram_content_rising`](https://finder-dev-pub.bzine.co/docs/tools/insight-instagram-content-rising.md)

### solari insight instagram content aggregate

> Use this to count Instagram posts.

- **CLI**: `solari insight instagram content aggregate`
- **MCP tool**: `solari_insight_instagram_content_aggregate`
- **Access**: `solari:read` — Works with any signed-in SOLARI account.
- **Required plan**: Free
- **Credit**: 0

Add up tracked posts by account, format, hashtag, mention, or keyword — for questions that need a number.

**When to use it** — When you need volume, averages, or which hashtag leads. For the posts themselves, use content search.

**What comes back** — Counts per group, largest first. Extra metrics only if you ask for them.

#### Parameters

- `region` (enum, optional, default "KR") — KR, JP, US, or TW. Values: `KR`, `JP`, `US`, `TW`.
- `group_by` (enum, optional) — How to split the counts. Values: `account`, `post_type`, `hashtag`, `mention`, `caption_keyword`, `transcription_keyword`.
- `interval` (enum, optional) — Add a time series at this calendar interval. Values: `day`, `week`, `month`.
- `metrics` (string[], optional) — Extra metrics besides post_count. Values: `like_sum`, `like_avg`, `comment_sum`, `comment_avg`, `view_sum`, `view_avg`, `follower_avg`, `account_count`.
- `query` (string, optional) — Keyword filter over captions and transcripts.
- `usernames` (string[], optional) — Only these Instagram usernames.
- `hashtags` (string[], optional) — Only posts that have all of these hashtags.
- `mentions` (string[], optional) — Only posts that mention all of these usernames.
- `post_types` (string[], optional) — Only these formats.
- `since` (string, optional, pattern ^\d{4}-\d{2}-\d{2}$) — Only posts on or after this UTC date (YYYY-MM-DD).
- `until` (string, optional, pattern ^\d{4}-\d{2}-\d{2}$) — Only posts on or before this UTC date (YYYY-MM-DD).
- `limit` (integer, optional, ≥ 1) — How many groups to return.

#### Response

##### `Response`

- `region` (string) — Region aggregated.
- `since` (date) — Start date actually used.
- `until` (date | null) — End date actually used.
- `group_by` (string | null) — Grouping applied.
- `interval` (string | null) — Time interval applied.
- `total_posts` (integer) — Posts matching the filters.
- `truncated` (boolean) — true if more groups existed than limit.
- `buckets` (object[]) — Groups, largest first.

##### `buckets[]`

- `key` (string) — Group value. A single total when group_by is omitted.
- `metrics.post_count` (integer) — Post count. Always present.
- `metrics.like_sum / like_avg` (number | null) — Like total and mean, when requested.
- `metrics.comment_sum / comment_avg` (number | null) — Comment total and mean, when requested.
- `metrics.view_sum / view_avg` (number | null) — View total and mean, when requested.
- `metrics.share_sum / collect_sum` (number | null) — TikTok-only. Always null here.
- `metrics.follower_avg` (number | null) — Mean follower count of authors.
- `metrics.account_count` (integer | null) — Distinct accounts in the group.
- `series` (object[] | null) — Per-period breakdown, when interval is set.

#### Example

```console
$ solari insight 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_insight_instagram_content_aggregate",
  "arguments": {
    "group_by": "hashtag",
    "query": "이니스프리",
    "metrics": [
      "like_avg",
      "view_sum",
      "account_count"
    ],
    "limit": 5
  }
}
```

#### Notes

- Only post_count is filled unless you name other metrics.
- Coverage is KR, JP, US, and TW, about the last six months. Older since values are clamped.
- interval alone makes one bucket per period. Combined with group_by, each group gets a series.

#### Related tools

- [`solari_catalog_instagram_content_search`](https://finder-dev-pub.bzine.co/docs/tools/catalog-instagram-content-search.md)
- [`solari_insight_tiktok_content_aggregate`](https://finder-dev-pub.bzine.co/docs/tools/insight-tiktok-content-aggregate.md)

### solari catalog instagram tag search

> Use this to find posts with a hashtag or mention.

- **CLI**: `solari catalog instagram tag search`
- **MCP tool**: `solari_catalog_instagram_tag_search`
- **Access**: `solari:read` — Works with any signed-in SOLARI account.
- **Required plan**: Free
- **Credit**: 0

Find an exact hashtag or mention across the full tracked history. For keywords anywhere in the text, use content search.

**When to use it** — When you want a campaign hashtag's reach, or posts that mentioned an account.

**What comes back** — Posts that carry the tag, newest collected first.

#### Parameters

- `query` (string, required, ≤ 200 chars) — Hashtag (#ootd) or mention (@username).
- `limit` (integer, optional, ≥ 1) — How many posts per page.
- `cursor` (string, optional) — next_cursor from the previous page.

#### Response

##### `Response`

- `query` (string) — The tag the lookup actually ran on, without its leading # or @.
- `tag_kind` (string) — hashtag or mention — how the query was read.
- `matched_tags` (integer) — How many stored spellings matched. 0 means the tag has never been seen.
- `items` (object[]) — The posts found.
- `found` (integer) — Posts that hydrated.
- `next_cursor` (string | null) — Pass back as cursor for the next page. null on the last page.
- `mirror_synced_at` (timestamp | null) — When the tag index was last refreshed (UTC).

##### `items[]`

- `id` (uuid) — Post id.
- `slug` (string) — Instagram shortcode.
- `text` (string) — Caption.
- `posted_at` (timestamp) — Published at (UTC).
- `username / user_id / account_id` (string) — Authoring account.
- `like_count / comment_count` (integer) — Engagement.
- `play_count` (integer | null) — Video plays.
- `media_type` (string) — Post format.

#### Example

```console
$ solari catalog instagram tag search query=#ootd limit=3
```

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

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

#### As an MCP call

```json
{
  "name": "solari_catalog_instagram_tag_search",
  "arguments": {
    "query": "#ootd",
    "limit": 3
  }
}
```

#### Notes

- Order is collection time, not posted_at. Sort by posted_at yourself if publish time matters.
- The tag index refreshes daily. mirror_synced_at is the cutoff.
- Matching is exact: #ootd does not match #ootdkorea. Prefix with @ for mentions.

#### Related tools

- [`solari_catalog_instagram_content_search`](https://finder-dev-pub.bzine.co/docs/tools/catalog-instagram-content-search.md)
- [`solari_insight_instagram_content_aggregate`](https://finder-dev-pub.bzine.co/docs/tools/insight-instagram-content-aggregate.md)

### solari catalog tiktok account search

> Find TikTok users by username or name. Use this to get an account_id.

- **CLI**: `solari catalog tiktok account search`
- **MCP tool**: `solari_catalog_tiktok_account_search`
- **Access**: `solari:read` — Works with any signed-in SOLARI account.
- **Required plan**: Free
- **Credit**: 0

Search TikTok for a brand or creator by username or display name. Instagram account_ids will not work here.

**When to use it** — When you have a TikTok name or username, and not an account_id yet.

**What comes back** — Matching accounts, closest first.

#### Parameters

- `query` (string, required) — Name or TikTok username.
- `limit` (integer, optional, ≥ 1) — How many accounts to return.
- `region` (string, optional, ≤ 8 chars) — Country code such as KR or JP. Leave this off to search everywhere.

#### Response

##### `Response`

- `found` (boolean) — Whether anyone matched.
- `items` (object[]) — Accounts that matched, closest first.

##### `items[]`

- `account_id` (uuid) — TikTok account_id. Not interchangeable with Instagram.
- `username` (string) — TikTok username.
- `nickname` (string) — Display name.
- `follower_count / video_count` (integer) — Followers and videos.
- `region` (string | null) — Region code. Many tracked accounts carry none.
- `is_verified / is_private` (boolean) — Verification and privacy flags.
- `is_commerce_user` (boolean) — Whether this is a commerce account.
- `commerce_user_category` (string | null) — Commerce category, e.g. Beauty.
- `profile_url` (string) — Public profile URL.

#### Example

```console
$ solari catalog tiktok account search query=innisfree limit=5
```

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

```json
{
  "found": true,
  "items": [
    {
      "account_id": "019b2137-f76e-7b33-9437-26044fa7b1ed",
      "username": "innisfree_official",
      "nickname": "Innisfreeofficial",
      "follower_count": 143800,
      "video_count": 767,
      "region": "KR",
      "is_verified": true,
      "is_private": false,
      "is_commerce_user": true,
      "commerce_user_category": "Beauty",
      "profile_url": "https://www.tiktok.com/@innisfree_official"
    }
  ]
}
```

#### As an MCP call

```json
{
  "name": "solari_catalog_tiktok_account_search",
  "arguments": {
    "query": "innisfree",
    "limit": 5
  }
}
```

#### Notes

- region keeps only the specified country, and drops accounts with no region. Leave it off unless you need one.
- Usernames SOLARI has not seen yet will not show up here. Pass an exact handle to solari fetch tiktok account, then read it with catalog tiktok account profile.

#### Related tools

- [`solari_catalog_tiktok_account_profile`](https://finder-dev-pub.bzine.co/docs/tools/catalog-tiktok-account-profile.md)
- [`solari_catalog_tiktok_account_posts`](https://finder-dev-pub.bzine.co/docs/tools/catalog-tiktok-account-posts.md)
- [`solari_catalog_instagram_account_search`](https://finder-dev-pub.bzine.co/docs/tools/catalog-instagram-account-search.md)

### solari catalog tiktok account profile

> A TikTok account's profile and recent posts.

- **CLI**: `solari catalog tiktok account profile`
- **MCP tool**: `solari_catalog_tiktok_account_profile`
- **Access**: `solari:read` — Works with any signed-in SOLARI account.
- **Required plan**: Free
- **Credit**: 0

A TikTok account's profile and a preview of recent posts.

**When to use it** — When you want a full picture of a TikTok account.

**What comes back** — Profile, recent posts, and whether the account is being tracked.

#### Parameters

- `account_id` (string, optional, uuid, pattern ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$) — Pass the TikTok account_id or username.
- `username` (string, optional, ≤ 64 chars) — TikTok username. Ignored when account_id is set.

#### Response

##### `Response`

- `account_id` (uuid) — TikTok account_id.
- `username / nickname / bio` (string) — Username, display name, and bio.
- `bio_links` (string[]) — Links in the bio.
- `follower_count / following_count` (integer) — Followers and following.
- `heart_count` (integer) — Lifetime likes across the account.
- `video_count` (integer) — Videos published.
- `is_verified / is_private` (boolean) — Verification and privacy flags.
- `is_commerce_user / commerce_user_category` (boolean · string) — Commerce status and category.
- `region / language` (string | null) — Region and language codes.
- `avatar_url / profile_url` (string) — Avatar and public profile link.
- `tracked` (boolean) — Whether the account is on the regular crawl.
- `sync_status` (string) — Crawl state.
- `synced_at` (timestamp) — Last crawl time.
- `recent_posts` (object[]) — Recent post previews.
- `fetched_on_demand` (boolean) — true if the account was fetched live on this call.

##### `recent_posts[]`

- `post_id` (uuid) — TikTok post id. Not interchangeable with Instagram.
- `video_id` (string) — Public numeric id from the TikTok URL.
- `url` (string) — Public permalink.
- `account_id` (uuid) — Author account_id.
- `username` (string) — Author username.
- `post_type` (string) — video or carousel.
- `posted_at` (timestamp) — Published at (UTC).
- `caption` (string) — Caption.
- `duration_seconds` (integer) — Video length.
- `width / height` (integer) — Resolution.
- `play_count` (integer) — Plays.
- `like_count` (integer) — Likes.
- `comment_count` (integer) — Comments.
- `share_count` (integer) — Shares.
- `collect_count` (integer) — Saves.
- `is_ad` (boolean) — TikTok ad flag.
- `is_pinned` (boolean) — Pinned on the profile.
- `aigc_label_type` (string | null) — AI-content label, when TikTok sets one.
- `original_language_code` (string | null) — Source language.
- `cover_url` (string) — Cover image URL.
- `video_url` (string) — Video file URL.
- `images` (string[]) — Carousel slides. Empty for video.
- `hashtags` (string[]) — Hashtags from the caption.
- `mentions` (string[]) — Usernames mentioned in the caption.
- `transcript` (string | null) — Spoken transcript. Only when include_transcript=true.

#### Example

```console
$ solari catalog tiktok account profile username=innisfree_official
```

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

```json
{
  "account_id": "019b2137-f76e-7b33-9437-26044fa7b1ed",
  "username": "innisfree_official",
  "nickname": "Innisfreeofficial",
  "bio": "NATURE MEETS KOREAN SKIN SCIENCE",
  "bio_links": [
    "https://linktr.ee/innisfree_official"
  ],
  "follower_count": 143900,
  "following_count": 14,
  "heart_count": 2200000,
  "video_count": 767,
  "is_verified": true,
  "is_private": false,
  "is_commerce_user": true,
  "commerce_user_category": "Beauty",
  "region": "KR",
  "language": null,
  "avatar_url": "https://p16-common-sign.tiktokcdn-eu.com/tos-alisg-avt-0068/3f8e48dc4a284a8ead37e93175ebdb86~tplv-tiktokx-cropcenter:720:720.jpeg?dr=10399&refresh_token=04b90255&x-expires=1788541200&x-signature=Gd3gJu4HyBZPCr%2FqEevyDs6 …",
  "profile_url": "https://www.tiktok.com/@innisfree_official",
  "sync_status": "OK",
  "tracked": true,
  "synced_at": "2026-09-02T17:16:05.835000Z",
  "recent_posts": [
    {
      "post_id": "01a0631e-f0df-7e9d-a09b-d84bc31d3834",
      "video_id": "7680375687139642645",
      "url": "https://www.tiktok.com/@innisfree_official/video/7680375687139642645",
      "account_id": "019b2137-f76e-7b33-9437-26044fa7b1ed",
      "username": "innisfree_official",
      "post_type": "video",
      "posted_at": "2026-09-02T12:00:00Z",
      "caption": "Deeply hydrated skin—NO OFF HOURS. 💚  wherever the day takes MINGYU—his hydration stays SUPERCHARGED ⚡️ Green Tea Ceramide Milk: Lightweight milky toner that won't clog your pores  Green Tea Ceramide Mist: Touch-free, fa …",
      "duration_seconds": 23,
      "width": 1080,
      "height": 1920,
      "play_count": 493,
      "like_count": 37,
      "comment_count": 2,
      "share_count": 0,
      "collect_count": 3,
      "is_ad": false,
      "is_pinned": false,
      "aigc_label_type": null,
      "original_language_code": null,
      "cover_url": "https://smr-images-a.bzine.co/tiktok/users/019b2137-f76e-7b33-9437-26044fa7b1ed/posts/01a0631e-f0df-7e9d-a09b-d84bc31d3834/medias/cover.jpg",
      "video_url": "https://smr-images-a.bzine.co/tiktok/users/019b2137-f76e-7b33-9437-26044fa7b1ed/posts/01a0631e-f0df-7e9d-a09b-d84bc31d3834/medias/origin.mp4",
      "images": [],
      "hashtags": [],
      "mentions": [],
      "transcript": null
    },
    "… 5 more"
  ],
  "fetched_on_demand": false
}
```

#### As an MCP call

```json
{
  "name": "solari_catalog_tiktok_account_profile",
  "arguments": {
    "username": "innisfree_official"
  }
}
```

#### Notes

- This reads the catalog only. If the username is missing, call solari fetch tiktok account username=… then retry.
- A not-found error means the handle is not in the catalog.

#### Related tools

- [`solari_catalog_tiktok_account_posts`](https://finder-dev-pub.bzine.co/docs/tools/catalog-tiktok-account-posts.md)
- [`solari_catalog_tiktok_account_search`](https://finder-dev-pub.bzine.co/docs/tools/catalog-tiktok-account-search.md)
- [`solari_catalog_instagram_account_profile`](https://finder-dev-pub.bzine.co/docs/tools/catalog-instagram-account-profile.md)

### solari catalog tiktok account posts

> Posts from a TikTok account.

- **CLI**: `solari catalog tiktok account posts`
- **MCP tool**: `solari_catalog_tiktok_account_posts`
- **Access**: `solari:read` — Works with any signed-in SOLARI account.
- **Required plan**: Free
- **Credit**: 0

List a TikTok account's posts. Turn on include_transcript only when the spoken words matter.

**When to use it** — When you need more posts than the profile preview, or a date range or format.

**What comes back** — Posts, with transcripts when you ask for them.

#### Parameters

- `account_id` (string, optional, uuid, pattern ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$) — Pass the TikTok account_id or username.
- `username` (string, optional, ≤ 64 chars) — TikTok username. Ignored when account_id is set.
- `limit` (integer, optional, ≥ 1) — How many posts per page.
- `offset` (integer, optional, default 0, ≥ 0) — How many posts to skip.
- `since` (string, optional, pattern ^\d{4}-\d{2}-\d{2}$) — Only posts on or after this UTC date (YYYY-MM-DD).
- `until` (string, optional, pattern ^\d{4}-\d{2}-\d{2}$) — Only posts on or before this UTC date (YYYY-MM-DD).
- `post_type` (enum, optional) — Limit to video or carousel. Values: `video`, `carousel`.
- `include_transcript` (boolean, optional, default false) — Include spoken transcripts.

#### Response

##### `Response`

- `found` (boolean) — false if the username is not on TikTok.
- `account_id / username` (string) — The resolved account.
- `total` (integer) — Posts matching the filters.
- `has_more` (boolean) — Whether there is another page.
- `items` (object[]) — Posts, newest first.
- `fetched_on_demand` (boolean) — true when only the most recent posts are available so far.

##### `items[]`

- `post_id` (uuid) — TikTok post id. Not interchangeable with Instagram.
- `video_id` (string) — Public numeric id from the TikTok URL.
- `url` (string) — Public permalink.
- `account_id` (uuid) — Author account_id.
- `username` (string) — Author username.
- `post_type` (string) — video or carousel.
- `posted_at` (timestamp) — Published at (UTC).
- `caption` (string) — Caption.
- `duration_seconds` (integer) — Video length.
- `width / height` (integer) — Resolution.
- `play_count` (integer) — Plays.
- `like_count` (integer) — Likes.
- `comment_count` (integer) — Comments.
- `share_count` (integer) — Shares.
- `collect_count` (integer) — Saves.
- `is_ad` (boolean) — TikTok ad flag.
- `is_pinned` (boolean) — Pinned on the profile.
- `aigc_label_type` (string | null) — AI-content label, when TikTok sets one.
- `original_language_code` (string | null) — Source language.
- `cover_url` (string) — Cover image URL.
- `video_url` (string) — Video file URL.
- `images` (string[]) — Carousel slides. Empty for video.
- `hashtags` (string[]) — Hashtags from the caption.
- `mentions` (string[]) — Usernames mentioned in the caption.
- `transcript` (string | null) — Spoken transcript. Only when include_transcript=true.

#### Example

```console
$ solari catalog tiktok account posts username=innisfree_official limit=2
```

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

```json
{
  "found": true,
  "account_id": "019b2137-f76e-7b33-9437-26044fa7b1ed",
  "username": "innisfree_official",
  "total": 87,
  "has_more": true,
  "items": [
    {
      "post_id": "01a0631e-f0df-7e9d-a09b-d84bc31d3834",
      "video_id": "7680375687139642645",
      "url": "https://www.tiktok.com/@innisfree_official/video/7680375687139642645",
      "account_id": "019b2137-f76e-7b33-9437-26044fa7b1ed",
      "username": "innisfree_official",
      "post_type": "video",
      "posted_at": "2026-09-02T12:00:00Z",
      "caption": "Deeply hydrated skin—NO OFF HOURS. 💚  wherever the day takes MINGYU—his hydration stays SUPERCHARGED ⚡️ Green Tea Ceramide Milk: Lightweight milky toner that won't clog your pores  Green Tea Ceramide Mist: Touch-free, fa …",
      "duration_seconds": 23,
      "width": 1080,
      "height": 1920,
      "play_count": 493,
      "like_count": 37,
      "comment_count": 2,
      "share_count": 0,
      "collect_count": 3,
      "is_ad": false,
      "is_pinned": false,
      "aigc_label_type": null,
      "original_language_code": null,
      "cover_url": "https://smr-images-b.bzine.co/tiktok/users/019b2137-f76e-7b33-9437-26044fa7b1ed/posts/01a0631e-f0df-7e9d-a09b-d84bc31d3834/medias/cover.jpg",
      "video_url": "https://smr-images-a.bzine.co/tiktok/users/019b2137-f76e-7b33-9437-26044fa7b1ed/posts/01a0631e-f0df-7e9d-a09b-d84bc31d3834/medias/origin.mp4",
      "images": [],
      "hashtags": [],
      "mentions": [],
      "transcript": null
    },
    "… 1 more"
  ],
  "fetched_on_demand": false
}
```

#### As an MCP call

```json
{
  "name": "solari_catalog_tiktok_account_posts",
  "arguments": {
    "username": "innisfree_official",
    "limit": 2
  }
}
```

#### Notes

- Transcripts are large, so include_transcript is off by default.
- This reads the catalog only. If the username is missing, call solari fetch tiktok posts username=… then retry.

#### Related tools

- [`solari_catalog_tiktok_account_profile`](https://finder-dev-pub.bzine.co/docs/tools/catalog-tiktok-account-profile.md)
- [`solari_catalog_tiktok_content_detail`](https://finder-dev-pub.bzine.co/docs/tools/catalog-tiktok-content-detail.md)
- [`solari_catalog_instagram_account_posts`](https://finder-dev-pub.bzine.co/docs/tools/catalog-instagram-account-posts.md)

### solari catalog tiktok content detail

> A TikTok post, by id, video_id, or URL.

- **CLI**: `solari catalog tiktok content detail`
- **MCP tool**: `solari_catalog_tiktok_content_detail`
- **Access**: `solari:read` — Works with any signed-in SOLARI account.
- **Required plan**: Free
- **Credit**: 0

Load a TikTok post by post_id, video_id, or public URL.

**When to use it** — When you need a post. For many ids at once, use content batch.

**What comes back** — The post, with a transcript when one exists.

#### Parameters

- `post_id` (string, optional, uuid, pattern ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$) — post_id. Pass this, video_id, or url.
- `video_id` (string, optional, pattern ^\d{15,20}$) — Public numeric TikTok id.
- `url` (string, optional, ≤ 512 chars) — Public TikTok post URL.

#### Response

##### `Response`

- `item` (object | null) — The post. null if it does not exist or is not public.
- `fetched_on_demand` (boolean) — true if the post was fetched live on this call.

##### `item`

- `post_id` (uuid) — TikTok post id. Not interchangeable with Instagram.
- `video_id` (string) — Public numeric id from the TikTok URL.
- `url` (string) — Public permalink.
- `account_id` (uuid) — Author account_id.
- `username` (string) — Author username.
- `post_type` (string) — video or carousel.
- `posted_at` (timestamp) — Published at (UTC).
- `caption` (string) — Caption.
- `duration_seconds` (integer) — Video length.
- `width / height` (integer) — Resolution.
- `play_count` (integer) — Plays.
- `like_count` (integer) — Likes.
- `comment_count` (integer) — Comments.
- `share_count` (integer) — Shares.
- `collect_count` (integer) — Saves.
- `is_ad` (boolean) — TikTok ad flag.
- `is_pinned` (boolean) — Pinned on the profile.
- `aigc_label_type` (string | null) — AI-content label, when TikTok sets one.
- `original_language_code` (string | null) — Source language.
- `cover_url` (string) — Cover image URL.
- `video_url` (string) — Video file URL.
- `images` (string[]) — Carousel slides. Empty for video.
- `hashtags` (string[]) — Hashtags from the caption.
- `mentions` (string[]) — Usernames mentioned in the caption.
- `transcript` (string | null) — Spoken transcript. Only when include_transcript=true.

#### Example

```console
$ solari catalog tiktok content detail video_id=7680375687139642645 include_transcript=true
```

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

```json
{
  "item": {
    "post_id": "01a0631e-f0df-7e9d-a09b-d84bc31d3834",
    "video_id": "7680375687139642645",
    "url": "https://www.tiktok.com/@innisfree_official/video/7680375687139642645",
    "account_id": "019b2137-f76e-7b33-9437-26044fa7b1ed",
    "username": "innisfree_official",
    "post_type": "video",
    "posted_at": "2026-09-02T12:00:00Z",
    "caption": "Deeply hydrated skin—NO OFF HOURS. 💚  wherever the day takes MINGYU—his hydration stays SUPERCHARGED ⚡️ Green Tea Ceramide Milk: Lightweight milky toner that won't clog your pores  Green Tea Ceramide Mist: Touch-free, fa …",
    "duration_seconds": 23,
    "width": 1080,
    "height": 1920,
    "play_count": 493,
    "like_count": 37,
    "comment_count": 2,
    "share_count": 0,
    "collect_count": 3,
    "is_ad": false,
    "is_pinned": false,
    "aigc_label_type": null,
    "original_language_code": null,
    "cover_url": "https://smr-images-b.bzine.co/tiktok/users/019b2137-f76e-7b33-9437-26044fa7b1ed/posts/01a0631e-f0df-7e9d-a09b-d84bc31d3834/medias/cover.jpg",
    "video_url": "https://smr-images-c.bzine.co/tiktok/users/019b2137-f76e-7b33-9437-26044fa7b1ed/posts/01a0631e-f0df-7e9d-a09b-d84bc31d3834/medias/origin.mp4",
    "images": [],
    "hashtags": [],
    "mentions": [],
    "transcript": null
  },
  "fetched_on_demand": false
}
```

#### As an MCP call

```json
{
  "name": "solari_catalog_tiktok_content_detail",
  "arguments": {
    "video_id": "7680375687139642645"
  }
}
```

#### Notes

- vm.tiktok.com and vt.tiktok.com short links work too.
- This reads the catalog only. Fetch does not take a post URL. If you have the author's username, call solari fetch tiktok posts username=… then retry.

#### Related tools

- [`solari_catalog_tiktok_content_batch`](https://finder-dev-pub.bzine.co/docs/tools/catalog-tiktok-content-batch.md)
- [`solari_catalog_tiktok_account_posts`](https://finder-dev-pub.bzine.co/docs/tools/catalog-tiktok-account-posts.md)

### solari catalog tiktok content batch

> Several TikTok posts at once.

- **CLI**: `solari catalog tiktok content batch`
- **MCP tool**: `solari_catalog_tiktok_content_batch`
- **Access**: `solari:read` — Works with any signed-in SOLARI account.
- **Required plan**: Free
- **Credit**: 0

Load captions and metrics for a list of TikTok post ids. Ids that cannot be found are skipped.

**When to use it** — When you have ids from search or account posts and want them together.

**What comes back** — The posts that were found.

#### Parameters

- `post_ids` (uuid[], required, 1–100 items, uuid) — TikTok post ids to load, up to 100.
- `sort` (enum, optional, default "recent") — Order by newest, or by engagement. Values: `recent`, `engagement`.
- `include_transcript` (boolean, optional, default false) — Include spoken transcripts.

#### Response

##### `Response`

- `requested` (integer) — How many ids were sent.
- `found` (integer) — How many resolved.
- `items` (object[]) — The posts found.

##### `items[]`

- `post_id` (uuid) — TikTok post id. Not interchangeable with Instagram.
- `video_id` (string) — Public numeric id from the TikTok URL.
- `url` (string) — Public permalink.
- `account_id` (uuid) — Author account_id.
- `username` (string) — Author username.
- `post_type` (string) — video or carousel.
- `posted_at` (timestamp) — Published at (UTC).
- `caption` (string) — Caption.
- `duration_seconds` (integer) — Video length.
- `width / height` (integer) — Resolution.
- `play_count` (integer) — Plays.
- `like_count` (integer) — Likes.
- `comment_count` (integer) — Comments.
- `share_count` (integer) — Shares.
- `collect_count` (integer) — Saves.
- `is_ad` (boolean) — TikTok ad flag.
- `is_pinned` (boolean) — Pinned on the profile.
- `aigc_label_type` (string | null) — AI-content label, when TikTok sets one.
- `original_language_code` (string | null) — Source language.
- `cover_url` (string) — Cover image URL.
- `video_url` (string) — Video file URL.
- `images` (string[]) — Carousel slides. Empty for video.
- `hashtags` (string[]) — Hashtags from the caption.
- `mentions` (string[]) — Usernames mentioned in the caption.
- `transcript` (string | null) — Spoken transcript. Only when include_transcript=true.

#### Example

```console
$ solari catalog tiktok content batch post_ids='["01a0631e-f0df-7e9d-a09b-d84bc31d3834"]'
```

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

```json
{
  "requested": 1,
  "found": 1,
  "items": [
    {
      "post_id": "01a0631e-f0df-7e9d-a09b-d84bc31d3834",
      "video_id": "7680375687139642645",
      "url": "https://www.tiktok.com/@innisfree_official/video/7680375687139642645",
      "account_id": "019b2137-f76e-7b33-9437-26044fa7b1ed",
      "username": "innisfree_official",
      "post_type": "video",
      "posted_at": "2026-09-02T12:00:00Z",
      "caption": "Deeply hydrated skin—NO OFF HOURS. 💚  wherever the day takes MINGYU—his hydration stays SUPERCHARGED ⚡️ Green Tea Ceramide Milk: Lightweight milky toner that won't clog your pores  Green Tea Ceramide Mist: Touch-free, fa …",
      "duration_seconds": 23,
      "width": 1080,
      "height": 1920,
      "play_count": 493,
      "like_count": 37,
      "comment_count": 2,
      "share_count": 0,
      "collect_count": 3,
      "is_ad": false,
      "is_pinned": false,
      "aigc_label_type": null,
      "original_language_code": null,
      "cover_url": "https://smr-images-b.bzine.co/tiktok/users/019b2137-f76e-7b33-9437-26044fa7b1ed/posts/01a0631e-f0df-7e9d-a09b-d84bc31d3834/medias/cover.jpg",
      "video_url": "https://smr-images-b.bzine.co/tiktok/users/019b2137-f76e-7b33-9437-26044fa7b1ed/posts/01a0631e-f0df-7e9d-a09b-d84bc31d3834/medias/origin.mp4",
      "images": [],
      "hashtags": [],
      "mentions": [],
      "transcript": null
    }
  ]
}
```

#### As an MCP call

```json
{
  "name": "solari_catalog_tiktok_content_batch",
  "arguments": {
    "post_ids": [
      "01a0631e-f0df-7e9d-a09b-d84bc31d3834"
    ]
  }
}
```

#### Notes

- This takes SOLARI post ids only. A numeric video id goes to content detail as video_id.
- TikTok post ids and Instagram post ids are not interchangeable.

#### Related tools

- [`solari_catalog_tiktok_content_detail`](https://finder-dev-pub.bzine.co/docs/tools/catalog-tiktok-content-detail.md)
- [`solari_catalog_tiktok_content_search`](https://finder-dev-pub.bzine.co/docs/tools/catalog-tiktok-content-search.md)

### solari catalog tiktok content search

> Use this to search TikTok captions and video transcripts.

- **CLI**: `solari catalog tiktok content search`
- **MCP tool**: `solari_catalog_tiktok_content_search`
- **Access**: `solari:read` — Works with any signed-in SOLARI account.
- **Required plan**: Free
- **Credit**: 0

Keyword search over tracked TikTok posts in KR, JP, US, and TW, covering about the last six months.

**When to use it** — When you want TikTok posts about a topic, or about what is said on screen.

**What comes back** — Posts ranked by relevance, with matching text highlighted.

#### Parameters

- `query` (string, required) — Words to search for.
- `region` (enum, optional, default "KR") — KR, JP, US, or TW. Values: `KR`, `JP`, `US`, `TW`.
- `limit` (integer, optional, ≥ 1) — How many posts per page.
- `offset` (integer, optional, default 0, ≥ 0) — How many posts to skip.
- `since` (string, optional, pattern ^\d{4}-\d{2}-\d{2}$) — Only posts on or after this UTC date (YYYY-MM-DD).
- `until` (string, optional, pattern ^\d{4}-\d{2}-\d{2}$) — Only posts on or before this UTC date (YYYY-MM-DD).

#### Response

##### `Response`

- `query / region` (string) — The query and region applied.
- `total` (integer) — Total matches. Exact up to 10,000, then saturates.
- `took_ms` (integer) — Search time.
- `items` (object[]) — Hits, score descending.

##### `items[]`

- `post_id / video_id / url` (string) — Post identifiers and public link.
- `account_id / username` (string) — Authoring account.
- `caption` (string) — Caption.
- `user_bio` (string) — Author bio.
- `transcription_text` (string | null) — Speech transcript — part of the searched text.
- `transcription_language` (string | null) — Transcript language code.
- `post_type` (string) — video or carousel.
- `posted_at` (timestamp) — Published at (UTC).
- `duration_seconds` (integer) — Video length.
- `play_count / like_count / comment_count / share_count / collect_count` (integer) — Engagement.
- `follower_count` (integer) — Author follower count.
- `is_ad` (boolean) — TikTok's own ad flag.
- `cover_url` (string) — Cover image.
- `score` (number) — Relevance score.
- `highlight` (object) — Matched fragments per field.

#### Example

```console
$ solari catalog tiktok content search query="올리브영 세일" limit=3
```

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

```json
{
  "query": "올리브영 세일",
  "region": "KR",
  "total": 4041,
  "took_ms": 29,
  "items": [
    {
      "post_id": "01a05c46-9a08-7e92-a40e-b1a039103118",
      "video_id": "7679484556189207815",
      "url": "https://www.tiktok.com/@flos_bonita/video/7679484556189207815",
      "account_id": "0196cb39-87a7-7be3-ac4a-4a80b7818a90",
      "username": "flos_bonita",
      "caption": "태닝한 산리오 키링이라니…☀️🥹💗 푸드올로지 X 산리오 콜라보 실물 너무 귀엽잖아!! 헬로키티·쿠로미·한교동·마이멜로디까지🎀 제품마다 다른 키링이라 산리오 덕후들 취향 제대로 저격💘 올영 세일 시작했으니 얼른 구경해봐요👀🛒 #푸드올로지 #태닝키티 #올리브영추천템 #올영세일",
      "user_bio": "화미 프로필 링크",
      "transcription_text": "살리오 덕후라면 절대 그냥 넘길 수 없는 영상 오늘부터 시작인 올리브영 세일과 함께 푸드올로지와 살리오 콜라보 나왔어요 이번 콜라보는 젤리 폼 앰플 젤리 3 종으로 피디아렌 앰플 젤리 글루타치원 씨 앰플 젤리 히알루론산 앰플 젤리까지 제품마다 귀여운 살리오 굿즈도 함께 만나 볼 수 있는데 헬로키티 크로미 한교동부터 마이 멜로디까지 저는 역시 헬로키티 더 쿠답게 키티 키링으로 폼구 최애 캐릭터 …",
      "transcription_language": "ko",
      "post_type": "video",
      "posted_at": "2026-08-29T16:02:22Z",
      "duration_seconds": 37,
      "play_count": 955,
      "like_count": 26,
      "comment_count": 0,
      "share_count": 0,
      "collect_count": 5,
      "follower_count": 1345,
      "is_ad": true,
      "cover_url": "https://p16-common-sign.tiktokcdn-eu.com/tos-alisg-p-0037/oEu4VAolaEBAAYjMAjBtiyCIAABiPp9TOCAME~tplv-tiktokx-origin.image?dr=10395&x-expires=1788426000&x-signature=FAP0C10M1M1gEwD4YMB03pYd0YA%3D&t=4d5b0474&ps=13740610&sh …",
      "score": 53.787056,
      "highlight": {
        "caption": [
          "헬로키티·쿠로미·한교동·마이멜로디까지🎀 제품마다 다른 키링이라 산리오 덕후들 취향 제대로 저격💘 올<mark>영</mark> <mark>세일</mark> 시작했으니 얼른 구경해봐요👀🛒 #푸드올로지 #태닝키티 #올리브영추천템 #올영세일"
        ],
        "user_bio": [],
        "transcription_text": [
          "살리오 덕후라면 절대 그냥 넘길 수 없는 영상 오늘부터 시작인 <mark>올리브</mark><mark>영</mark> <mark>세일</mark>과 함께 푸드올로지와 살리오 콜라보 나왔어요 이번 콜라보는 젤리 폼 앰플 젤리 3 종으로 피디아렌 앰플 젤리 글루타치원 씨 앰플 젤리 히알루론산 앰플 젤리까지 제품마다 귀여운 살리오 굿즈도 함께",
          "… 1 more"
        ]
      }
    },
    "… 2 more"
  ]
}
```

#### As an MCP call

```json
{
  "name": "solari_catalog_tiktok_content_search",
  "arguments": {
    "query": "올리브영 세일",
    "limit": 3
  }
}
```

#### Notes

- offset tops out at 9,800. Narrow the date range to go deeper.
- total counts up to 10,000, then stops.

#### Related tools

- [`solari_insight_tiktok_content_aggregate`](https://finder-dev-pub.bzine.co/docs/tools/insight-tiktok-content-aggregate.md)
- [`solari_catalog_tiktok_content_batch`](https://finder-dev-pub.bzine.co/docs/tools/catalog-tiktok-content-batch.md)
- [`solari_catalog_instagram_content_search`](https://finder-dev-pub.bzine.co/docs/tools/catalog-instagram-content-search.md)

### solari insight tiktok content aggregate

> Use this to count TikTok posts.

- **CLI**: `solari insight tiktok content aggregate`
- **MCP tool**: `solari_insight_tiktok_content_aggregate`
- **Access**: `solari:read` — Works with any signed-in SOLARI account.
- **Required plan**: Free
- **Credit**: 0

Add up tracked TikTok posts by account, format, hashtag, mention, or keyword.

**When to use it** — When you need cadence, hashtag mix, or average plays. For the posts themselves, use content search.

**What comes back** — Counts per group, largest first. Extra metrics only if you ask for them.

#### Parameters

- `region` (enum, optional, default "KR") — KR, JP, US, or TW. Values: `KR`, `JP`, `US`, `TW`.
- `group_by` (enum, optional) — How to split the counts. Values: `account`, `post_type`, `hashtag`, `mention`, `caption_keyword`.
- `interval` (enum, optional) — Add a time series at this calendar interval. Values: `day`, `week`, `month`.
- `metrics` (string[], optional) — Extra metrics besides post_count. Values: `like_sum`, `like_avg`, `comment_sum`, `comment_avg`, `view_sum`, `view_avg`, `share_sum`, `share_avg`, `collect_sum`, `collect_avg`, `follower_avg`, `account_count`.
- `query` (string, optional) — Keyword filter over captions and transcripts.
- `usernames` (string[], optional) — Only these TikTok usernames.
- `hashtags` (string[], optional) — Only posts that have all of these hashtags.
- `mentions` (string[], optional) — Only posts that mention all of these usernames.
- `post_types` (string[], optional) — Only these formats. Values: `video`, `carousel`.
- `since` (string, optional, pattern ^\d{4}-\d{2}-\d{2}$) — Only posts on or after this UTC date (YYYY-MM-DD).
- `until` (string, optional, pattern ^\d{4}-\d{2}-\d{2}$) — Only posts on or before this UTC date (YYYY-MM-DD).
- `limit` (integer, optional, ≥ 1) — How many groups to return.

#### Response

##### `Response`

- `region` (string) — Region aggregated.
- `since` (date) — Start date actually used.
- `until` (date | null) — End date actually used.
- `group_by` (string | null) — Grouping applied.
- `interval` (string | null) — Time interval applied.
- `total_posts` (integer) — Posts matching the filters.
- `truncated` (boolean) — true if more groups existed than limit.
- `buckets` (object[]) — Groups, largest first.

##### `buckets[]`

- `key` (string) — Group value. A single total when group_by is omitted.
- `metrics.post_count` (integer) — Post count. Always present.
- `metrics.like_sum / like_avg` (number | null) — Like total and mean, when requested.
- `metrics.comment_sum / comment_avg` (number | null) — Comment total and mean, when requested.
- `metrics.view_sum / view_avg` (number | null) — Play total and mean, when requested.
- `metrics.share_sum / collect_sum` (number | null) — Share and save totals, when requested.
- `metrics.follower_avg` (number | null) — Mean follower count of authors.
- `metrics.account_count` (integer | null) — Distinct accounts in the group.
- `series` (object[] | null) — Per-period breakdown, when interval is set.

#### Example

```console
$ solari insight tiktok content aggregate group_by=account query="이니스프리" metrics='["view_sum","like_avg","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": "account",
  "interval": null,
  "total_posts": 20,
  "truncated": true,
  "buckets": [
    {
      "key": "merryview_",
      "metrics": {
        "post_count": 2,
        "like_sum": null,
        "like_avg": 2378.5,
        "comment_sum": null,
        "comment_avg": null,
        "view_sum": 179504,
        "view_avg": null,
        "share_sum": null,
        "share_avg": null,
        "collect_sum": null,
        "collect_avg": null,
        "follower_avg": null,
        "account_count": 1
      },
      "series": null
    },
    {
      "key": "_kimdayun_",
      "metrics": {
        "post_count": 1,
        "like_sum": null,
        "like_avg": 1829,
        "comment_sum": null,
        "comment_avg": null,
        "view_sum": 102000,
        "view_avg": null,
        "share_sum": null,
        "share_avg": null,
        "collect_sum": null,
        "collect_avg": null,
        "follower_avg": null,
        "account_count": 1
      },
      "series": null
    },
    "… 3 more"
  ]
}
```

#### As an MCP call

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

#### Notes

- view_* is plays. share_* and collect_* are filled here, unlike Instagram.
- Coverage is KR, JP, US, and TW, about the last six months. Older since values are clamped.

#### Related tools

- [`solari_catalog_tiktok_content_search`](https://finder-dev-pub.bzine.co/docs/tools/catalog-tiktok-content-search.md)
- [`solari_insight_instagram_content_aggregate`](https://finder-dev-pub.bzine.co/docs/tools/insight-instagram-content-aggregate.md)

### solari fetch instagram account

> Ingest one Instagram handle into the catalog.

- **CLI**: `solari fetch instagram account`
- **MCP tool**: `solari_fetch_instagram_account`
- **Access**: `solari:read` — Works with any signed-in SOLARI account.
- **Required plan**: Free
- **Credit**: 0

Add one Instagram account to the SOLARI catalog by exact username. This is not a search. If it is already stored, nothing is scraped.

**When to use it** — When catalog search does not know an exact handle you already have.

**What comes back** — Whether it was ingested, the account_id, and the catalog command to read it.

#### Parameters

- `username` (string, required, ≤ 64 chars) — Instagram username.

#### Response

##### `Response`

- `ingested` (boolean) — true if this call collected it live.
- `already_tracked` (boolean) — true if it was already in the catalog.
- `fetched_on_demand` (boolean) — Same as ingested.
- `account_id` (uuid) — The ingested account.
- `username` (string) — Resolved handle.
- `note` (string) — What to expect next.
- `next` (string) — Catalog command to read the result.

#### Example

```console
$ solari fetch instagram account username=innisfreeofficial
```

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

```json
{
  "ingested": false,
  "already_tracked": true,
  "fetched_on_demand": false,
  "account_id": "018cabce-14cc-7544-8890-7811ec33ef74",
  "username": "innisfreeofficial",
  "note": "Already in the SOLARI catalog. Nothing was scraped.",
  "next": "solari catalog instagram account profile username=innisfreeofficial"
}
```

#### As an MCP call

```json
{
  "name": "solari_fetch_instagram_account",
  "arguments": {
    "username": "innisfreeofficial"
  }
}
```

#### Notes

- Do not use this to search a name. Use catalog account search first.
- A first-time ingest can take several seconds. Metrics and collaborations stay empty until the crawl finishes.

#### Related tools

- [`solari_catalog_instagram_account_search`](https://finder-dev-pub.bzine.co/docs/tools/catalog-instagram-account-search.md)
- [`solari_catalog_instagram_account_profile`](https://finder-dev-pub.bzine.co/docs/tools/catalog-instagram-account-profile.md)
- [`solari_fetch_instagram_posts`](https://finder-dev-pub.bzine.co/docs/tools/fetch-instagram-posts.md)

### solari fetch instagram posts

> Collect one Instagram account's posts into the catalog.

- **CLI**: `solari fetch instagram posts`
- **MCP tool**: `solari_fetch_instagram_posts`
- **Access**: `solari:read` — Works with any signed-in SOLARI account.
- **Required plan**: Free
- **Credit**: 0

Collect posts for one Instagram account into the SOLARI catalog by exact username. This is not a post listing. If the handle is already stored, nothing is scraped.

**When to use it** — When catalog posts does not know an exact handle you already have.

**What comes back** — Whether it was ingested, how many posts came back, and the catalog command to read them.

#### Parameters

- `username` (string, required, ≤ 64 chars) — Instagram username.

#### Response

##### `Response`

- `ingested` (boolean) — true if this call collected it live.
- `already_tracked` (boolean) — true if it was already in the catalog.
- `fetched_on_demand` (boolean) — Same as ingested.
- `found` (boolean) — false if the handle could not be collected.
- `account_id` (uuid) — The ingested account.
- `username` (string) — Resolved handle.
- `total` (integer) — Posts available so far.
- `note` (string) — What to expect next.
- `next` (string) — Catalog command to read the result.

#### Example

```console
$ solari fetch instagram posts username=innisfreeofficial
```

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

```json
{
  "ingested": false,
  "already_tracked": true,
  "fetched_on_demand": false,
  "found": true,
  "account_id": "018cabce-14cc-7544-8890-7811ec33ef74",
  "username": "innisfreeofficial",
  "total": 12,
  "note": "Already in the SOLARI catalog. Nothing was scraped.",
  "next": "solari catalog instagram account posts username=innisfreeofficial"
}
```

#### As an MCP call

```json
{
  "name": "solari_fetch_instagram_posts",
  "arguments": {
    "username": "innisfreeofficial"
  }
}
```

#### Notes

- Do not use this to list stored posts. Use catalog instagram account posts for that.
- A first-time ingest can take several seconds. Only recent posts exist until the crawl finishes.

#### Related tools

- [`solari_fetch_instagram_account`](https://finder-dev-pub.bzine.co/docs/tools/fetch-instagram-account.md)
- [`solari_catalog_instagram_account_posts`](https://finder-dev-pub.bzine.co/docs/tools/catalog-instagram-account-posts.md)
- [`solari_catalog_instagram_account_search`](https://finder-dev-pub.bzine.co/docs/tools/catalog-instagram-account-search.md)

### solari fetch tiktok account

> Ingest one TikTok handle into the catalog.

- **CLI**: `solari fetch tiktok account`
- **MCP tool**: `solari_fetch_tiktok_account`
- **Access**: `solari:read` — Works with any signed-in SOLARI account.
- **Required plan**: Free
- **Credit**: 0

Add one TikTok account to the SOLARI catalog by exact username. This is not a search. If it is already stored, nothing is scraped.

**When to use it** — When catalog search does not know an exact handle you already have.

**What comes back** — Whether it was ingested, the account_id, and the catalog command to read it.

#### Parameters

- `username` (string, required, ≤ 64 chars) — TikTok username.

#### Response

##### `Response`

- `ingested` (boolean) — true if this call collected it live.
- `already_tracked` (boolean) — true if it was already in the catalog.
- `fetched_on_demand` (boolean) — Same as ingested.
- `account_id` (uuid) — The ingested account.
- `username` (string) — Resolved handle.
- `note` (string) — What to expect next.
- `next` (string) — Catalog command to read the result.

#### Example

```console
$ solari fetch tiktok account username=innisfree_official
```

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

```json
{
  "ingested": false,
  "already_tracked": true,
  "fetched_on_demand": false,
  "account_id": "01a0631e-f0df-7e9d-a09b-d84bc31d3834",
  "username": "innisfree_official",
  "note": "Already in the SOLARI catalog. Nothing was scraped.",
  "next": "solari catalog tiktok account profile username=innisfree_official"
}
```

#### As an MCP call

```json
{
  "name": "solari_fetch_tiktok_account",
  "arguments": {
    "username": "innisfree_official"
  }
}
```

#### Notes

- Do not use this to search a name. Use catalog account search first.
- A first-time ingest can take 10 to 40 seconds. Only recent posts exist until the crawl finishes.

#### Related tools

- [`solari_catalog_tiktok_account_search`](https://finder-dev-pub.bzine.co/docs/tools/catalog-tiktok-account-search.md)
- [`solari_catalog_tiktok_account_profile`](https://finder-dev-pub.bzine.co/docs/tools/catalog-tiktok-account-profile.md)
- [`solari_fetch_tiktok_posts`](https://finder-dev-pub.bzine.co/docs/tools/fetch-tiktok-posts.md)

### solari fetch tiktok posts

> Collect one TikTok account's posts into the catalog.

- **CLI**: `solari fetch tiktok posts`
- **MCP tool**: `solari_fetch_tiktok_posts`
- **Access**: `solari:read` — Works with any signed-in SOLARI account.
- **Required plan**: Free
- **Credit**: 0

Collect posts for one TikTok account into the SOLARI catalog by exact username. This is not a post listing. If the handle is already stored, nothing is scraped.

**When to use it** — When catalog posts does not know an exact handle you already have.

**What comes back** — Whether it was ingested, how many posts came back, and the catalog command to read them.

#### Parameters

- `username` (string, required, ≤ 64 chars) — TikTok username.

#### Response

##### `Response`

- `ingested` (boolean) — true if this call collected it live.
- `already_tracked` (boolean) — true if it was already in the catalog.
- `fetched_on_demand` (boolean) — Same as ingested.
- `found` (boolean) — false if the handle could not be collected.
- `account_id` (uuid) — The ingested account.
- `username` (string) — Resolved handle.
- `total` (integer) — Posts available so far.
- `note` (string) — What to expect next.
- `next` (string) — Catalog command to read the result.

#### Example

```console
$ solari fetch tiktok posts username=innisfree_official
```

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

```json
{
  "ingested": false,
  "already_tracked": true,
  "fetched_on_demand": false,
  "found": true,
  "account_id": "01a0631e-f0df-7e9d-a09b-d84bc31d3834",
  "username": "innisfree_official",
  "total": 12,
  "note": "Already in the SOLARI catalog. Nothing was scraped.",
  "next": "solari catalog tiktok account posts username=innisfree_official"
}
```

#### As an MCP call

```json
{
  "name": "solari_fetch_tiktok_posts",
  "arguments": {
    "username": "innisfree_official"
  }
}
```

#### Notes

- Do not use this to list stored posts. Use catalog tiktok account posts for that.
- A first-time ingest can take 10 to 40 seconds. Only recent posts exist until the crawl finishes.

#### Related tools

- [`solari_fetch_tiktok_account`](https://finder-dev-pub.bzine.co/docs/tools/fetch-tiktok-account.md)
- [`solari_catalog_tiktok_account_posts`](https://finder-dev-pub.bzine.co/docs/tools/catalog-tiktok-account-posts.md)
- [`solari_catalog_tiktok_account_search`](https://finder-dev-pub.bzine.co/docs/tools/catalog-tiktok-account-search.md)