Instagram API

Endpoints

Quick start

Coverage & limits

• Independent worker on port 3037, INSTAGRAM_API_KEY in x-api-key. No Instagram account, login, storage, media download or product dependency; one anonymous session per operation with a browser TLS fingerprint. The only memory kept between operations is a bounded map of handle to numeric user id (identifiers only, 15 minutes, 10,000 entries) so that repeat reads of an account skip its profile page.
• Four concurrent operations, 45-second deadline, at most four upstream requests per operation: profile = one document (plus the page load the first time a handle is seen); basic-profile = one document; post-count = page; posts = the 35 KB session probe and the posts document (plus the page when the posts carry no header of the account: private, empty, unknown or age-gated handles); reels = document (plus the page when identified by handle; include_details adds up to two grid documents, or by user id the profile document, the session probe and one grid document); post = document plus page (the document alone with include_comments=false on photos and videos); comments = page; highlights = page (plus a document when identified by user id); popular search = page; each with one shared transient retry for network failures or HTTP 5xx. Challenges, rate limits and 4xx answers are never retried.
• Decoded response budget per operation (about twice the largest read observed): 1 MiB basic-profile, 2 MiB profile, post-count, comments, highlights and popular search, 3 MiB post, 5 MiB posts and reels; 600,000 JSON nodes, 64 levels, 50 items per page (12 per source page), 50 comments and 100 highlights.
• Pagination is caller-carried: posts return next_max_id, reels return paging_info.max_id (top-level max_id with trim). Popular search returns the first page Instagram serves logged-out visitors (first_page_only). Comments return the first page (comments_first_page_only marks further pages, also inside the single-post layout; include_comments=false leaves them out of the single post as comments_omitted); highlight albums list with their covers. Private accounts answer with empty lists and a private_account warning or restricted_page.
• Document ids are pinned to the documents the web client uses; when Instagram retires one, the operation fails operation_unavailable instead of guessing.
• Handles are 1–30 letters, digits, periods and underscores (leading @ accepted), user ids are numeric, post URLs are instagram.com /p/, /reel/, /reels/ or /tv/ permalinks (query strings and fragments ignored). Identity is verified against the request; mismatches fail unsupported_page.
• Optional INSTAGRAM_PROXY_URL (falling back to TWITCH_PROXY_URL, then REDDIT_PROXY_URL) routes every operation through a fresh residential proxy session for hosts that need one.