Getting Started

1. Get your API key

Create an account and generate a FetchLayer API key from your dashboard. The same key works on every platform.

2. Read an account

Pass a handle with or without the @, or a profile URL. The bio links come back unwrapped to their real destinations, and the story highlights come back with them.

curl -X POST https://api.fetchlayer.dev/instagram/user-profile \
  -H "Authorization: Bearer ss-your-key" \
  -H "Content-Type: application/json" \
  -d '{"username":"@nasa"}'

3. List what they posted

Newest first, pinned posts first, each normally with its posting date, like and comment counts, and for a video its play count and length — plus captions, hashtags, mentions and every rendition.

curl -X POST https://api.fetchlayer.dev/instagram/user-posts \
  -H "Authorization: Bearer ss-your-key" \
  -H "Content-Type: application/json" \
  -d '{"username":"@nasa","limit":60}'

4. Read the reels, with play counts

Same shape as the posts listing. Every reel comes back with playCount, likeCount and commentCount, and most with their posting date, length and caption too.

curl -X POST https://api.fetchlayer.dev/instagram/user-reels \
  -H "Authorization: Bearer ss-your-key" \
  -H "Content-Type: application/json" \
  -d '{"username":"@nasa","limit":12}'

Read what they have up now

The stories an account has up right now, oldest first, each frame with its posting and expiry time, every rendition, any link the account attached and any post it re-shared.

curl -X POST https://api.fetchlayer.dev/instagram/user-stories \
  -H "Authorization: Bearer ss-your-key" \
  -H "Content-Type: application/json" \
  -d '{"username":"@nasa"}'

5. Open one post, and read its comments

By URL, by the short code from it, or by the post’s numeric id. A video or reel comes back with its current play count and its length in seconds; photos and carousels have no public view count. Add "include":["reposts","shares","saves"] to also get repostCount, shareCount and saveCount — reposts on any post, shares and saves on reels and videos. It adds about 1 to 2 seconds, and the same include works on /user-posts and /user-reels for a whole page at the same price — there it adds a few seconds per page, usually 2 to 8.

curl -X POST https://api.fetchlayer.dev/instagram/post-detail \
  -H "Authorization: Bearer ss-your-key" \
  -H "Content-Type: application/json" \
  -d '{"post":"https://www.instagram.com/p/DcOX3hWFiey/"}'

curl -X POST https://api.fetchlayer.dev/instagram/post-comments \
  -H "Authorization: Bearer ss-your-key" \
  -H "Content-Type: application/json" \
  -d '{"post":"DcOX3hWFiey"}'

6. Discovery, without search

Instagram does not make keyword search or hashtag feeds public. What it does publish is the reels it lists as popular and the terms it is promoting. /reels-feed returns popular reels from many accounts, varying between calls, each with its play count, caption, author and video; like counts, comment counts and dates come from /post-detail.

curl -X POST https://api.fetchlayer.dev/instagram/reels-feed \
  -H "Authorization: Bearer ss-your-key" \
  -H "Content-Type: application/json" \
  -d '{"limit":12}'

curl -X POST https://api.fetchlayer.dev/instagram/trending-searches \
  -H "Authorization: Bearer ss-your-key" \
  -H "Content-Type: application/json" \
  -d '{"limit":48}'

7. Assets that keep working

Instagram’s asset URLs are signed and expire, so every asset carries a downloadUrl pointing at GET /instagram/media, which re-fetches it on demand with Range support.

curl -L "https://api.fetchlayer.dev/instagram/media?url=<asset url>" \
  -H "Authorization: Bearer ss-your-key" \
  --output post.jpg

Resolving a pasted link

When someone hands you an Instagram URL and you do not know what it points at, /resolve-url tells you — post, reel, account, hashtag, place, story or explore — plus the short code, numeric id, handle, tag or place id it encodes. It reaches Instagram not at all, so it is free.

curl -X POST https://api.fetchlayer.dev/instagram/resolve-url \
  -H "Authorization: Bearer ss-your-key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.instagram.com/p/DcOX3hWFiey/"}'

A link naming something Instagram does not make public — a hashtag page, a place — is still identified, with a note saying it is not available. That is the cheapest way to find out. A share link (/share/…) does not say which post it points to, so it comes back as unknown with a note to open it and pass the link it lands on.

Errors and retries

A 400 names the field to fix; unrecognised fields are rejected rather than ignored. A 404 means there is no such account or post — {"error":"no account \"fetchlayerprobe9f3\" was found","status":404} — never a 503 dressed up as a failure. An account Instagram restricts, typically an age-restricted brand, is not a 404: it answers 200 with restricted: true and less detail. A 502 or 503 is worth retrying after a wait. Read notes on successful responses too: the comment ceiling, the counts Instagram does not make public and a private account all announce themselves there rather than as an error.

Error responses

Every error, on every route, is JSON in one shape: error (what went wrong, in words), status, code, retryable and requestId, which also comes as the X-Request-Id header. Branch on code and retryable rather than on the text; on a 5xx the text is generic. Quote requestId when reporting a problem.

{
  "error": "Missing required parameter: url",
  "status": 400,
  "missing": ["url"],
  "code": "invalid_input",
  "retryable": false,
  "requestId": "922874e3-c0d0-40d8-8866-d198af132420"
}

More codes may be added; treat one you do not recognise by its retryable flag. Over MCP, a tool error carries the same fields in structuredContent, and as a JSON text block beside the message.

Next steps

• Learn about authentication →
• Read the reels reference →
• See the comment ceiling in full →