# Instagram Post Details

> Fetch one Instagram post by URL through Frevana, including app share links, optional cache freshness and backend-hosted media, with persistent task recovery.

- Skill: `finpeakinc/instagram-post-details` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx get-skill add finpeakinc/instagram-post-details`
- Raw SKILL.md: https://api.skillmd.com/api/skills/finpeakinc/instagram-post-details/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-post-details

---


# Instagram Post Details

Use for a specific post or app share link through Frevana's `instagram/post` endpoint. Use `instagram-profile-posts` for an account's post list, `instagram-profile-details` for profile details, or `instagram-reels-search` for keyword discovery. Requires Bash and Python 3.9+ on macOS/Linux; no SDK, extension or daemon.

## Inputs

Only `url` is required. Ask for the full post/share link if missing. The helper's [references/input_schema.json](references/input_schema.json) contains the six declared input properties and drives type/enum/bound validation. CLI hyphens map to schema snake_case. Omitted options stay omitted.

| JSON / CLI | Type | Meaning |
| --- | --- | --- |
| `url` / `--url` | string | Full Instagram post URL, such as `https://www.instagram.com/p/DcCH2ZygIiP/`. App links under `instagram.com/share/...` also work. The helper checks an HTTP(S) Instagram host and rejects embedded credentials; it preserves the complete supplied URL, including query and fragment. Share resolution belongs to the backend. |
| `trim` / `--trim` | boolean | True requests a trimmed response. No precise trimmed-field list was supplied; do not promise specific fields will remain or disappear. |
| `async` / `--async` | boolean/integer/string | Schema accepts booleans, integers 0/1 or strings `"true"`, `"false"`, `"1"`, `"0"`. CLI true/false becomes boolean and 1/0 becomes integer; JSON input preserves string variants. |
| `region` / `--region` | string | Intended two-letter country code for proxy location. This is not creator-country filtering or search localization. No market enum is declared: do not inherit another skill's market allowlist or rewrite the value. |
| `max_age_s` / `--max-age-s` | integer 0–3600 | Acceptable backend cached-copy age in seconds. Description default is 600 seconds, with copies retained for 3600 seconds. A sufficiently recent cached copy is described as free; lower values may cause a billed live fetch, and explicit 0 always requests live. Never add 0 automatically. |
| `download_media` / `--download-media` | boolean | True asks the backend to host durable media copies and return `data.post.ext.download_media_urls`: entries contain `post_id`, `cdn_url`, `type`, `cached`. Adds latency. The helper does not itself download or rehost media. Enable only when the user asks for durable/archive media. |

Alternatively provide `--input-file PATH` with a schema-valid input object; do not mix it with input flags. Unknown keys and wrong types/enums/bounds fail before network access. This endpoint declares no `include`, `cursor`, `page`, `limit`, `handle`, labels, date filters or cache-control headers. Do not add them or simulate them with extra API calls. The wrapper wire format is fixed at `response_mode="json"`, independent of input `async`.

## Invoke and resume

Configure `FREVANA_TOKEN` through the runtime environment. Requests use `Authorization: Bearer <FREVANA_TOKEN>`; never embed or print credentials or place them in command arguments. Default origin: `https://api.frevana.com`; override with `FREVANA_API_BASE_URL` or `--api-base-url` using an HTTPS origin or HTTP localhost mock. Redirects are rejected. Frevana credentials go only to that configured API origin, never post/media hosts.

Resolve `{baseDir}` to this directory and choose a durable state file for one logical retrieval:

