# Social Fetch API - Instagram endpoints
# Base URL: https://api.socialfetch.dev
# Auth: x-api-key header (sfk_...)
# Full catalog: https://www.socialfetch.dev/llms-endpoints.txt | JSON: https://www.socialfetch.dev/llms.json
# Docs hub: https://www.socialfetch.dev/docs/api | OpenAPI: https://www.socialfetch.dev/openapi.json

16 documented Instagram operations. Do not invent paths - only the routes below (and their linked markdown pages) are supported.

## GET /v1/instagram/profiles/{handle}
Get Instagram profile
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/instagram/profiles/handle/get.mdx
SDK: client.instagram.getProfile({ handle })
Parameters:
- handle (required, string) - Instagram handle to look up, with or without a leading @.
Outcome field: `data.lookupStatus` in `found`, `private`, `not_found`
curl "https://api.socialfetch.dev/v1/instagram/profiles/charlidamelio" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/instagram/profiles/{userId}/basic
Get Instagram basic profile
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/instagram/profiles/userid/basic/get.mdx
SDK: client.instagram.getBasicProfile({ userId })
Parameters:
- userId (required, string) - Instagram numeric user id to look up.
Outcome field: `data.lookupStatus` in `found`, `private`, `not_found`
curl "https://api.socialfetch.dev/v1/instagram/profiles/258288542/basic" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/instagram/profiles/{handle}/posts
List Instagram profile posts
Credit cost: 1 credit base. With `hostMedia`, +2 credits per hosted asset (up to 24 assets, 49 credits max).
Docs: https://www.socialfetch.dev/docs/api/v1/instagram/profiles/handle/posts/get.mdx
SDK: client.instagram.getProfilePosts({ handle, cursor? })
Parameters:
- handle (required, string) - Instagram handle whose posts should be listed.
- cursor (optional, string) - Opaque pagination cursor from a previous response.
- hostMedia (optional, boolean) - When true, hosts source media for 90 days and returns delivery URLs in each post's `hostedMedia`.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `private`, `not_found`
curl "https://api.socialfetch.dev/v1/instagram/profiles/charlidamelio/posts" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/instagram/profiles/{handle}/reels
List Instagram profile reels
Credit cost: 1 credit base. With `hostMedia`, +2 credits per hosted asset (up to 24 assets, 49 credits max).
Docs: https://www.socialfetch.dev/docs/api/v1/instagram/profiles/handle/reels/get.mdx
SDK: client.instagram.getProfileReels({ handle, cursor? })
Parameters:
- handle (required, string) - Instagram handle whose reels should be listed.
- cursor (optional, string) - Opaque pagination cursor from a previous response.
- hostMedia (optional, boolean) - When true, hosts source media for 90 days and returns delivery URLs in each reel's `hostedMedia`.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/instagram/profiles/charlidamelio/reels" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/instagram/profiles/{handle}/highlights
List Instagram profile highlights
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/instagram/profiles/handle/highlights/get.mdx
SDK: client.instagram.getProfileHighlights({ handle })
Parameters:
- handle (required, string) - Instagram handle whose story highlight albums should be listed.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/instagram/profiles/mrbeast/highlights" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/instagram/highlights/{highlightId}
Get Instagram highlight
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/instagram/highlights/highlightid/get.mdx
SDK: client.instagram.getHighlight({ highlightId })
Parameters:
- highlightId (required, string) - Numeric Instagram highlight id from a highlight URL.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/instagram/highlights/17929440964811872" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/instagram/profiles/{handle}/engagement
Get Instagram profile engagement audit
Credit cost: 5 credits per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/instagram/profiles/handle/engagement/get.mdx
Parameters:
- handle (required, string) - Instagram handle to look up, with or without a leading @.
Outcome field: `data.lookupStatus` in `found`, `private`, `not_found`
curl "https://api.socialfetch.dev/v1/instagram/profiles/charlidamelio/engagement" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/instagram/search/profiles
Search Instagram profiles
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/instagram/search/profiles/get.mdx
SDK: client.instagram.searchProfiles({ query: "fitness coach" })
Parameters:
- query (required, string) - Search query text for Instagram profiles.
- cursor (optional, string) - Opaque pagination cursor returned by a previous response.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
curl "https://api.socialfetch.dev/v1/instagram/search/profiles?query=fitness coach" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/instagram/search/reels
Search Instagram Reels
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/instagram/search/reels/get.mdx
SDK: client.instagram.searchReels({ query: "dogs" })
Parameters:
- query (required, string) - Search query text for Instagram Reels.
- datePosted (optional, string, enum: last-hour | last-day | last-week | last-month | last-year) - Optional filter for when matching reels were posted.
- page (optional, integer) - 1-based results page number. Omit to request the first page. Pagination is page-based.
Pagination: send query `page` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
curl "https://api.socialfetch.dev/v1/instagram/search/reels?query=dogs" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/instagram/search/hashtags
Search Instagram by hashtag
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/instagram/search/hashtags/get.mdx
SDK: client.instagram.searchHashtags({ hashtag: "makeup" })
Parameters:
- hashtag (required, string) - Hashtag to search for. A leading # is optional.
- datePosted (optional, string, enum: last-hour | last-day | last-week | last-month | last-year) - Optional filter for when matching posts were posted.
- mediaType (optional, string, enum: all | reels) - Content filter. Use `all` for posts and Reels, or `reels` for Reels only. Default: `all`.
- cursor (optional, string) - Pagination cursor returned by a previous response.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
curl "https://api.socialfetch.dev/v1/instagram/search/hashtags?hashtag=makeup" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/instagram/posts
Get Instagram post or reel
Credit cost: 1 credit base. With `downloadMedia`, Hosted media download. Up to 11 credits max.
Docs: https://www.socialfetch.dev/docs/api/v1/instagram/posts/get.mdx
SDK: client.instagram.getPost({ url })
Parameters:
- url (required, string) - Link to the post or reel.
- region (optional, string) - Optional ISO 3166-1 country code for request routing.
- trim (optional, boolean) - When true, returns a smaller response with fewer fields.
- downloadMedia (optional, boolean) - When true, asks the upstream provider to download media and return provider-hosted URLs in `downloads` (not SocialFetch-owned storage). Adds 10 credits when media is found (11 total including the base lookup); when no media is returned the base lookup credit still applies.
Outcome field: `data.lookupStatus` in `found`, `not_found`, `restricted`
curl "https://api.socialfetch.dev/v1/instagram/posts?url=https://www.instagram.com/p/DIdOKNpx66J" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/instagram/posts/comments
List Instagram post or reel comments
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/instagram/posts/comments/get.mdx
SDK: client.instagram.getPostComments({ url })
Parameters:
- url (required, string) - Link to the Instagram post or reel whose comments should be listed.
- cursor (optional, string) - Opaque cursor from a previous response to fetch the next page.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
Disambiguation: Lists top-level comments only. When a comment has replies (`data.comments[].replyCount` > 0), use List Instagram comment replies with that comment's `id` as `commentId` plus the same post or reel `url`.
curl "https://api.socialfetch.dev/v1/instagram/posts/comments?url=https://www.instagram.com/p/DIdOKNpx66J" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/instagram/posts/comments/replies
List Instagram comment replies
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/instagram/posts/comments/replies/get.mdx
SDK: client.instagram.getPostCommentReplies({ commentId, url })
Parameters:
- commentId (required, string) - Parent comment id from List Instagram post or reel comments (`data.comments[].id`).
- url (required, string) - Link to the Instagram post or reel that contains the parent comment.
- cursor (optional, string) - Opaque cursor from a previous response to fetch the next page.
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
Disambiguation: Requires parent `commentId` from List Instagram post or reel comments plus the same post or reel `url`. Paginate with `data.page.hasMore` and `data.page.nextCursor`; do not assume a fixed page size.
curl "https://api.socialfetch.dev/v1/instagram/posts/comments/replies?commentId=18038110327814211&url=https://www.instagram.com/p/DIdOKNpx66J" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/instagram/posts/download
Download Instagram post or reel media
Credit cost: 11 credits per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/instagram/posts/download/get.mdx
Parameters:
- url (required, string) - Link to the post or reel.
- region (optional, string) - Optional ISO 3166-1 country code for request routing.
Outcome field: `data.lookupStatus` in `found`, `not_found`, `restricted`
curl "https://api.socialfetch.dev/v1/instagram/posts/download?url=https://www.instagram.com/p/DIdOKNpx66J" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/instagram/posts/transcript
Get Instagram post transcript
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/instagram/posts/transcript/get.mdx
SDK: client.instagram.getPostTranscript({ url })
Parameters:
- url (required, string) - Link to the Instagram post or Reel whose transcript should be returned.
Outcome field: `data.lookupStatus` in `found`, `not_found`
curl "https://api.socialfetch.dev/v1/instagram/posts/transcript?url=https://www.instagram.com/p/DIdOKNpx66J" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/instagram/reels/trending
List trending Instagram Reels
Credit cost: 1 credit per successful request.
Docs: https://www.socialfetch.dev/docs/api/v1/instagram/reels/trending/get.mdx
SDK: client.instagram.getTrendingReels()
curl "https://api.socialfetch.dev/v1/instagram/reels/trending" \
  -H "x-api-key: YOUR_API_KEY"