v1.0.0 to v1.0.0

- description: "Instagram public data: profiles with follower counts and bio, timeline posts, reels, tagged posts, active stories, single-post detail, comments and replies, follower and following lists, and user and hashtag search. 12 endpoints, 2-10 credits each; responses keep Instagram's own structure, not a normalized shape."

- tags: instagram, instagram-api, instagram-scraper, social-media, profiles, reels, stories, followers, comments, hashtags, influencer-marketing, social-listening, langchain, crewai, autogen, ai-agents, structured-data, json

- Read public Instagram data as JSON: profiles, timeline posts, reels, tagged posts, active stories, single-post detail, comment threads, follower and following lists, and user/hashtag search.

- - Look up an Instagram profile: follower count, bio, verified status, account type

- - Mine the comments on a post, or the replies under one comment

- - List who follows an account, or who it follows

- - Find accounts or hashtags by keyword

- **1. Instagram is the most expensive family in the API. Budget before you loop.** Costs are per-endpoint and range 2 to 10 credits, unlike Google or Reddit where everything is 1. A profile lookup is **10 credits** — ten times a Google search. On the free plan's 50 one-time credits that is five calls. The full table is below; read it before writing any loop. The cheap endpoint is `/user/posts` at **2 credits** — prefer it, and reach for the 10-credit endpoints only when you genuinely need what they carry.

- **2. There is no single post identifier that works everywhere.** The three post endpoints take three different, non-overlapping identity sets:

- So you cannot chain `/post/comments` straight into `/post/comments/replies` — comments are addressed by shortcode, replies by `media_id`. To get replies, call `/instagram/post` first to resolve the `media_id`, then pass it with the `comment_id` from the comments call. That chain costs 8 + 10 + 8 = 26 credits; make sure the user actually wants it.

- **3. The response keeps Instagram's own structure, not a normalized Scavio shape.** Unlike Reddit, YouTube or LinkedIn, Instagram responses keep Instagram's field names. Two consequences:

- - **Field names are Instagram's, not friendly ones.** On a post, the video URL is at `video_versions[].url` — there is **no** `video_url`. The cover image is at `image_versions2.candidates[]` — there is **no** `thumbnail_url`. `media_type` is the integer `1` (image), `2` (video), or `8` (carousel).

- - **The top-level keys inside `data` can vary between calls on the same endpoint**, because the same endpoint can answer in two different structures. Always probe defensively: check for `items` and for `data`, take whichever is present, and never assume a key exists.

- 3. A new account starts with 50 credits. Endpoints in this skill cost 1 credit each unless the table below says otherwise.

- Base URL: `https://api.scavio.dev`. All paths are under `/api/v1/instagram`.

- | `POST /api/v1/instagram/user/posts` | **2** | Timeline posts for a user. The cheap one -- start here |

- | `POST /api/v1/instagram/post` | **8** | Full detail for one post |

- | `POST /api/v1/instagram/post/comments/replies` | **8** | Replies under one comment |

- | `POST /api/v1/instagram/profile` | **10** | Profile: bio, counts, verified, account type |

- | `POST /api/v1/instagram/user/reels` | **10** | A user's reels |

- | `POST /api/v1/instagram/user/tagged` | **10** | Posts a user was tagged in |

- | `POST /api/v1/instagram/user/stories` | **10** | Currently active stories |

- | `POST /api/v1/instagram/post/comments` | **10** | Top-level comments on a post |

- | `POST /api/v1/instagram/user/followers` | **10** | Who follows this account |

- | `POST /api/v1/instagram/user/followings` | **10** | Who this account follows |

- | `POST /api/v1/instagram/search/users` | **10** | Find accounts by keyword |

- | `POST /api/v1/instagram/search/hashtags` | **10** | Find hashtags by keyword |

-

- The 8-vs-10 split reflects what each lookup costs to serve reliably. Nothing here is 1 credit.

- 2. **Prefer `user_id` once you have it.** Every response that includes a profile carries `pk` / `id` — that is the `user_id`. When both are sent, `user_id` wins and is more stable than a username, which can be changed by its owner.

- 3. **Cheapest useful path:** `/user/posts` (2 credits) already carries captions, media, like and comment counts for recent posts. For "what is this creator posting about", that single call is often the whole answer.

