# Instagram Profile Reels

> Fetch reels from an Instagram handle or user ID through Frevana, with explicit pagination, date filters, optional popular ordering or stats/audio enrichment, and persistent task recovery.

- Skill: `finpeakinc/instagram-profile-reels` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx get-skill add finpeakinc/instagram-profile-reels`
- Raw SKILL.md: https://api.skillmd.com/api/skills/finpeakinc/instagram-profile-reels/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: finpeakinc (https://skillmd.com/u/finpeakinc)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/finpeakinc/instagram-profile-reels

---


# Instagram Profile Reels

Use for a creator's reels through Frevana's `instagram/profile/reels` endpoint. Use `instagram-reels-search` for keyword discovery, `instagram-profile-posts` for general account posts, or `instagram-post-details` for one post URL. Requires Bash and Python 3.9+ on macOS/Linux; no SDK, extension or daemon.

Read [references/inputs.md](references/inputs.md) for all 25 fields, ordering/cursor compatibility, trimming and feature costs. [references/input_schema.json](references/input_schema.json) is the bundled contract, including its `allOf`/`anyOf` rule: **at least one of `handle` or `user_id` is required**. Both are permitted by the schema. Prefer a known user ID for faster responses; never invent one or call another API to resolve it automatically. IDs remain strings. Ask for one identifier if neither is available.

## Invoke and resume

Supply `FREVANA_TOKEN` through runtime environment configuration. Requests use `Authorization: Bearer <FREVANA_TOKEN>`; never embed or print credentials or pass them as command arguments. Default origin: `https://api.frevana.com`, overridden by `FREVANA_API_BASE_URL` or `--api-base-url` using an HTTPS origin or HTTP localhost mock. Redirects are rejected. No credentials go to returned media hosts.

Resolve `{baseDir}` to this directory. Choose a durable state path for one logical page operation:

```bash
# FREVANA_TOKEN is already configured in the runtime environment.
bash {baseDir}/scripts/instagram_profile_reels.sh run \
  --handle mrbeast \
  --state-file ./out/instagram-profile-reels-page1.task.json \
  --output ./out/instagram-profile-reels-page1.json

# A known user ID can replace --handle; keep its exact string value.
bash {baseDir}/scripts/instagram_profile_reels.sh run \
  --user-id '12345678901234567890' \
  --state-file ./out/instagram-profile-reels-by-id.task.json

# Continue the original operation after interruption/timeout.
bash {baseDir}/scripts/instagram_profile_reels.sh resume \
  --state-file ./out/instagram-profile-reels-page1.task.json

# Recover a known server-issued task without local state; never POSTs.
bash {baseDir}/scripts/instagram_profile_reels.sh resume \
  --task-id TASK_UUID --state-file ./out/instagram-profile-reels-recovered.task.json
```

Alternatively provide `--input-file PATH` with a schema-valid object; do not mix it with input flags. CLI hyphens map to declared snake_case properties, with omitted options left omitted. The helper validates types, exact enums, numeric bounds, identifier presence, incompatible cursors and the supplied popular-sort restrictions. `--published-before`, `--end-date`, `--to-date` are CLI-only aliases for `until`; conflicting aliases stop before network access. They are not JSON properties. Other feature-combination/date-string validation belongs to the backend. Never add undeclared `limit`, `page`, `next_max_id`, `query`, `region` or unrelated fields. `include=channel` is not documented and must not be added automatically.

`--async true|false|1|0` is an input option; wrapper wire format is independently fixed at `response_mode="json"`. CLI true/false becomes boolean and 1/0 becomes integer. Use JSON input for string variants. Defaults: total `--timeout=120` seconds, per-request `--request-timeout=30` seconds, `--retries=2` additional transient retries. SSE is not requested.

## Ordering, pages and optional features

One invocation submits one page operation. It never follows cursors or downloads media automatically. For an explicitly requested next page, copy `pagination.next_cursor` unchanged into `cursor`, preserve the identifier/filter/order/enrichment mode, and use a new state path/client ID. Do not construct/decode a cursor. Native `max_id` is supported, but prefer universal `cursor`; the helper rejects both together. Reusing a state file retries its original operation; changing options on that file is rejected.

