instagram-scraper-api
Instagram public data: profiles with follower counts and bio, timeline posts, reels, tagged posts, stories and highlights, single-post detail, comments, replies and likers, follower, following and similar-account lists, and search across users, hashtags, Reels, music and location
#ai-agents
Install
npx skills add https://github.com/scavio-ai/skills/tree/main/skills/instagram-scraper-api
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install scavio-ai-skills@llmmart
git clone https://github.com/scavio-ai/skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole scavio-ai/skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Instagram Scraper API - Profiles, Posts, Reels, Stories, Followers
Read public Instagram data as JSON: profiles, timeline posts, reels, tagged posts, active stories and saved highlights, single-post detail, comment threads, post likers, follower, following and similar-account lists, and search across users, hashtags, Reels, music and locations.
When to trigger
Use this skill when the user asks to:
- Look up an Instagram profile: follower count, bio, verified status, category
- Pull a creator's recent posts, reels, or the posts they were tagged in
- Read a creator's active stories or the stories saved in their highlights
- Read a specific post: caption, media URLs, like and comment counts
- Mine the comments on a post, the replies under one comment, or who liked a post
- List who follows an account, who it follows, or which accounts are similar to it
- Find accounts, hashtags, Reels, audio tracks or places by keyword
- See which Reels use a given song or sound
- Do influencer vetting, competitor tracking, or creator-discovery research on Instagram
For TikTok creators use scavio-tiktok. For TikTok Shop products use scavio-tiktok-shop.
Three things to read before you call anything
1. Most calls cost 1 or 2 credits. Know which is which before you loop. /profile, /user/reels, /user/tagged and /music/posts typically cost 1 credit; every other endpoint typically costs 2. Three exceptions to plan around:
/user/reelsand/user/taggedcost 2 the first time a given username is looked up, then 1. Sendinguser_idinstead ofusernamekeeps them at 1./search/usersand/search/hashtagscost 8 when you send acursor. Page 1 is 2. Only ask for page 2 when page 1 genuinely was not enough.- Any request can cost more (never more than 10) when it needs extra work to answer.
credits_usedin every response is the exact charge, so read it rather than assuming the typical price.
On the free plan's 50 one-time credits that is about 50 profile lookups or 25 post-detail calls. The full table is below.
2. Post identifiers differ per endpoint. The post endpoints take different identity sets:
| Endpoint | Accepts | Does NOT accept |
|---|---|---|
/post |
url, media_id, or shortcode |
-- |
/post/comments |
shortcode or url |
media_id |
/post/likers |
shortcode or url |
media_id |
/post/comments/replies |
media_id + comment_id |
shortcode, url |
To get replies, take media_id and pk from a comment in the /post/comments response (every comment carries both) and pass them as media_id and comment_id. Comments then replies is 2 + 2 = 4 credits.
3. Responses keep Instagram's own field names, not a normalized Scavio shape. Unlike Reddit, YouTube or LinkedIn, Instagram responses keep Instagram's structure, and it differs per endpoint (the per-endpoint notes below say where the list lives). Consequences:
- Field names are Instagram's, not friendly ones. On
/post, the video URL is atvideo_versions[].urland the cover image atimage_versions2.candidates[].media_typeis the integer1(image),2(video), or8(carousel). - Each endpoint answers in one structure, but structures differ between endpoints:
/user/postslists items atdata.data.items,/user/reelsatdata.items,/post/commentsatdata.comments. Read the notes below rather than guessing.
Do not invent friendlier field names when reporting results, and do not claim a field is missing until you have checked the raw keys actually returned.
Setup
Get a free API key at scavio.dev (50 one-time credits to get started, no card required):
export SCAVIO_API_KEY=sk_live_your_key
If you do not have a key yet
An agent running this skill without SCAVIO_API_KEY set will get 401 on every
call below. The whole path from nothing to a working key is self-serve:
- Sign up at dashboard.scavio.dev - email or Google, no card required.
- A key is created for the account automatically at signup. It is on the dashboard under API Keys, ready to copy.
- A new account starts with 50 credits. Endpoints in this skill cost 1 or 2 credits each, as the table below says.
When the balance runs out the API answers 402 with a JSON body carrying
billing_url. Topping up needs no code change - the same key keeps working.
The smallest purchase is 2,500 credits for $25, and monthly plans work out
cheaper per credit if the usage is steady rather than one-off.
Every request is a POST with a JSON body and:
Authorization: Bearer $SCAVIO_API_KEY
Endpoints
Base URL: https://api.scavio.dev. All paths are under /api/v1/instagram. Credits are the typical cost per call (per page for paginated endpoints); credits_used in each response is the exact charge, never more than 10.
| Endpoint | Credits | Description |
|---|---|---|
POST /api/v1/instagram/profile |
1 | Profile: bio, follower/following/media counts, verified, category |
POST /api/v1/instagram/user/posts |
2 | Timeline posts for a user, about 12 per page |
POST /api/v1/instagram/user/reels |
1 (2 on a username's first lookup) | A user's reels |
POST /api/v1/instagram/user/tagged |
1 (2 on a username's first lookup) | Posts a user was tagged in |
POST /api/v1/instagram/user/stories |
2 | Currently active stories |
POST /api/v1/instagram/user/highlights |
2 | A user's story highlights: id, title, cover, item count |
POST /api/v1/instagram/highlight/stories |
2 | Every story saved in one highlight, with media URLs |
POST /api/v1/instagram/post |
2 | Full detail for one post |
POST /api/v1/instagram/post/comments |
2 | Top-level comments on a post |
POST /api/v1/instagram/post/comments/replies |
2 | Replies under one comment |
POST /api/v1/instagram/post/likers |
2 | Accounts that liked a post (up to about 1,000) and the total like count |
POST /api/v1/instagram/user/followers |
2 | Who follows this account |
POST /api/v1/instagram/user/followings |
2 | Who this account follows |
POST /api/v1/instagram/user/similar |
2 | Accounts similar to this one |
POST /api/v1/instagram/search/users |
2 (8 with a cursor) |
Find accounts by keyword |
POST /api/v1/instagram/search/hashtags |
2 (8 with a cursor) |
Find hashtags by keyword |
POST /api/v1/instagram/search/reels |
2 | Find Reels by keyword |
POST /api/v1/instagram/search/music |
2 | Find audio tracks by song or artist |
POST /api/v1/instagram/music/posts |
1 | Reels that use one audio track, plus its total reel count |
POST /api/v1/instagram/search/locations |
2 | Find places by name: id, address, coordinates |
Workflow
- Start from a username. Every user endpoint accepts
username(without the@). You do not need to resolve an id first, unlike TikTok. - Prefer
user_idonce you have it./profilereturns it asid(andpk). When both are sent,user_idwins and is more stable than a username, which can be changed by its owner. On/user/reelsand/user/taggedit also avoids the 2-credit first lookup. - Cheapest useful path for "what is this creator about":
/profile(1 credit) for counts and bio, then/user/reels(1) or/user/posts(2) for recent content with captions and engagement counts. - Paginate with
cursor. Pass the continuation token from the previous response back ascursor. Its name depends on the endpoint:pagination_token(user posts, Reels search),next_max_id(reels, tagged, followers, followings),next_min_id(comments),paging_info.max_id(music posts). Stop when none is present orhas_more/more_availableis false. - Do not rely on
count./user/postsreturns about 12 items per page whatevercountsays. Read how many items you actually got rather than assuming.
Parameters
Identity: username vs user_id
Nine endpoints take a user identity. Both fields are optional individually but at least one is required; omitting both is a 400. user_id takes precedence when both are sent. user_id is a string, even though it looks like a number.
Profile (/profile), stories (/user/stories), highlights (/user/highlights), similar accounts (/user/similar)
| Parameter | Type | Default | Description |
|---|---|---|---|
username |
string | -- | Instagram handle without @ |
user_id |
string | -- | Numeric id as a string. Wins over username |
No count, no cursor.
/profilereturns the profile inlined at the root ofdata:data.username,data.full_name,data.follower_count,data.following_count,data.media_count,data.biography,data.is_verified,data.is_private,data.category,data.external_url. There is nodata.userwrapper./user/storieslists live stories atdata.items(also grouped per user underdata.reels.<user_id>.items), each withtaken_at,expiring_at,media_type,thumbnail_urlandvideo_url. An account with no active stories returns an empty list, which is a normal result and not an error./user/highlightslists highlights atdata.data.items, each withid(for examplehighlight:18149897764550869),title,media_count,cover_mediaandcreated_at./user/similarlists accounts atdata.data.itemswithid,username,full_name,is_verified,is_private. It works for most creator accounts; some brand accounts return none, which is a normal empty result.
Highlight stories (/highlight/stories)
| Parameter | Type | Default | Description |
|---|---|---|---|
highlight_id |
string | required | An id from /user/highlights, with or without the highlight: prefix |
Stories are at data.data.items, each with taken_at, media_type, image_versions, and on video items video_url and video_versions. The highlight's own title is at data.data.additional_data.title.
User posts (/user/posts), reels (/user/reels), tagged (/user/tagged)
| Parameter | Type | Default | Description |
|---|---|---|---|
username |
string | -- | Handle without @ |
user_id |
string | -- | Wins over username |
count |
number | 12 |
Items per page, 1-50 (not honored on /user/posts) |
cursor |
string | -- | Continuation token from the previous response |
/user/posts: items atdata.data.items, next page token atdata.pagination_token. Each item carriescode,caption.text,like_count,comment_count,taken_at,media_type,image_versionsandthumbnail_url; video items addvideo_url,video_versionsandplay_count./user/reelsand/user/tagged: items atdata.items, next page token atdata.next_max_id. Each item is compact:code,shortcode,media_type,is_video,like_count,comment_count,view_count,taken_at,caption_text,thumbnail_url,video_url,owner.- On
/user/tagged,video_urlisnullon video items andowner.full_name/owner.is_verifiedarenull. To get a tagged video's URL, call/postwith itscode.
Followers (/user/followers), followings (/user/followings)
| Parameter | Type | Default | Description |
|---|---|---|---|
username |
string | -- | Handle without @ |
user_id |
string | -- | Wins over username |
count |
number | 12 |
Users per page, 1-100 |
cursor |
string | -- | Continuation token (next_max_id) |
Users are at data.users. The path is followings, plural. Follower lists on large accounts are effectively bottomless -- Instagram will not hand over millions of rows. Each page is 2 credits; set an explicit page budget with the user before starting, and stop when the continuation token stops coming back.
Post detail (/post)
| Parameter | Type | Default | Description |
|---|---|---|---|
url |
string | -- | Full post URL, e.g. https://www.instagram.com/p/DUajw4YkorV/ |
media_id |
string | -- | Numeric media id as a string. Highest precedence |
shortcode |
string | -- | The code from the URL, e.g. DUajw4YkorV |
One of the three is required. The post is at data.items[0]. Within it: media_type 1/2/8, caption.text, like_count, comment_count, play_count, user, usertags, video at video_versions[].url, cover at image_versions2.candidates[]. For a carousel (media_type: 8) the children are under carousel_media[] -- walk them rather than expecting one media URL.
Post comments (/post/comments)
| Parameter | Type | Default | Description |
|---|---|---|---|
shortcode |
string | -- | The code from the post URL |
url |
string | -- | Full post URL |
cursor |
string | -- | Continuation token (next_min_id) |
sort_order |
string | popular |
popular or newest |
One of shortcode / url is required. media_id is not accepted here. Comments are at data.comments, each with pk, text, user, comment_like_count, child_comment_count, created_at and media_id; data.comment_count and data.has_more_comments describe the thread.
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> fails. Extract the shortcode yourself and send that instead.
Comment replies (/post/comments/replies)
| Parameter | Type | Default | Description |
|---|---|---|---|
media_id |
string | required | The post's numeric media id (the media_id on any comment) |
comment_id |
string | required | The comment's pk from /post/comments |
cursor |
string | -- | Continuation token |
Replies are at data.child_comments; the comment they answer is at data.parent_comment.
Post likers (/post/likers)
| Parameter | Type | Default | Description |
|---|---|---|---|
shortcode |
string | -- | The code from the post URL |
url |
string | -- | Full post URL |
One of the two is required; no cursor. Accounts are at data.data.items (id, username, full_name, is_verified, is_private), up to about 1,000 per post. data.data.total is the post's total like count, data.data.count how many accounts came back.
Search users (/search/users), search hashtags (/search/hashtags)
| Parameter | Type | Default | Description |
|---|---|---|---|
keyword |
string | required | Search term, 1-500 chars |
cursor |
string | -- | Rank token from a previous response. Makes the call cost 8 |
The field is keyword, not query or search. There is no count. Users are at data.users (pk, username, full_name, is_verified); hashtags at data.hashtags (id, name, media_count).
Search Reels (/search/reels)
| Parameter | Type | Default | Description |
|---|---|---|---|
keyword |
string | required | Search term |
cursor |
string | -- | pagination_token from the previous response |
Reels are at data.data.items, each with code, caption.text, user, play_count, like_count, comment_count, taken_at and video_versions. Next page token at data.pagination_token; each page is 2 credits.
Search music (/search/music) and music posts (/music/posts)
| Endpoint | Parameter | Type | Description |
|---|---|---|---|
/search/music |
keyword |
string, required | Song title or artist |
/music/posts |
music_id |
string, required | The id of a track from /search/music (numeric) |
/music/posts |
cursor |
string | paging_info.max_id from the previous response |
/search/music lists tracks at data.data.items with id, title, display_artist, duration_in_ms and progressive_download_url. Pass the track's id (not audio_id) as music_id.
/music/posts lists the Reels using that track at data.items[].media (code, play_count, like_count, comment_count, video_versions), with the track's total reel count at data.media_count.clips_count and data.formatted_media_count. More pages while data.paging_info.more_available is true; 1 credit per page.
Search locations (/search/locations)
| Parameter | Type | Default | Description |
|---|---|---|---|
keyword |
string | required | Place name |
Places are at data.data.items with id, name, address, city, latitude and longitude.
Errors
| Status | Meaning | What to do |
|---|---|---|
| 400 | Invalid body. The details array names the offending field |
Fix and resend. Usually a missing identity field |
| 401 | Bad or missing API key | Check SCAVIO_API_KEY |
| 402 | Out of credits | Stop. Tell the user, do not retry |
| 429 | Too many requests in flight at once | Wait for one to finish, then retry. Not a cooldown |
| 500 | Unparseable post URL on /post/comments |
Send a bare shortcode instead |
| 502 | Instagram data temporarily unavailable | Retry once after a short delay, then give up |
A 402 or 429 means stop, not retry harder. Report the condition to the user rather than burning the remaining balance.
Credits and spend discipline
Every successful response carries credits_used and credits_remaining next to data. Read credits_remaining as you go. To check the balance without spending anything, call GET /api/v1/usage (0 credits, no body).
Concurrency is capped per plan -- 1 simultaneous request on free and pay-as-you-go, up to 50 on Growth. Exceeding it returns 429 immediately. Do not fan out parallel Instagram calls unless you know the plan allows it.
Before any multi-call workflow, state the credit cost to the user. "Scanning this account's 500 followers is 2 credits per page of up to 100, so about 10 credits" is the kind of thing to say before starting, not after.
Example
# 1. Follower count and bio -- 1 credit
curl -X POST 'https://api.scavio.dev/api/v1/instagram/profile' \
-H "Authorization: Bearer $SCAVIO_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"username": "nasa"}'
# 2. Recent reels for the same creator -- 1 credit
curl -X POST 'https://api.scavio.dev/api/v1/instagram/user/reels' \
-H "Authorization: Bearer $SCAVIO_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"username": "nasa"}'
# 3. Who liked one post, plus the total like count -- 2 credits
curl -X POST 'https://api.scavio.dev/api/v1/instagram/post/likers' \
-H "Authorization: Bearer $SCAVIO_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"shortcode": "DeJ28eTxo4s"}'
# 4. Which Reels use a song: find the track, then its Reels -- 2 + 1 credits
curl -X POST 'https://api.scavio.dev/api/v1/instagram/search/music' \
-H "Authorization: Bearer $SCAVIO_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"keyword": "espresso"}'
curl -X POST 'https://api.scavio.dev/api/v1/instagram/music/posts' \
-H "Authorization: Bearer $SCAVIO_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"music_id": "1747512212697470"}'
# 5. A creator's highlights, then the stories in one -- 2 + 2 credits
curl -X POST 'https://api.scavio.dev/api/v1/instagram/user/highlights' \
-H "Authorization: Bearer $SCAVIO_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"username": "natgeo"}'
curl -X POST 'https://api.scavio.dev/api/v1/instagram/highlight/stories' \
-H "Authorization: Bearer $SCAVIO_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"highlight_id": "highlight:18149897764550869"}'
Related skills
scavio-tiktok-- TikTok creator profiles, videos, comments, hashtagsscavio-tiktok-shop-- TikTok Shop products, prices, reviewsscavio-x-- X (Twitter) posts, users, timelines, trendsscavio-linkedin-- LinkedIn people, companies, jobs, postsscavio-youtube-- YouTube search, videos, channels, transcripts
Files (skills)
-
SKILL.md 20.5 KB
--- name: instagram-scraper-api description: "Instagram public data: profiles with follower counts and bio, timeline posts, reels, tagged posts, stories and highlights, single-post detail, comments, replies and likers, follower, following and similar-account lists, and search across users, hashtags, Reels, music and locations. 20 endpoints, typically 1-2 credits each; responses keep Instagram's own structure, not a normalized shape." version: 1.0.0 tags: instagram, instagram-api, instagram-scraper, social-media, profiles, reels, stories, followers, comments, hashtags, highlights, likers, influencer-marketing, social-listening, langchain, crewai, autogen, ai-agents, structured-data, json metadata: openclaw: requires: env: - SCAVIO_API_KEY primaryEnv: SCAVIO_API_KEY timeout: 120 throttle: 1 emoji: "\U0001F4F8" homepage: https://scavio.dev/docs/instagram-api?utm_source=agent-skills&utm_medium=skill&utm_campaign=instagram-scraper-api --- # Instagram Scraper API - Profiles, Posts, Reels, Stories, Followers Read public Instagram data as JSON: profiles, timeline posts, reels, tagged posts, active stories and saved highlights, single-post detail, comment threads, post likers, follower, following and similar-account lists, and search across users, hashtags, Reels, music and locations. ## When to trigger Use this skill when the user asks to: - Look up an Instagram profile: follower count, bio, verified status, category - Pull a creator's recent posts, reels, or the posts they were tagged in - Read a creator's active stories or the stories saved in their highlights - Read a specific post: caption, media URLs, like and comment counts - Mine the comments on a post, the replies under one comment, or who liked a post - List who follows an account, who it follows, or which accounts are similar to it - Find accounts, hashtags, Reels, audio tracks or places by keyword - See which Reels use a given song or sound - Do influencer vetting, competitor tracking, or creator-discovery research on Instagram For TikTok creators use `scavio-tiktok`. For TikTok Shop products use `scavio-tiktok-shop`. ## Three things to read before you call anything **1. Most calls cost 1 or 2 credits. Know which is which before you loop.** `/profile`, `/user/reels`, `/user/tagged` and `/music/posts` typically cost **1 credit**; every other endpoint typically costs **2**. Three exceptions to plan around: - `/user/reels` and `/user/tagged` cost 2 the first time a given username is looked up, then 1. Sending `user_id` instead of `username` keeps them at 1. - `/search/users` and `/search/hashtags` cost **8** when you send a `cursor`. Page 1 is 2. Only ask for page 2 when page 1 genuinely was not enough. - Any request can cost more (never more than **10**) when it needs extra work to answer. `credits_used` in every response is the exact charge, so read it rather than assuming the typical price. On the free plan's 50 one-time credits that is about 50 profile lookups or 25 post-detail calls. The full table is below. **2. Post identifiers differ per endpoint.** The post endpoints take different identity sets: | Endpoint | Accepts | Does NOT accept | |---|---|---| | `/post` | `url`, `media_id`, or `shortcode` | -- | | `/post/comments` | `shortcode` or `url` | `media_id` | | `/post/likers` | `shortcode` or `url` | `media_id` | | `/post/comments/replies` | `media_id` + `comment_id` | `shortcode`, `url` | To get replies, take `media_id` and `pk` from a comment in the `/post/comments` response (every comment carries both) and pass them as `media_id` and `comment_id`. Comments then replies is 2 + 2 = 4 credits. **3. Responses keep Instagram's own field names, not a normalized Scavio shape.** Unlike Reddit, YouTube or LinkedIn, Instagram responses keep Instagram's structure, and it differs per endpoint (the per-endpoint notes below say where the list lives). Consequences: - **Field names are Instagram's, not friendly ones.** On `/post`, the video URL is at `video_versions[].url` and the cover image at `image_versions2.candidates[]`. `media_type` is the integer `1` (image), `2` (video), or `8` (carousel). - **Each endpoint answers in one structure**, but structures differ between endpoints: `/user/posts` lists items at `data.data.items`, `/user/reels` at `data.items`, `/post/comments` at `data.comments`. Read the notes below rather than guessing. Do not invent friendlier field names when reporting results, and do not claim a field is missing until you have checked the raw keys actually returned. ## Setup Get a free API key at [scavio.dev](https://scavio.dev/?utm_source=agent-skills&utm_medium=skill&utm_campaign=instagram-scraper-api) (50 one-time credits to get started, no card required): ```bash export SCAVIO_API_KEY=sk_live_your_key ``` ### If you do not have a key yet An agent running this skill without `SCAVIO_API_KEY` set will get `401` on every call below. The whole path from nothing to a working key is self-serve: 1. Sign up at [dashboard.scavio.dev](https://dashboard.scavio.dev/sign-up?utm_source=agent-skills&utm_medium=skill&utm_campaign=instagram-scraper-api) - email or Google, no card required. 2. A key is created for the account automatically at signup. It is on the dashboard under API Keys, ready to copy. 3. A new account starts with 50 credits. Endpoints in this skill cost 1 or 2 credits each, as the table below says. When the balance runs out the API answers `402` with a JSON body carrying `billing_url`. Topping up needs no code change - the same key keeps working. The smallest purchase is 2,500 credits for $25, and monthly plans work out cheaper per credit if the usage is steady rather than one-off. Every request is a `POST` with a JSON body and: ``` Authorization: Bearer $SCAVIO_API_KEY ``` ## Endpoints Base URL: `https://api.scavio.dev`. All paths are under `/api/v1/instagram`. Credits are the typical cost per call (per page for paginated endpoints); `credits_used` in each response is the exact charge, never more than 10. | Endpoint | Credits | Description | |---|---|---| | `POST /api/v1/instagram/profile` | **1** | Profile: bio, follower/following/media counts, verified, category | | `POST /api/v1/instagram/user/posts` | **2** | Timeline posts for a user, about 12 per page | | `POST /api/v1/instagram/user/reels` | **1** (2 on a username's first lookup) | A user's reels | | `POST /api/v1/instagram/user/tagged` | **1** (2 on a username's first lookup) | Posts a user was tagged in | | `POST /api/v1/instagram/user/stories` | **2** | Currently active stories | | `POST /api/v1/instagram/user/highlights` | **2** | A user's story highlights: id, title, cover, item count | | `POST /api/v1/instagram/highlight/stories` | **2** | Every story saved in one highlight, with media URLs | | `POST /api/v1/instagram/post` | **2** | Full detail for one post | | `POST /api/v1/instagram/post/comments` | **2** | Top-level comments on a post | | `POST /api/v1/instagram/post/comments/replies` | **2** | Replies under one comment | | `POST /api/v1/instagram/post/likers` | **2** | Accounts that liked a post (up to about 1,000) and the total like count | | `POST /api/v1/instagram/user/followers` | **2** | Who follows this account | | `POST /api/v1/instagram/user/followings` | **2** | Who this account follows | | `POST /api/v1/instagram/user/similar` | **2** | Accounts similar to this one | | `POST /api/v1/instagram/search/users` | **2** (8 with a `cursor`) | Find accounts by keyword | | `POST /api/v1/instagram/search/hashtags` | **2** (8 with a `cursor`) | Find hashtags by keyword | | `POST /api/v1/instagram/search/reels` | **2** | Find Reels by keyword | | `POST /api/v1/instagram/search/music` | **2** | Find audio tracks by song or artist | | `POST /api/v1/instagram/music/posts` | **1** | Reels that use one audio track, plus its total reel count | | `POST /api/v1/instagram/search/locations` | **2** | Find places by name: id, address, coordinates | ## Workflow 1. **Start from a username.** Every user endpoint accepts `username` (without the `@`). You do not need to resolve an id first, unlike TikTok. 2. **Prefer `user_id` once you have it.** `/profile` returns it as `id` (and `pk`). When both are sent, `user_id` wins and is more stable than a username, which can be changed by its owner. On `/user/reels` and `/user/tagged` it also avoids the 2-credit first lookup. 3. **Cheapest useful path for "what is this creator about":** `/profile` (1 credit) for counts and bio, then `/user/reels` (1) or `/user/posts` (2) for recent content with captions and engagement counts. 4. **Paginate with `cursor`.** Pass the continuation token from the previous response back as `cursor`. Its name depends on the endpoint: `pagination_token` (user posts, Reels search), `next_max_id` (reels, tagged, followers, followings), `next_min_id` (comments), `paging_info.max_id` (music posts). Stop when none is present or `has_more` / `more_available` is false. 5. **Do not rely on `count`.** `/user/posts` returns about 12 items per page whatever `count` says. Read how many items you actually got rather than assuming. ## Parameters ### Identity: `username` vs `user_id` Nine endpoints take a user identity. Both fields are optional individually but **at least one is required**; omitting both is a 400. `user_id` takes precedence when both are sent. `user_id` is a **string**, even though it looks like a number. ### Profile (`/profile`), stories (`/user/stories`), highlights (`/user/highlights`), similar accounts (`/user/similar`) | Parameter | Type | Default | Description | |---|---|---|---| | `username` | string | -- | Instagram handle without `@` | | `user_id` | string | -- | Numeric id as a string. Wins over `username` | No `count`, no `cursor`. - `/profile` returns the profile **inlined at the root of `data`**: `data.username`, `data.full_name`, `data.follower_count`, `data.following_count`, `data.media_count`, `data.biography`, `data.is_verified`, `data.is_private`, `data.category`, `data.external_url`. There is no `data.user` wrapper. - `/user/stories` lists live stories at `data.items` (also grouped per user under `data.reels.<user_id>.items`), each with `taken_at`, `expiring_at`, `media_type`, `thumbnail_url` and `video_url`. An account with no active stories returns an empty list, which is a normal result and not an error. - `/user/highlights` lists highlights at `data.data.items`, each with `id` (for example `highlight:18149897764550869`), `title`, `media_count`, `cover_media` and `created_at`. - `/user/similar` lists accounts at `data.data.items` with `id`, `username`, `full_name`, `is_verified`, `is_private`. It works for most creator accounts; some brand accounts return none, which is a normal empty result. ### Highlight stories (`/highlight/stories`) | Parameter | Type | Default | Description | |---|---|---|---| | `highlight_id` | string | required | An `id` from `/user/highlights`, with or without the `highlight:` prefix | Stories are at `data.data.items`, each with `taken_at`, `media_type`, `image_versions`, and on video items `video_url` and `video_versions`. The highlight's own title is at `data.data.additional_data.title`. ### User posts (`/user/posts`), reels (`/user/reels`), tagged (`/user/tagged`) | Parameter | Type | Default | Description | |---|---|---|---| | `username` | string | -- | Handle without `@` | | `user_id` | string | -- | Wins over `username` | | `count` | number | `12` | Items per page, 1-50 (not honored on `/user/posts`) | | `cursor` | string | -- | Continuation token from the previous response | - `/user/posts`: items at `data.data.items`, next page token at `data.pagination_token`. Each item carries `code`, `caption.text`, `like_count`, `comment_count`, `taken_at`, `media_type`, `image_versions` and `thumbnail_url`; video items add `video_url`, `video_versions` and `play_count`. - `/user/reels` and `/user/tagged`: items at `data.items`, next page token at `data.next_max_id`. Each item is compact: `code`, `shortcode`, `media_type`, `is_video`, `like_count`, `comment_count`, `view_count`, `taken_at`, `caption_text`, `thumbnail_url`, `video_url`, `owner`. - On `/user/tagged`, `video_url` is `null` on video items and `owner.full_name` / `owner.is_verified` are `null`. To get a tagged video's URL, call `/post` with its `code`. ### Followers (`/user/followers`), followings (`/user/followings`) | Parameter | Type | Default | Description | |---|---|---|---| | `username` | string | -- | Handle without `@` | | `user_id` | string | -- | Wins over `username` | | `count` | number | `12` | Users per page, 1-100 | | `cursor` | string | -- | Continuation token (`next_max_id`) | Users are at `data.users`. The path is `followings`, plural. Follower lists on large accounts are effectively bottomless -- Instagram will not hand over millions of rows. Each page is 2 credits; set an explicit page budget with the user before starting, and stop when the continuation token stops coming back. ### Post detail (`/post`) | Parameter | Type | Default | Description | |---|---|---|---| | `url` | string | -- | Full post URL, e.g. `https://www.instagram.com/p/DUajw4YkorV/` | | `media_id` | string | -- | Numeric media id as a string. **Highest precedence** | | `shortcode` | string | -- | The code from the URL, e.g. `DUajw4YkorV` | One of the three is required. The post is at `data.items[0]`. Within it: `media_type` `1`/`2`/`8`, `caption.text`, `like_count`, `comment_count`, `play_count`, `user`, `usertags`, video at `video_versions[].url`, cover at `image_versions2.candidates[]`. For a carousel (`media_type: 8`) the children are under `carousel_media[]` -- walk them rather than expecting one media URL. ### Post comments (`/post/comments`) | Parameter | Type | Default | Description | |---|---|---|---| | `shortcode` | string | -- | The code from the post URL | | `url` | string | -- | Full post URL | | `cursor` | string | -- | Continuation token (`next_min_id`) | | `sort_order` | string | `popular` | `popular` or `newest` | One of `shortcode` / `url` is required. **`media_id` is not accepted here.** Comments are at `data.comments`, each with `pk`, `text`, `user`, `comment_like_count`, `child_comment_count`, `created_at` and `media_id`; `data.comment_count` and `data.has_more_comments` describe the thread. **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>` fails. Extract the shortcode yourself and send that instead. ### Comment replies (`/post/comments/replies`) | Parameter | Type | Default | Description | |---|---|---|---| | `media_id` | string | required | The post's numeric media id (the `media_id` on any comment) | | `comment_id` | string | required | The comment's `pk` from `/post/comments` | | `cursor` | string | -- | Continuation token | Replies are at `data.child_comments`; the comment they answer is at `data.parent_comment`. ### Post likers (`/post/likers`) | Parameter | Type | Default | Description | |---|---|---|---| | `shortcode` | string | -- | The code from the post URL | | `url` | string | -- | Full post URL | One of the two is required; no cursor. Accounts are at `data.data.items` (`id`, `username`, `full_name`, `is_verified`, `is_private`), up to about 1,000 per post. `data.data.total` is the post's total like count, `data.data.count` how many accounts came back. ### Search users (`/search/users`), search hashtags (`/search/hashtags`) | Parameter | Type | Default | Description | |---|---|---|---| | `keyword` | string | required | Search term, 1-500 chars | | `cursor` | string | -- | Rank token from a previous response. Makes the call cost 8 | The field is `keyword`, not `query` or `search`. There is **no `count`**. Users are at `data.users` (`pk`, `username`, `full_name`, `is_verified`); hashtags at `data.hashtags` (`id`, `name`, `media_count`). ### Search Reels (`/search/reels`) | Parameter | Type | Default | Description | |---|---|---|---| | `keyword` | string | required | Search term | | `cursor` | string | -- | `pagination_token` from the previous response | Reels are at `data.data.items`, each with `code`, `caption.text`, `user`, `play_count`, `like_count`, `comment_count`, `taken_at` and `video_versions`. Next page token at `data.pagination_token`; each page is 2 credits. ### Search music (`/search/music`) and music posts (`/music/posts`) | Endpoint | Parameter | Type | Description | |---|---|---|---| | `/search/music` | `keyword` | string, required | Song title or artist | | `/music/posts` | `music_id` | string, required | The `id` of a track from `/search/music` (numeric) | | `/music/posts` | `cursor` | string | `paging_info.max_id` from the previous response | `/search/music` lists tracks at `data.data.items` with `id`, `title`, `display_artist`, `duration_in_ms` and `progressive_download_url`. Pass the track's `id` (not `audio_id`) as `music_id`. `/music/posts` lists the Reels using that track at `data.items[].media` (`code`, `play_count`, `like_count`, `comment_count`, `video_versions`), with the track's total reel count at `data.media_count.clips_count` and `data.formatted_media_count`. More pages while `data.paging_info.more_available` is true; 1 credit per page. ### Search locations (`/search/locations`) | Parameter | Type | Default | Description | |---|---|---|---| | `keyword` | string | required | Place name | Places are at `data.data.items` with `id`, `name`, `address`, `city`, `latitude` and `longitude`. ## Errors | Status | Meaning | What to do | |---|---|---| | 400 | Invalid body. The `details` array names the offending field | Fix and resend. Usually a missing identity field | | 401 | Bad or missing API key | Check `SCAVIO_API_KEY` | | 402 | Out of credits | Stop. Tell the user, do not retry | | 429 | Too many requests in flight at once | Wait for one to finish, then retry. Not a cooldown | | 500 | Unparseable post URL on `/post/comments` | Send a bare shortcode instead | | 502 | Instagram data temporarily unavailable | Retry once after a short delay, then give up | A 402 or 429 means stop, not retry harder. Report the condition to the user rather than burning the remaining balance. ## Credits and spend discipline Every successful response carries `credits_used` and `credits_remaining` next to `data`. Read `credits_remaining` as you go. To check the balance without spending anything, call `GET /api/v1/usage` (0 credits, no body). Concurrency is capped per plan -- 1 simultaneous request on free and pay-as-you-go, up to 50 on Growth. Exceeding it returns 429 immediately. Do not fan out parallel Instagram calls unless you know the plan allows it. Before any multi-call workflow, state the credit cost to the user. "Scanning this account's 500 followers is 2 credits per page of up to 100, so about 10 credits" is the kind of thing to say **before** starting, not after. ## Example ```bash # 1. Follower count and bio -- 1 credit curl -X POST 'https://api.scavio.dev/api/v1/instagram/profile' \ -H "Authorization: Bearer $SCAVIO_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"username": "nasa"}' # 2. Recent reels for the same creator -- 1 credit curl -X POST 'https://api.scavio.dev/api/v1/instagram/user/reels' \ -H "Authorization: Bearer $SCAVIO_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"username": "nasa"}' # 3. Who liked one post, plus the total like count -- 2 credits curl -X POST 'https://api.scavio.dev/api/v1/instagram/post/likers' \ -H "Authorization: Bearer $SCAVIO_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"shortcode": "DeJ28eTxo4s"}' # 4. Which Reels use a song: find the track, then its Reels -- 2 + 1 credits curl -X POST 'https://api.scavio.dev/api/v1/instagram/search/music' \ -H "Authorization: Bearer $SCAVIO_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"keyword": "espresso"}' curl -X POST 'https://api.scavio.dev/api/v1/instagram/music/posts' \ -H "Authorization: Bearer $SCAVIO_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"music_id": "1747512212697470"}' # 5. A creator's highlights, then the stories in one -- 2 + 2 credits curl -X POST 'https://api.scavio.dev/api/v1/instagram/user/highlights' \ -H "Authorization: Bearer $SCAVIO_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"username": "natgeo"}' curl -X POST 'https://api.scavio.dev/api/v1/instagram/highlight/stories' \ -H "Authorization: Bearer $SCAVIO_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"highlight_id": "highlight:18149897764550869"}' ``` ## Related skills - `scavio-tiktok` -- TikTok creator profiles, videos, comments, hashtags - `scavio-tiktok-shop` -- TikTok Shop products, prices, reviews - `scavio-x` -- X (Twitter) posts, users, timelines, trends - `scavio-linkedin` -- LinkedIn people, companies, jobs, posts - `scavio-youtube` -- YouTube search, videos, channels, transcripts
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.