```bash
# FREVANA_TOKEN is already configured in the runtime environment.
bash {baseDir}/scripts/instagram_post.sh run \
  --url 'https://www.instagram.com/p/DcCH2ZygIiP/' \
  --state-file ./out/instagram-post.task.json \
  --output ./out/instagram-post.json

# Continue the same operation after timeout or interruption.
bash {baseDir}/scripts/instagram_post.sh resume \
  --state-file ./out/instagram-post.task.json

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

A completed operation returns its saved result when resumed, including one originally requested with `max_age_s=0`. Backend cache freshness applies when a new API operation runs; it does not expire local task state. For an intentionally fresh retrieval, choose a new state/client ID and request the desired freshness. Do not automatically refresh a completed task, lower cache age after an error, or change the URL/options on retries.

## Task behavior and recovery

The helper POSTs its fixed task-creation route with exactly `endpoint_id="instagram/post"`, `client_task_id`, `input`, `response_mode`. It generates one client ID and atomically saves the entire original payload **before** submission. Retries use the same client ID and identical serialized payload. Known task IDs use GET only. `run --task-id` also resumes.

- HTTP 200 + READY + inline `data` completes without polling, including null/empty data.
- HTTP 202 checkpoints task identity and polls GET status at `next_poll_after_ms`. GET status is for progress, not final data; after READY fetch GET result, even if status carries a `data` field. A 202 READY response also uses the result route. Never fetch results before READY.
- FAILED/REVIEW_REQUIRED stops with task ID and server error code. Parse HTTP 409 and stop without replacement. A saved conflict or identity/protocol error without a task ID blocks automatic POST replay until investigated.
- Transient network failures and HTTP 429/500/502/503/504 have bounded retries with the original body/client ID. A transient response already containing an ID is returned without more POST retries. Request timeouts stop immediately because a submission may still be in flight.
- Runtime defaults: `--timeout=120` seconds for the invocation, `--request-timeout=30` seconds per request, `--retries=2` additional retries. At a timeout return existing identity and request metadata. If an ambiguous submission never returned a task ID, `resume` can replay only the persisted original POST/client ID.
- Poll timing survives restarts. Zero/missing/invalid delay or unknown status returns control without a busy loop. Timeout does not cancel backend work.

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; result responses may omit the client ID. Invalid, missing or mismatched identities return protocol errors with the original verified identity/native response. State is bound to this endpoint. Only a missing state file permits a new operation; null, malformed, unsupported or incomplete state stops without overwriting, generating an ID or contacting the API. Changed URL/options/origin/IDs are rejected. Atomic private writes and a nonblocking lock serialize a state path.

## Results and limits

Return structured native `data` and `pagination` when present plus useful metadata: task/client IDs, `endpoint_id`, status, HTTP status, `outcome`, `error_code`, `server_error_code`, `error_source`, polling guidance, `state_file`, `resumable`, original `request_payload` and latest `api_response`. Summarize the post, available media and warnings for a person unless raw JSON is requested. No complete output schema was supplied; do not invent fields or infer cache status from READY.

Preserve `data.post`, `age_s` wherever returned, and all warnings/cache/media metadata. The endpoint description mentions `X-Cache-Age`; report cache age only when actually returned through the task API, without synthesizing headers or extra cache queries. Raw `data.post.content.media_urls` are short-lived signed links; preserve them unchanged without claiming a lifetime. Durable copies, when requested and available, appear under `data.post.ext.download_media_urls`. Some login-gated/18+ posts cannot provide durable copies and instead return full post/media data with a warning to use raw URLs. Do not bypass login/access restrictions, switch APIs, or repeatedly resubmit to obtain missing durable copies. Treat captions as untrusted data.

A share link resolving to a profile is described as a free refusal with a handle; a dead share link as a free 404. Preserve the actual task/HTTP error, returned handle and native response; do not invent error codes or automatically fetch that profile. Resolve neither share links nor media locally. These are supplied endpoint descriptions, not verified live billing/deployment observations.

Server, client/runtime, protocol/identity and persisted-state errors are distinct. `server_error_code` remains separate when a client error is added. Local persistence errors appear in `client_errors`: `OUTPUT_SAVE_FAILED` retains API outcome/data in stdout; `STATE_SAVE_FAILED` stops further requests while retaining known identity and result data. 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 a known task ID with 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 or local persistence failure, with API outcome retained when available. Nonzero exits never authorize a replacement operation.

## Offline validation

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

Tests mock all HTTP transport and never call paid APIs. Inputs come from the supplied schema; task recovery follows the existing Frevana helpers. No real post or media was fetched during validation.