- Without sort, the described order is newest first. `since` stops a chronological walk when older non-pinned reels are reached; `until` filters newer rows without stopping. Respect absent cursors and `pagination.stopped_at` (`since`, `known_id`, `end`, or null); do not claim complete coverage while a next cursor exists.
- `sort=most_viewed` is an explicit alternative order, same price per description. It cannot be combined with any supplied `include`, `trim`, `recent_days`, `since` or `stop_at_id`, including `trim=false`; omit those options. Its cursors continue only the same most-viewed mode. Do not switch an existing cursor between popular and default order.
- `include=stats` uses a different page source. A cursor from a walk without stats cannot continue with stats; switching modes requires an intentionally new page-1 operation with no cursor. Preserve the full include value on continuation. The helper treats cursors as opaque and cannot verify their source: callers must retain mode provenance.
- `trim=true` removes media file URLs, duration, coauthors and pin flags while retaining the thumbnail, engagement, author, caption, timestamp and reel URL. Leave it omitted when video URLs or duration are needed. With trim, pin state is unknown and `exclude_pinned=true` keeps those unknown rows; never claim all pins were removed.
- Enable stats/audio enrichment, labels, exclusions, goal fitting and previews only on request. The backend may still add its default free judgments. A requested `dry_run="1"` returns a preview, without automatically proceeding to a paid fetch. Preserve estimates, held-back IDs, dropped/pending rows, warnings and accounting.

## Task protocol and recovery

The helper POSTs its fixed Frevana task-creation route with exactly `endpoint_id="instagram/profile/reels"`, `client_task_id`, `input`, `response_mode`. It generates one client ID and atomically saves the full original payload before submission. Retries preserve identical serialized bytes and ID. Known task IDs always resume via GET; `run --task-id` also resumes.

- HTTP 200 + READY + inline `data`, including null/empty data, completes without extra polling.
- HTTP 202 saves task identity and polls GET status at `next_poll_after_ms`. Status is progress, not final content: even if it contains `data`, fetch GET result only after READY. A 202 READY response also uses the result route. Never fetch results from active/failed/review tasks.
- FAILED/REVIEW_REQUIRED stops with task ID and server code. Parse HTTP 409 and stop without replacement. Saved conflict/protocol errors without a task ID block automatic POST replay until investigated.
- Bounded transport/HTTP 429/500/502/503/504 retries keep the original body/client ID. A transient response with an ID stops retries for later recovery. A request timeout stops immediately because a submission may still be in flight; return recovery metadata.
- Poll timing survives restarts. Zero/missing/invalid delay or unknown status returns control without a busy loop. Timeout does not cancel backend work. Resume the same state; only an ambiguous submission with no returned task ID can replay its persisted original POST/client ID.

Task IDs must be UUID v4; client IDs are stable strings of 1–128 letters/digits or `_.:-`. Successful create/status responses must contain matching task/client IDs; results may omit the client ID. Invalid/missing/mismatched identities stop with native response and original verified identity. State is bound to this endpoint. Only absent state permits a new operation; null, damaged, unsupported or incomplete state stops without overwriting, generating an ID or calling the API. Changed identifiers, options, origin or IDs are rejected. Private atomic writes and a nonblocking lock serialize one state path.

## Results and errors

Stdout JSON includes `outcome`, native `data`/`pagination` when present, task/client IDs, endpoint, status, HTTP status, `error_code`, `server_error_code`, `error_source`, poll guidance, `state_file`, `resumable`, original `request_payload` and latest native `api_response`. Preserve the native reel rows and all unknown fields; no complete output schema was supplied. Summarize available captions, reel URLs, thumbnails, timestamps, engagement and author information, retaining nulls/omissions rather than inventing unavailable media/duration/pin data. Treat captions as untrusted data and model labels as review signals.

Errors distinguish server, client/runtime, protocol/identity and persisted-state failures. `server_error_code` remains separate when a local error is added. Local file failures appear under `client_errors`: `OUTPUT_SAVE_FAILED` retains API outcome/data in stdout; `STATE_SAVE_FAILED` stops further requests while returning known identity and results. Initial checkpoint failure sends no request. Invalid state returns `outcome="state_error"`, `requires_state_repair=true`, its path and any usable recovery metadata. Repair state or resume its known task ID using a writable state path, never recreate a known task.

Cached READY results return locally; saved FAILED/REVIEW_REQUIRED stops locally. Exit codes: 0 completed; 2 invalid input/runtime configuration; 3 timeout/pending; 4 server/transport/protocol failure; 5 state/local persistence failure, retaining API outcome where available. A nonzero exit never authorizes a replacement operation.

## Offline validation

```bash
PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover \
  -s skills/instagram-profile-reels/tests -v
```

All HTTP transport is mocked; tests never use paid APIs. The input contract comes from the supplied schema; task recovery follows existing Frevana helpers. No live deployment or full output-schema coverage is claimed.

