Instagram — Worker-Internal Reference

Worker-internal routes for Instagram public data. These are not the public API routes — they are called by the API layer (apps/api) via HTTP. Clients never call these directly.

Architecture

Client -> API layer -> GET /instagram/user/info?username_or_url=zuck
  -> SiteRouteEngine
    -> SessionPool.allocate("instagram")
    -> InstagramAdapter.build_fetch_request()
      -> Builds Instagram-specific URL, headers, GraphQL body
      -> Attaches IgFingerprint cookies (ig_did, csrftoken, mid)
      -> Returns FetchRequest with pool-owned session_id
    -> StatefulFetcher.fetch()
      -> Redis: load pooled SessionBundle
      -> HttpFetcher: TLS-impersonated HTTP request via residential proxy
      -> Block detection: "challenge_required", "login_required"
    -> ON SUCCESS:
      -> SessionPool.release(session_id)
      -> Save response cookies + extracted tokens
    -> ON BLOCK:
      -> SessionPool.quarantine(session_id)
      -> Background spawns replacement
    -> InstagramAdapter.transform_response()
      -> Extracts datr, lsd, asbd_id, csrftoken, mid
  -> Response to client

Pooled sessions carry their own sticky identity, cookies and fingerprint, under a shared 260-request concurrency key. The client asks for data and never leases Instagram sessions directly.

Two routes exist in routes.py but have no section below: GET /instagram/user/id (resolve a username to numeric ID, cheaper than /user/info) and GET /instagram/user/summary (condensed profile by numeric ID, one physical data attempt). The summary route does not retry after a tunnel attempt. Both are real, live routes — see routes.py and schemas.py directly.

Endpoints

GET /instagram/user/info

Look up an Instagram user by username. If the feed cannot resolve the ID, summary mode reads it from the mobile page and attempts the compact query once. A successful compact query supplies the complete summary; otherwise the mobile profile stays partial. Full mode keeps partial markers when only summary fields are available.

An active profile-not-found page returns null, including when Instagram serves that page with HTTP 200. Empty or login-gated pages are not evidence of deletion. The same recovery applies to ID lookup. See the dated investigation.

curl "http://localhost:8000/instagram/user/info?username_or_url=zuck"

GET /instagram/user/posts

Fetch a public account's own posted media (photos/videos/reels mixed). Accepts either identifier — pass user_id when known, since it's more stable than a username that can change.

Backed by the logged-out timeline GraphQL query (timeline, by numeric id); a username is resolved first through user_id. The response keeps the retired REST feed's items / more_available / next_max_id shape. See research/instagram/21-logged-out-rest-rollout-2026-10.md.

GET /instagram/user/highlights

Fetch a user's active story presence, live-broadcast status, and highlight reel metadata. (Not additional profile fields — despite the upstream GraphQL operation being named "profile extras", the payload is about story/live/highlight state.)

GET /instagram/oembed

Fetch oEmbed metadata for a public post or reel.

GET /instagram/post

Fetch a post's full public media object (caption, image/video variants, counters) plus its first page of comments. Accepts either identifier — pass media_id when known; code is converted to a numeric media ID locally (no extra request) via the standard Instagram shortcode encoding.

curl "http://localhost:8000/instagram/post?code=CxQl2oQO__S"

A simpler GraphQL mechanism (post_simple operation, no comments) exists in the adapter as a kept-but-unrouted fallback.

GET /instagram/post/comments

Fetch paginated comments for a post (use after /instagram/post for pages beyond the first).

curl "http://localhost:8000/instagram/post/comments?code=CxQl2oQO__S&count=20"

GET /instagram/post/views

View counts for one post or reel. video_view_count comes from the embed page; play_count from the owner's Reels tab (newest 36 reels only, else null). They are different metrics. Photo, private or deleted posts return null.

curl "http://localhost:8000/instagram/post/views?code=DePb6WLuVae"

GET /instagram/user/reels

Fetch a user's reels with pagination. Every item carries play_count (the plays shown on the profile's Reels tab).

curl "http://localhost:8000/instagram/user/reels?user_id=42526505485&count=12"

GET /instagram/location/info

Fetch public location metadata, read from the location page's server-rendered Relay prefetch (the XHR query is rate-limited logged out).

GET /instagram/location/media

Deprecated (2026-07-25). Live-checked against real high-traffic locations (both tabs, with and without a cursor) and it consistently returns empty edges — see research/instagram/12-location-graphql.md. Left wired up for internal/testing use; do not build new callers against it.

Fetch public location media tab data.

GET /instagram/search/popular

Fetch public media, related keyword suggestions, and an AI-generated topic description for a hashtag/keyword.

curl "http://localhost:8000/instagram/search/popular?keyword=travel"

Session Pool

Each pooled session stores a complete browser identity in Redis:

Pool lifecycle:

1. Startup: creates the idle pool without proxy traffic
2. Request: allocates → uses → releases or quarantines
3. Isolation: the cookie jar is scoped to the proxy spec; provider failover is disabled
4. Scaling: all replicas share one Redis concurrency ceiling

Instagram runs on one tier, evomi.core_residential, declared in sites.yaml. The worker rejects /pool/instagram/lease; only the site routes own these sessions.

Pool config (sites.yaml):

sites:
  instagram:
    pool_min_idle: 5
    pool_max_idle: 30
    pool_max_total: 320
    max_concurrency: 260
    session_ttl: 1800

Fingerprint Details

The IgFingerprint dataclass generates realistic device identity:

The last five fields are only populated after a pool warmup fetch (state.py::extract_warmup_metadata) — a fresh session has them empty until its first warmup completes. They're required for Comet POST operations (post, comments); a request without them fails upstream with error 1357005.

Response extraction patterns:

• datr: cookie value or "_js_datr","<value>" in body
• lsd: "LSD",[],{"token":"<value>"} in body
• asbd_id: cookie value or "asbd_id"="<digits>" in body

Block Detection

Status codes 401, 403, 429 and body signatures challenge_required, login_required, checkpoint_required, /accounts/login/, __coig_login=1, Please wait a few minutes, feedback_required, rate_limit, captcha are treated as blocks (adapter.py::_BLOCK_SIGNATURES, 9 signatures total). post_views drops bare captcha: every embed lists arkose_captcha among its CSP hosts. On block, the pooled session is quarantined and a replacement is spawned automatically.

Configuration

Response Format

No envelope wrapper. On a 2xx upstream response the cleaned/raw payload is the body itself (api/responses.py::ok()). On a blocked or errored upstream response, routes.py::_site_response collapses the status into one of a few meanings and returns a minimal problem object via fail() — the HTTP status line carries the code, not a body field:

Block response (upstream 401/403/429):

{
  "type": "UPSTREAM_BLOCKED",
  "message": "Upstream blocked the request",
  "context": { "upstream_status": 403 }
}

with HTTP status 503 (blocks are always reported as 503, regardless of the upstream's own status code). A 404 from upstream returns null with HTTP 200. Any other non-2xx status is forwarded as UPSTREAM_ERROR with that same status code.