# 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

13 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 per successful request.
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 (`data.page.nextCursor`).
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`
Empty results: An empty `data.posts` array with `lookupStatus: found` means no posts on this page; use `lookupStatus` for `not_found` / `restricted` vs empty feed.
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 per successful request.
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 (`data.page.nextCursor`).
Pagination: send query `cursor` from prior `data.page.nextCursor`; stop when `data.page.hasMore` is false.
Outcome field: `data.lookupStatus` in `found`, `not_found`
Empty results: An empty `data.reels` array with `lookupStatus: found` means no reels on this page; use `lookupStatus` for `not_found` / `restricted` vs empty feed.
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`
Empty results: An empty `data.highlights` array with `lookupStatus: found` means no highlights on this page; use `lookupStatus` for `not_found` / `restricted` vs empty feed.
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/posts
Get Instagram post or reel
Credit cost: 1 credit base, +10 with `downloadMedia`. 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) - When true, returns a smaller response with fewer fields.
- downloadMedia (optional) - When true, returns permanent CDN URLs for media in `downloads`. Adds 10 credits (11 total including the base lookup).
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`
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/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/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.
Empty results: An empty profiles array means no matching public profiles were found for this query and page. Results are best-effort from publicly indexed Instagram pages and are not a complete native Instagram directory.
Disambiguation: Use `GET /v1/instagram/profiles/{handle}` when you already know the username. Use this endpoint to discover profiles by keyword.
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) - 1-based results page number. Omit to request the first page. Pagination is page-based.
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. Defaults to 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.
Empty results: An empty `data.posts` array means no matching public posts were returned for this page; results are best-effort and may be incomplete compared to Instagram's native hashtag feed.
Disambiguation: Use `data.page.hasMore` and `data.page.nextCursor` for pagination. Repeat the same hashtag and filters when requesting the next page. Prefer this endpoint for hashtag discovery; use Instagram Reels keyword search for free-text reel queries.
curl "https://api.socialfetch.dev/v1/instagram/search/hashtags?hashtag=makeup" \
  -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()
Disambiguation: Returns a small batch of trending Reels per call. Repeat the same request for another fresh batch (new and overlapping Reels are both possible). No cursor or page parameters.
curl "https://api.socialfetch.dev/v1/instagram/reels/trending" \
  -H "x-api-key: YOUR_API_KEY"