| name | ig-agent |
| description | Fetches Instagram data (media list, Reel insights, account metrics) through the local `ig-agent` CLI and returns structured JSON. Use when the user asks about their own Instagram posts or Reels, performance metrics (reach, views, likes, saves, watch time), follower counts, ranking Reels by engagement, exporting IG data to CSV/JSON, or drafting content strategy based on their history. Only useful when the `ig-agent` binary is available on PATH. |
ig-agent
A read-only wrapper around Meta's Instagram API with Instagram Login (graph.instagram.com). Emits structured JSON for agent consumption. Stable exit codes for retry logic.
First step: check auth
Start any session with ig-agent auth status --pretty. The output is JSON:
{ "authenticated": true, "expires_in_days": 58, "accounts": [ ... ] }
- If
authenticated is false, stop and tell the user to run ig-agent auth login (browser OAuth) or ig-agent auth login --token <token> (headless). Do not try to complete the OAuth flow yourself — it requires a browser session.
- If the command itself errors with "not found" or similar, the CLI isn't installed. Tell the user:
npm install -g ig-agent.
Invocation contract
-
stdout is machine-readable JSON (compact by default, pretty with --pretty). Pipe it, jq it, parse it.
-
stderr carries human log output. Ignore for data extraction.
-
Exit codes are stable:
| Code | Meaning | How an agent should react |
|---|
| 0 | Success | Parse stdout |
| 1 | User error (bad flags) | Surface to user; don't retry |
| 2 | API error (non-retryable) | Surface; don't retry |
| 3 | Rate-limited | Sleep 30–120 s, retry; prefer cache |
| 4 | Auth expired / missing | Tell user to ig-agent auth login or auth refresh |
| 5 | Network error | Retry with exponential backoff |
Always check exit codes in shell ($?) before parsing stdout.
Most common commands
ig-agent media list --type REELS --limit 20 --json
ig-agent insights <media-id> --json
ig-agent account insights --period week --json
ig-agent sync
ig-agent export --format json --type REELS --limit 50
Global flags
Every subcommand accepts:
--json (default) / --pretty — output format--account <ig-user-id-or-username> — target a specific connected account when the user has multiple--config <path> — alternative config location (rarely needed; default is ~/.config/ig-agent/config.json)--quiet — suppress stderr logs
Cache-first discipline (rate-limit aware)
The Instagram API is capped at 200 req/hr per IG account (as wired in our token-bucket limiter; Meta's documented global budget is 4800 × impressions per 24 h). The CLI ships with a token-bucket limiter, but you still shouldn't burn quota. Rule:
- If the user asks for analysis over many posts, run
ig-agent sync once, then read from ig-agent export --format json or re-run insight commands against already-cached media ids. Cached data is authoritative for ranking/summary tasks.
- If the user asks "what happened in the last hour?", go live (
media list / insights) — the cache isn't fresh enough.
- On exit code 3 (rate-limited), fall back to the cache and tell the user.
Where to look next
- For the complete command reference (every flag, every return shape, every metric name), read COMMANDS.md.
- For worked agent workflows (rank Reels, weekly summary, content-direction brainstorm), read RECIPES.md.
What this skill is NOT for
- Publishing, DM-ing, or modifying anything. The CLI is read-only — no write endpoints exist, even when the user has opted into the
comments scope via --scope=comments. Don't attempt write operations.
- Scraping other accounts.
ig-agent only operates on accounts the user has connected via OAuth.
- Competitor research. The Instagram API doesn't expose competitor data.
If the user asks for any of these, tell them explicitly that ig-agent doesn't support it and stop.
