# SocialCrawl API — instagram endpoints
# Base URL: https://www.socialcrawl.dev
# Auth: x-api-key header
# Full docs: https://www.socialcrawl.dev/docs/instagram

## GET /v1/instagram/profile
Get Instagram user profile
Credit cost: 1 (standard)
Parameters:
- handle (required) — Instagram username without the @ symbol
- trim (optional, boolean) — Set to true to get a trimmed response
curl "https://www.socialcrawl.dev/v1/instagram/profile?handle=instagram" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/instagram/profile/posts
List Instagram user posts
Credit cost: 1 (standard)
Parameters:
- handle (required) — Instagram username without the @ symbol
- next_max_id (optional, string) — Cursor to get next page of results.
- trim (optional, boolean) — Set to true to get a trimmed response
curl "https://www.socialcrawl.dev/v1/instagram/profile/posts?handle=instagram" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/instagram/post
Get Instagram post details
Credit cost: 1 (standard)
Parameters:
- url (required) — Full URL of the Instagram post
- region (optional, string) — 2 letter country code to set the proxy in
- trim (optional, boolean) — Set to true to get a trimmed response
- download_media (optional, boolean) — Set to true to also download the video/images and get back permanent, durable media URLs under `data.post.ext.download_media_urls` (`[{ post_id, cdn_url, type, cached }]`). Use these for archiving — the raw `media_urls` are short-lived signed CDN links that expire. Adds a few seconds of latency while the media is fetched.
curl "https://www.socialcrawl.dev/v1/instagram/post?url=https://www.instagram.com/p/CwA1234abcd/" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/instagram/post/comments
List Instagram post comments
Credit cost: 5 (advanced)
Parameters:
- url (required) — URL of the Instagram post (a /p/, /reel/, /reels/, or /tv/ link).
- sort (optional, enum: top | recent) — Ordering: `top` (default) ranks by Instagram's popularity order (most-liked first); `recent` returns newest-first.
- cursor (optional, string) — Pagination cursor. Use the `next_cursor` from the previous response to fetch the next page.
- safe_url (optional, boolean) — When true, returns URL-safe profile picture links suitable for embedding.
curl "https://www.socialcrawl.dev/v1/instagram/post/comments?url=https://www.instagram.com/p/DXidPIVDU6M/" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/instagram/comment
Look up one Instagram comment by URL or id
Credit cost: 5 (override; tier advanced)
Parameters:
- comment_url (optional, string) — An Instagram comment permalink: `https://www.instagram.com/p/{shortcode}/c/{commentId}/` (or a reply permalink `.../c/{parent}/r/{reply}/`, best-effort). Mutually exclusive with `post_url`+`comment_id`.
- post_url (optional, string) — The post URL (a `/p/`, `/reel/`, `/reels/`, or `/tv/` link). Combine with `comment_id`, or with `author_username`/`text_contains` for a search.
- comment_id (optional, string) — The target comment's numeric id (`pk`). Requires `post_url`.
- author_username (optional, string) — Return up to `max` comments authored by this username (no comment id needed). Mutually exclusive with `text_contains` and any comment id.
- text_contains (optional, string) — Return up to `max` comments whose text contains this snippet (case-insensitive). Mutually exclusive with `author_username` and any comment id.
- deep_scan (optional, boolean) — Widen the scan budget for deeply-buried comments (raises the per-chain page ceiling and deadline). Bills 15 credits instead of 5.
- position_hint (optional, string) — Opaque token from a prior lookup's `lookup.position_hint`. Passing it back replays just the last-known sort chain first, making a re-check of an already-found comment cheap.
- max (optional, integer) — For `author_username`/`text_contains` search: max matches to return (1–20, default 5).
curl "https://www.socialcrawl.dev/v1/instagram/comment" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/instagram/basic-profile
Get Instagram basic profile
Credit cost: 1 (standard)
Parameters:
- userId (optional, string) — Instagram numeric user ID
curl "https://www.socialcrawl.dev/v1/instagram/basic-profile" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/instagram/profile/reels
List Instagram user reels
Credit cost: 1 (standard)
Parameters:
- user_id (optional, string) — Instagram user id. Use this for faster response times.
- handle (optional, string) — Instagram username without the @ symbol
- max_id (optional, string) — Max id to get more reels. Get 'max_id' from previous response.
- trim (optional, boolean) — Set to true for a trimmed down version of the response
- Constraint: one of user_id, handle (at least one required)
curl "https://www.socialcrawl.dev/v1/instagram/profile/reels" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/instagram/highlights
List Instagram story highlights
Credit cost: 1 (standard)
Parameters:
- user_id (optional, string) — Instagram user id. Use for faster response times.
- handle (optional, string) — Instagram username without the @ symbol
- Constraint: one of user_id, handle (at least one required)
curl "https://www.socialcrawl.dev/v1/instagram/highlights" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/instagram/highlight/detail
Get Instagram highlight detail
Credit cost: 1 (standard)
Parameters:
- id (optional, string) — Instagram highlight ID — the numeric id, with or without the `highlight:` prefix. Get it from `/v1/instagram/user/highlights`.
curl "https://www.socialcrawl.dev/v1/instagram/highlight/detail" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/instagram/search/reels
Search Instagram reels
Credit cost: 1 (standard)
Parameters:
- query (required) — Search keyword or phrase to find Instagram reels
- date_posted (optional, enum: last-hour | last-day | last-week | last-month | last-year) — Date posted
- page (optional, integer) — The page number to return.
curl "https://www.socialcrawl.dev/v1/instagram/search/reels?query=workout routine" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/instagram/media/transcript
Get Instagram media transcript
Credit cost: 10 (premium)
Parameters:
- url (required) — Full URL of the Instagram video or reel
curl "https://www.socialcrawl.dev/v1/instagram/media/transcript?url=https://www.instagram.com/reel/DHsD6HGqJhp/" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/instagram/user/embed
Get Instagram user embed HTML
Credit cost: 1 (standard)
Parameters:
- handle (required) — Instagram username without the @ symbol
curl "https://www.socialcrawl.dev/v1/instagram/user/embed?handle=instagram" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/instagram/audio/reels
List Instagram reels using an audio track
Credit cost: 1 (standard)
Parameters:
- audio_id (required) — Instagram audio ID — the numeric id from an instagram.com/reels/audio/{audio_id}/ URL
- cursor (optional, string) — Pagination cursor from the previous response
curl "https://www.socialcrawl.dev/v1/instagram/audio/reels?audio_id=1392969992841787" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/instagram/search/hashtag
Search Instagram posts by hashtag
Credit cost: 5 (advanced)
Parameters:
- hashtag (required) — The hashtag to search for. The leading # is optional.
- type (optional, enum: top | recent | clips) — Ranking of the returned posts: `top` (default), `recent`, or `clips` (reels only).
- cursor (optional, string) — Pagination cursor. Use the `next_cursor` from the previous response to fetch the next page.
- safe_url (optional, boolean) — When true, returns URL-safe media links suitable for embedding.
curl "https://www.socialcrawl.dev/v1/instagram/search/hashtag?hashtag=makeup" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/instagram/search/profiles
Search Instagram profiles by keyword
Credit cost: 1 (standard)
Parameters:
- query (required) — Bio or caption keyword/phrase to search for.
- cursor (optional, string) — The cursor returned by the previous response. In this version it is the next Google results page number.
curl "https://www.socialcrawl.dev/v1/instagram/search/profiles?query=yoga" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/instagram/reels/trending
Get trending Instagram reels
Credit cost: 5 (advanced)
curl "https://www.socialcrawl.dev/v1/instagram/reels/trending" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/instagram/followers
List Instagram followers
Credit cost: 5 (advanced)
Parameters:
- handle (optional, string) — Instagram username without the @ symbol.
- user_id (optional, string) — Instagram numeric user ID. Use this for faster responses.
- cursor (optional, string) — Pagination cursor. Use the `next_cursor` from the previous response to fetch the next page.
- Constraint: one of handle, user_id (at least one required)
curl "https://www.socialcrawl.dev/v1/instagram/followers" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/instagram/following
List Instagram following
Credit cost: 5 (advanced)
Parameters:
- handle (optional, string) — Instagram username without the @ symbol.
- user_id (optional, string) — Instagram numeric user ID. Use this for faster responses.
- cursor (optional, string) — Pagination cursor. Use the `next_cursor` from the previous response to fetch the next page.
- Constraint: one of handle, user_id (at least one required)
curl "https://www.socialcrawl.dev/v1/instagram/following" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/instagram/similar
List similar Instagram accounts
Credit cost: 5 (advanced)
Parameters:
- handle (optional, string) — Instagram username without the @ symbol.
- user_id (optional, string) — Instagram numeric user ID. Use this for faster responses.
- Constraint: one of handle, user_id (at least one required)
curl "https://www.socialcrawl.dev/v1/instagram/similar" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/instagram/post/likers
List Instagram post likers
Credit cost: 5 (advanced)
Parameters:
- url (required) — URL of the Instagram post (a /p/ or /reel/ link).
- safe_url (optional, boolean) — When true, returns URL-safe profile picture links suitable for embedding.
curl "https://www.socialcrawl.dev/v1/instagram/post/likers?url=https://www.instagram.com/p/CnpPou9hWqq/" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/instagram/post/stats
Get Instagram post stats including the share count
Credit cost: 5 (advanced)
Parameters:
- url (required) — URL of the Instagram post (a /p/, /reel/, or /tv/ link).
- safe_url (optional, boolean) — When true, returns URL-safe media links suitable for embedding.
curl "https://www.socialcrawl.dev/v1/instagram/post/stats?url=https://www.instagram.com/p/CnpPou9hWqq/" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/instagram/tagged
List posts an Instagram user is tagged in
Credit cost: 5 (advanced)
Parameters:
- handle (optional, string) — Instagram username without the @ symbol.
- user_id (optional, string) — Instagram numeric user ID. Use this for faster responses.
- cursor (optional, string) — Pagination cursor. Use the `next_cursor` from the previous response to fetch the next page.
- safe_url (optional, boolean) — When true, returns URL-safe media links suitable for embedding.
- Constraint: one of handle, user_id (at least one required)
curl "https://www.socialcrawl.dev/v1/instagram/tagged" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/instagram/location/posts
List recent posts at an Instagram location
Credit cost: 5 (advanced)
Parameters:
- location_id (required) — Instagram numeric location ID.
- cursor (optional, string) — Pagination cursor. Use the `next_cursor` from the previous response to fetch the next page.
- safe_url (optional, boolean) — When true, returns URL-safe media links suitable for embedding.
curl "https://www.socialcrawl.dev/v1/instagram/location/posts?location_id=331004901" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/instagram/engagement
Get Instagram engagement statistics
Credit cost: 5 (advanced)
Parameters:
- handle (required) — Instagram username without the @ symbol.
curl "https://www.socialcrawl.dev/v1/instagram/engagement?handle=mrbeast" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/instagram/search/location
Search Instagram locations
Credit cost: 5 (advanced)
Parameters:
- query (required) — Search keyword or phrase to find Instagram locations.
curl "https://www.socialcrawl.dev/v1/instagram/search/location?query=Paris" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/instagram/username-suggestions
Get Instagram username suggestions
Credit cost: 5 (advanced)
Parameters:
- query (required) — Keyword to seed the username suggestions.
curl "https://www.socialcrawl.dev/v1/instagram/username-suggestions?query=mrbeast" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/instagram/search/music
Search Instagram music
Credit cost: 5 (advanced)
Parameters:
- query (required) — Search keyword or phrase to find Instagram audio tracks.
- cursor (optional, string) — Pagination cursor. Use the `next_cursor` from the previous response to fetch the next page.
curl "https://www.socialcrawl.dev/v1/instagram/search/music?query=beyonce" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/instagram/stories
List an Instagram user's active stories
Credit cost: 5 (advanced)
Parameters:
- handle (optional, string) — Instagram username without the @ symbol.
- user_id (optional, string) — Instagram numeric user ID. Use this for faster responses.
- safe_url (optional, boolean) — When true, returns URL-safe media links suitable for embedding.
- Constraint: one of handle, user_id (at least one required)
curl "https://www.socialcrawl.dev/v1/instagram/stories" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/instagram/story/download
Download a single Instagram story
Credit cost: 5 (advanced)
Parameters:
- user_id (optional, string) — Instagram numeric user ID of the story's author.
- story_id (optional, string) — ID of the individual story to download.
- safe_url (optional, boolean) — When true, returns URL-safe media links suitable for embedding.
- Constraint: one of user_id (at least one required)
- Constraint: one of story_id (at least one required)
curl "https://www.socialcrawl.dev/v1/instagram/story/download" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/instagram/music/trending
List trending Instagram music
Credit cost: 5 (advanced)
curl "https://www.socialcrawl.dev/v1/instagram/music/trending" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/instagram/profile/full
Instagram profile, recent posts, and computed analytics in one call.
Credit cost: 5 (override; tier standard)
Parameters:
- handle (optional, string)
- posts (optional, integer) — How many recent posts to fetch + average the computed metrics over (1–100, default 25).
- cursor (optional, string) — Pass a prior response's posts_cursor to deepen the post window.
- include (optional, string) — CSV subset of posts,computed (default both). include=computed drops the raw posts[] to save payload.
curl "https://www.socialcrawl.dev/v1/instagram/profile/full" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/instagram/profile/reels/full
Instagram reels with views, likes, comments, and per-reel share counts where available, in one call.
Credit cost: 5 (advanced)
Parameters:
- handle (optional, string) — Instagram username (with or without a leading @). Required unless user_id is given. The share-count leg needs a handle; a user_id-only call returns views/likes/comments with shares null (partial refund).
- user_id (optional, string) — Numeric Instagram user id. Alternative to handle.
- cursor (optional, string) — Opaque cursor from a prior response's next_cursor to page deeper.
- limit (optional, integer) — Return up to this many items in one call (1–50). The endpoint pages the underlying source server-side until it has collected this many (or runs out), and bills per upstream page consumed (5 credits/page). Omit for a single page.
- Constraint: one of handle, user_id (at least one required)
curl "https://www.socialcrawl.dev/v1/instagram/profile/reels/full" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/instagram/profile/posts/full
Instagram posts with views, likes, comments, and per-post share counts where available, in one call.
Credit cost: 5 (advanced)
Parameters:
- handle (optional, string) — Instagram username (with or without a leading @). Required unless user_id is given. The share-count leg needs a handle; a user_id-only call returns views/likes/comments with shares null (partial refund).
- user_id (optional, string) — Numeric Instagram user id. Alternative to handle.
- cursor (optional, string) — Opaque cursor from a prior response's next_cursor to page deeper.
- limit (optional, integer) — Return up to this many items in one call (1–50). The endpoint pages the underlying source server-side until it has collected this many (or runs out), and bills per upstream page consumed (5 credits/page). Omit for a single page.
- Constraint: one of handle, user_id (at least one required)
curl "https://www.socialcrawl.dev/v1/instagram/profile/posts/full" \
  -H "x-api-key: sc_your_api_key_here"