- 4. **Add `/profile` (10) only when you need follower counts**, bio text, verified status, or account type. Do not call it reflexively before a feed call.

- 5. **Paginate with `cursor`.** Pass the continuation token from the previous response back as `cursor`. Names of the continuation field vary by endpoint and by which structure came back -- look for `next_max_id`, `pagination_token`, `next_min_id`, or `rank_token` and pass whichever is present. Stop when none is present or `has_more` / `more_available` is false.

- 6. **Raise `count` instead of making more calls.** Each call costs the same regardless of page size, so a single `count: 50` is five times cheaper than five `count: 10` calls.

- ### Profile (`/profile`), Stories (`/user/stories`)

- No `count`, no `cursor`. Stories are not paginated -- you get whatever is currently live, and an account with no active stories returns an empty set, which is a normal result and not an error.

- `/profile` returns the profile object **inlined at the root of `data`** -- there is no `data.user` wrapper. Read `data.follower_count`, not `data.user.follower_count`.

- | `count` | number | `12` | Items per page, 1-50 |

- Note on `/user/posts`: `count` is often not honored. Treat `count` as a request, not a guarantee, and read how many items you actually got rather than assuming.

-

- Also on `/user/posts`: when you pass **only** `user_id`, the items may arrive **double-nested at `data.data`** rather than `data.items`. Probe both.

- | `count` | number | `12` | Users per page, 1-**100** (the highest cap in the family) |

- | `cursor` | string | -- | Continuation token |

- The path is `followings`, plural. Follower lists on large accounts are effectively bottomless -- Instagram will not hand over millions of rows, and each page is 10 credits. Set an explicit page budget with the user before starting, and stop when the continuation token stops coming back.

- One of the three is required. `media_id` wins over everything; `shortcode` is expanded into a URL internally.

-

- The post is at `data.items[0]`. Within it: `media_type` `1`/`2`/`8`, video at `video_versions[].url`, cover at `image_versions2.candidates[]`. For a carousel (`media_type: 8`) the children are nested inside the item -- walk them rather than expecting one media URL.

- | `cursor` | string | -- | Continuation token |

- One of `shortcode` / `url` is required. **`media_id` is not accepted here** even though the sibling endpoints take it.

- Two cautions. First, `sort_order` is not always honored; when it is not, your sort is silently ignored. Do not present comment ordering to the user as guaranteed. Second, **pass a canonical post URL or a bare shortcode only.** A `/share/` link, a profile URL, or any URL that is not of the form `instagram.com/p/<code>`, `/reel/<code>`, `/reels/<code>` or `/tv/<code>` currently fails as a **500**, not a clean 400. Extract the shortcode yourself and send that instead.

- | `media_id` | string | required | The post's numeric media id, as a string |

- | `comment_id` | string | required | From a comment in the `/post/comments` response |

- Both ids are required. `/post/comments` does not return `media_id`, so resolve it with `/instagram/post` first. See caution 2 at the top.

- | `cursor` | string | -- | Rank token from a previous response |

- The field is `keyword`, not `query` or `search`. There is **no `count`** -- page size is not controllable. Pagination is best-effort: sometimes the cursor is ignored and you get page 1 again. Detect this by comparing the returned ids to what you already have rather than assuming forward progress.

- | 502 | Upstream Instagram data temporarily unavailable | Retry once after a short delay, then give up |

- Before any multi-call workflow, state the credit cost to the user. "Scanning this account's 500 followers is 10 credits per page of up to 100, so about 50 credits" is the kind of thing to say **before** starting, not after.

- # 1. Recent posts for a creator -- 2 credits, usually enough on its own

- curl -X POST 'https://api.scavio.dev/api/v1/instagram/user/posts' \

- -d '{"username": "instagram", "count": 24}'

- # 2. Follower count and bio -- 10 credits, only when actually needed

- curl -X POST 'https://api.scavio.dev/api/v1/instagram/profile' \

- -d '{"username": "instagram"}'

- # 3. One post in full -- 8 credits

- curl -X POST 'https://api.scavio.dev/api/v1/instagram/post' \

- -d '{"shortcode": "DUajw4YkorV"}'