The three numbers that govern your throughput​

1. Plan RPS — requests per second allowed by your plan. Exceed it and the gateway answers 429 with Retry-After: 1. It is a soft wall: sleep and continue; nothing is lost, nothing is billed.
2. Upstream timeout budget — the gateway allows up to 25 s per upstream call and returns 503 + Retry-After: 2 when exceeded. Large pages (a ~100-post timeline) legitimately take seconds; don't set client timeouts below 30.
3. Monthly request quota — billed only on 200 and 404. Errors and timeouts cost nothing by design, so retrying is always financially safe.

The retry table​

The 400-is-not-retryable rule matters most: a broken cursor is deterministic, and retrying it burns latency for the same answer.

Idempotent pagination: checkpoint everything​

A cursor is a pure function argument — same cursor, same page. That makes checkpointing trivial and resumption exact:

import json, os, time
from getsocialapi import Client, ServiceUnavailable

ig = Client(api_key="gsa_live_...").instagram
CKPT = "followers_cursor.txt"

cursor = open(CKPT).read().strip() if os.path.exists(CKPT) else None
rows = []

while True:
    try:
        page = ig.followers("25025320", count=50, max_id=cursor)
    except ServiceUnavailable as e:
        time.sleep(e.retry_after or 2)
        continue
    rows += page["users"]
    cursor = page.get("next_max_id")
    open(CKPT, "w").write(cursor or "")
    if not cursor:
        break

Kill it anywhere — the process resumes from the checkpoint with zero duplicate requests. For million-item exports this is not an optimization; it is the only way to finish.

Politeness that pays​

• Honor Retry-After verbatim — it reflects actual capacity, not punishment.
• Jitter your bursts — RPS limits are per-second buckets; even spacing beats bursts of exactly-N.
• Cache resolution results — username → pk lookups are stable; re-resolving per request wastes budget.

Observability: three metrics that predict incidents​

1. 429 rate — your client is outpacing the plan; fix pacing.
2. 503 rate — upstream pressure; widen per-page timing, reduce count.
3. Pages-per-cursor progress — a stalled cursor with no errors means an endpoint contract change; alert on it.

The billing asymmetry, restated​

Only 200/404 bill. Every retry mechanic above is free. The correct posture is therefore aggressive about retrying transient states and strict about not retrying deterministic ones — the exact opposite of DOM-scraping instincts.

Build it once, sleep at night — 100 free calls to pressure-test your loop.

Build with GetSocialAPI​

Explore Instagram API and Facebook API for capabilities, pricing and integration examples. Create an account to start with 100 free calls, or follow the quickstart.

Signal 1: liker composition​

The likes endpoint returns a ~100-liker sample. Fake likers cluster into recognizable shapes:

• high share of faceless accounts: default avatar, no posts, private
• follower counts bunched at round numbers (100, 500, 1000)
• usernames with digit-suffix patterns

from getsocialapi import Client

ig = Client(api_key="gsa_live_...").instagram
likers = ig.media_likers(shortcode)["users"]

faceless = sum(1 for u in likers
               if u.get("is_private") and not u.get("profile_pic_url"))
print("faceless share:", faceless / len(likers))

A healthy public post's likers are mostly public, avatar-bearing accounts. A >40% faceless share on a "lifestyle" account is a conversation, not a coincidence.

Signal 2: engagement ratio sanity​

Cross the media card counters with the profile:

• like-to-follower ratio far above the account's historical baseline on isolated posts (bought bursts concentrate on few posts)
• comment-to-like ratio below ~0.5% with high likes (comments cost more than likes — purchased packages reflect that)

Compute the baseline from the account's own grid via user media — you need ~12 posts for a stable median.

Signal 3: comment content patterns​

Full comment export is one walker (see the comments pagination guide). Fraud tells:

• emoji-only / generic praise ("🔥🔥", "Great post!") share
• duplicated texts across different commenter accounts
• commenters whose own accounts are empty
• declared comment_count far above collectable + child comments — the gap is where filtered spam lived

Signal 4: the About screen​

The about-this-account endpoint adds the trust trio:

• recent joined_at on an account claiming brand history
• multiple former_usernames — repurposed handle
• accounts_with_shared_followers clustering — bot farms share audiences by construction

Scoring it​

score = 0
score += faceless_share > 0.4           # liker quality
score += er_outlier > 3                 # burst detection
score += generic_comment_share > 0.6    # comment quality
score += joined_recently                # account age
# 0-1: normal variance; 2: review; 3-4: high fraud probability

The whole battery is ~20 API calls per account — profile, about, media page, one likes sample, one comments page. At influencer-vetting volume it costs less than one disputed invoice.

Every signal here is observable through public endpoints, no cookies, no account access — getsocialapi.com, first 100 calls free.

Build with GetSocialAPI​

Explore Instagram API for capabilities, pricing and integration examples. Create an account to start with 100 free calls, or follow the quickstart.

One call, two targets​

GET /fb/api/v1/feed?user_id=<id>                # profile timeline
GET /fb/api/v1/feed?group_id=<id>&per_page=10   # group feed

Pass exactly one of user_id / group_id. Page size is per_page (integer 3–20, default 10), and the cursor comes from page_info.end_cursor of each page.

The two pagination behaviors​

Profile timelines ask Facebook for exactly per_page posts. Two honest quirks:

• Facebook sometimes returns a post or two more than requested. The service does not trim the response — trimming would silently lose posts at page seams, and per-page cursors do not exist upstream.
• Loop on has_next_page, not on counting posts.

Group feeds are different: Facebook hard-caps its native page at roughly two posts. The service stitches several native pages up to per_page — which means up to two duplicate edges can appear at a seam. Deduplicate by node.cache_id.

from getsocialapi_facebook import Client

fb = Client(api_key="gsa_live_...").facebook

posts, cursor, seen = [], None, set()
while True:
    page = fb.feed(user_id="100053723115450", per_page=10, after=cursor)
    conn = page["data"]["profile"]["timeline_feed_units"]
    for e in conn["edges"]:
        node = e["node"]
        if node.get("cache_id") not in seen:
            seen.add(node.get("cache_id"))
            posts.append(node)
    if not conn["page_info"].get("has_next_page"):
        break
    cursor = conn["page_info"]["end_cursor"]

The same walker works for a group — the connection just lives at data.group_address.group_feed instead.

Example observations​

The figures below are illustrative observations, not a reproducible benchmark or a performance guarantee. Response sizes, latency and coverage depend on the target and upstream availability. Before sizing a production export, record the date, endpoint, parameters, page count and deduplicated item count for your own test.

Errors worth handling​

A broken or foreign cursor returns 400 Invalid Cursor — restart from page 1 instead of retrying. Timeouts come back as 503 with Retry-After: 2; cursors are session-independent, so a retry of the same request after a timeout is always safe.

When to use which endpoint​

• feed — dashboards, monitoring, "latest N posts" widgets. Small pages, low latency, one code path for both targets.
• posts — bulk export of a full timeline. Pages of ~100 posts per request, fixed by the service.
• group_posts — group-only pipelines that want the raw native behavior without stitching.

All three share the same cursor protocol, so switching between them is a base-URL change, not a rewrite. Start with 100 free calls on getsocialapi.com.

Build with GetSocialAPI​

Explore Facebook API for capabilities, pricing and integration examples. Create an account to start with 100 free calls, or follow the quickstart.

The three lists​

Friends are bidirectional and require acceptance — a strong-tie signal. Following is one-directional and free — a weak-tie interest signal. A brand cannot have "friends" at all; it has followers, and it follows other accounts.

The endpoints​

All three live under the same contract — pages of 15, cursor from page_info.end_cursor, passed back as after:

• Friends — GET /fb/api/v1/friends
• Followers — GET /fb/api/v1/followers
• Followings — GET /fb/api/v1/followings (supports name filtering via query)

from getsocialapi_facebook import Client

fb = Client(api_key="gsa_live_...").facebook

def export(fn, uid):
    rows, cursor = [], None
    while True:
        page = fn(uid, after=cursor)
        conn = page["data"]["profile"]["followers"]  # or friends/followings
        rows += [e["node"] for e in conn["edges"]]
        if not conn["page_info"].get("has_next_page"):
            return rows
        cursor = conn["page_info"]["end_cursor"]

followers = export(fb.followers, "100053723115450")

The connection key shifts slightly between endpoints (profile.followers vs group on group-scoped lists) — the response always mirrors the documented shape for that route.

Signals worth computing​

• Follower / following ratio — the classic influence heuristic.
• Audience overlap — followers ∩ following: the account's actual community core.
• Empty friends on a personal profile — either privacy settings or a repurposed account; cross-check with the profile overview.
• Followings without followers — a curation-heavy account (news, aggregation) rather than a social one.

Privacy boundaries, stated honestly​

Friends lists are frequently hidden by privacy settings even when the profile itself is public. The API returns an empty connection in that case — an empty list is data ("hidden"), not a bug. Design pipelines to distinguish empty-because-hidden from empty-because-none by checking the profile's privacy flags first.

Takeaway​

Three lists, three endpoints, one cursor protocol. Decide which question you are actually asking before choosing the route — then the walk is always the same 10 lines. Try all three on getsocialapi.com — the first 100 calls are free.

Build with GetSocialAPI​

Explore Facebook API for capabilities, pricing and integration examples. Create an account to start with 100 free calls, or follow the quickstart.

The endpoint​

GET /fb/members/all/{group_id}?after=<cursor>

One page holds a fixed batch of 15 members — the size is set by the upstream and there is no count knob. The response carries three things you care about:

• data.group.new_member_list.edges[] — member nodes of this page
• data.group.new_member_list.page_info.end_cursor — the cursor to the next page
• data.group.new_member_list.page_info.has_next_page — your loop condition

To resolve a group from its URL (facebook.com/groups/800246542990860) use the resolve endpoint first, or pass the numeric id directly.

The walking loop​

from getsocialapi_facebook import Client

fb = Client(api_key="gsa_live_...").facebook

members, cursor = [], None
while True:
    page = fb.members("800246542990860", after=cursor)
    conn = page["data"]["group"]["new_member_list"]
    members += [e["node"] for e in conn["edges"]]
    if not conn["page_info"].get("has_next_page"):
        break
    cursor = conn["page_info"]["end_cursor"]

print(len(members), "members exported")

Three rules that make this loop lossless:

1. Pass the cursor verbatim. end_cursor is a long base64 string; copy it as-is into after. Never try to decode or slice it — cursors are opaque and session-independent, but only whole.
2. Loop on has_next_page, not on counting. Page size can wobble by one node at seam boundaries; the flag is the source of truth.
3. Deduplicate by node id if you re-run the walk — Facebook occasionally reshuffles members between pages while you paginate (joins/leaves happen live).

What a member node looks like​

Each edge carries node.name, node.id, node.profile_picture and — for searchable lists — a node.subtitle with the city. Business accounts may include job_history entries.

Errors that matter​

Failed calls (everything except 200/404) are not billed — a safe property of the whole GetSocialAPI billing model.

Takeaways​

Full group export is a solved problem if you respect the cursor protocol: fixed pages, has_next_page as the loop condition, verbatim cursors, dedupe on re-runs. The Python walker above is ~10 lines and exports groups of any size. Open an account — the first 100 calls are free — and try it on your own group id.

Build with GetSocialAPI​

Explore Facebook API for capabilities, pricing and integration examples. Create an account to start with 100 free calls, or follow the quickstart.

The endpoint and its shape​

GET /fb/api/v1/group_posts/{group_id}?after=<cursor>

The payload lives at data.group_address.group_feed:

• edges[] — mixed units; filter by node.__typename
• page_info.end_cursor — the cursor (~550 chars, base64)
• page_info.has_next_page — loop condition

__typename values that matter:

Every Story node carries cache_id (dedupe key), the author, message text, attachment, reaction and comment counters, and timestamps.

The walker​

from getsocialapi_facebook import Client

fb = Client(api_key="gsa_live_...").facebook

posts, cursor, seen = [], None, set()
while True:
    page = fb.group_posts("800246542990860", after=cursor)
    feed = page["data"]["group_address"]["group_feed"]
    for e in feed["edges"]:
        n = e["node"]
        if n.get("__typename") == "Story" and n.get("cache_id") not in seen:
            seen.add(n.get("cache_id"))
            posts.append(n)
    if not feed["page_info"].get("has_next_page"):
        break
    cursor = feed["page_info"]["end_cursor"]

print(len(posts), "posts collected")

Per-page reality​

Facebook serves its native group page in chunks of 2–3 Story posts — that is upstream behavior, not an API limitation. One request = one chunk; a 100-post group costs ~40 requests. Latency per page is ~3 seconds. If that cadence does not fit your use case, the unified feed endpoint stitches chunks server-side up to per_page=20 at the cost of occasional seam duplicates.

Cursor rules​

1. Take end_cursor only from page_info — nodes contain internal cursor fields that look identical and produce Invalid Cursor errors.
2. Pass it verbatim as after; never decode or slice it.
3. Cursors are reusable and session-independent — safe to checkpoint long exports.

A broken cursor returns 400 Invalid Cursor (not billed) — restart the walk from page 1.

Enrich with members​

Post collection answers "what"; the group members endpoint answers "who". Cross-referencing post authors against the member export catches lurkers (members who never post) and power posters (members dominating the feed) — the two lists every community manager wants.

Start on getsocialapi.com — 100 free calls cover a small group end to end.

Build with GetSocialAPI​

Explore Facebook API for capabilities, pricing and integration examples. Create an account to start with 100 free calls, or follow the quickstart.

Step 1: resolve the link​

GET /fb/resolve?url=https://www.facebook.com/groups/800246542990860
GET /fb/api/v1/resolve-profile?profile_url=https://facebook.com/zuck

The link resolver classifies any facebook.com URL — profile, group, page or post — and returns its numeric id and type. The profile resolver is the focused variant for profile/page URLs, including the people/… alias forms that redirect everywhere else.

from getsocialapi_facebook import Client

fb = Client(api_key="gsa_live_...").facebook

entity = fb.resolve("https://www.facebook.com/groups/800246542990860")
print(entity)          # type + numeric id
uid = fb.resolve_profile("https://facebook.com/zuck")

The id is the key every other endpoint wants: members, posts, feed, followers, friends, contacts.

Step 2: pull the overview card​

GET /fb/api/v1/overview?user_id=<id>

The overview is the cheap profile card: name, avatar, verification, friend/follower counters, privacy posture. Before spending requests on deep lists, the overview answers the gating questions:

The pattern​

target = fb.resolve(profile_url)          # any URL form in
card = fb.overview(user_id=target_id)     # what exists, what's public

if card says lists are public:
    followers = walk(fb.followers, target_id)
    friends   = walk(fb.friends, target_id)

Resolve → overview → deep lists. The first two calls cost two units and prevent entire wasted walks on private or misclassified targets.

Where the ids flow next​

• Groups → members, group posts, unified feed
• Profiles/pages → followers, followings, friends, contacts

Handling the alias zoo​

Facebook happily serves several URLs for one entity: facebook.com/zuck, fb.com/zuck, m.facebook.com/zuck, profile.php?id=4. Don't normalize URLs client-side — the resolver tracks canonicalization server-side, and its answer is the id your pipeline should trust.

Two calls, any URL in, stable id out — getsocialapi.com, 100 free calls to wire the pair into your stack.

Build with GetSocialAPI​

Explore Facebook API for capabilities, pricing and integration examples. Create an account to start with 100 free calls, or follow the quickstart.

The call​

curl -H "X-API-Key: $KEY" \
  "https://api.getsocialapi.com/v1/user/about/25025320"

{
  "username": "instagram",
  "country": "United States",
  "joined_at": "February 2012",
  "former_usernames": null,
  "accounts_with_shared_followers": null,
  "is_verified": true,
  "unavailable": false,
  "has_about_data": true
}

How to read the fields​

Sparse and private accounts return null fields — that is normal, not an error. The useful pattern for trust scoring:

about = ig.user_about(user_id)
if about["unavailable"] or not about["has_about_data"]:
    risk = "unknown"
elif about["former_usernames"] and about["former_usernames"] > 3:
    risk = "elevated"
else:
    risk = "normal"

Pair it with the profile​

user_about answers who is behind the account; the profile endpoint answers what the account does (follower ratio, bio, category). Together they form a cheap two-call screen for fraud pipelines, marketplace onboarding and due-diligence automations.

Takeaways​

One call, no cookies, no login — country, join date, former usernames and shared-follower clustering for any account id. Resolve usernames to ids with the search endpoint first. The first 100 calls are free — start here.

Build with GetSocialAPI​

Explore Instagram API for capabilities, pricing and integration examples. Create an account to start with 100 free calls, or follow the quickstart.

The endpoint​

GET /ig/media/comments/{pk}?sort_order=recent&count=30&min_id=<cursor>

The media argument accepts a numeric pk or the shortcode from the post URL (Deu3BoCBbDP from instagram.com/p/Deu3BoCBbDP/) — no oEmbed resolution needed.

Rule one: always sort_order=recent​

Without it you get a ranked preview — roughly fifteen comments Instagram considers interesting. Ranked pages come from different pool accounts and overlap between requests: collecting them produces duplicates and gaps.

With sort_order=recent the contract changes completely:

• pages are strictly chronological (newer → older)
• pages are disjoint — concatenation is the final order, no sorting needed
• the cursor next_min_id is always present while more comments exist

Rule two: the cursor is next_min_id, never max_id​

The response carries next_min_id (a long JSON string with cursor tokens — pass it back verbatim, URL-encoded; SDKs do this for you). next_max_id is always null on this route: the classic max_id pagination used by followers endpoints does not work here.

from getsocialapi import Client

ig = Client(api_key="gsa_live_...").instagram

comments, cursor = [], None
while True:
    page = ig.media_comments("Deu3BoCBbDP", count=30,
                             sort_order="recent", min_id=cursor)
    comments += page["comments"]
    cursor = page.get("next_min_id")
    if not cursor:
        break

print(len(comments), "comments collected")

Example observations​

The figures below are illustrative observations, not a reproducible benchmark or a performance guarantee. Response sizes, latency and coverage depend on the target and upstream availability. Before sizing a production export, record the date, endpoint, parameters, page count and deduplicated item count for your own test.

Collecting every comment of a viral post (105 comments declared): 7 requests, 19.9 seconds total, zero duplicates, zero losses. Real page size is 12–20 comments regardless of count (accepted range 1–50, effectively a hint).

Two honest caveats:

1. The sum is below comment_count. The counter includes spam-filtered comments nobody can see through any client. Expect 5–15% fewer items than the declared number on aged posts.
2. Replies need a second pass. Each root comment carries child_comment_count; threads are collected separately.

Bonus: likers and the media card​

The same media argument works for the media card (items[0]: pk, media_type, caption, like/comment/view counts, owner) and likers (up to ~100 users, no pagination) — handy to enrich a comments export with post metadata.

Takeaways​

sort_order=recent + verbatim next_min_id until null is the complete protocol. Ten lines of Python, one request per ~15 comments, and the full comment section of any public post lands in your database — open an account and the first 100 calls are on us.

Build with GetSocialAPI​

Explore Instagram API for capabilities, pricing and integration examples. Create an account to start with 100 free calls, or follow the quickstart.

The endpoint​

GET /v1/followers/{user_id}?count=50&max_id=<cursor>

• user_id is the numeric pk — resolve a handle first with user search
• count is 1–50 (the page size you request)
• max_id is the cursor: take next_max_id from the previous response and pass it back verbatim

The export loop​

from getsocialapi import Client

ig = Client(api_key="gsa_live_...").instagram

followers, cursor = [], None
while True:
    page = ig.followers(user_id="25025320", count=50, max_id=cursor)
    followers += page["users"]
    cursor = page.get("next_max_id")
    if not cursor:
        break

print(len(followers), "followers")

Collect each returned page and deduplicate by pk. Follower lists can change while an export is running, so cursor pagination alone does not guarantee a fixed snapshot or complete coverage.

Visibility and verified-account limits​

Exports cover the follower data the endpoint makes available, rather than a guaranteed complete list. On verified accounts Instagram exposes approximately one page of 50 followers, without a continuation cursor; the name filter is ignored. Private or restricted accounts may return limited or no data. Follow the current endpoint limitations.

Name filtering​

The endpoint accepts a query parameter pushed down to Instagram: query=marc returns only followers whose name matches. It is the cheap way to answer "does this account have a follower named X" without exporting anything.

Request-budget estimates for unverified accounts​

For large exports the cursor is your checkpoint: it is a stable, session-independent string. Persist it, and resume the walk after any interruption from exactly where you stopped.

Rate limits and retries​

Follow your plan's RPS budget — exceed it and the gateway answers 429 with Retry-After: 1. Timeouts surface as 503 with Retry-After: 2; retrying the identical request is safe because the cursor fully determines the page. The official Python SDK does this automatically: three retries, exponential backoff, Retry-After respected.

Pair it with following for a mutuals calculation​

Followers + following gives you the social graph edges you need for the classic questions — mutuals, follower ratio, ghost-following detection:

followers = export(ig.followers, uid)          # who follows them
following = export(ig.following, uid)          # who they follow
mutuals = {u["pk"] for u in followers} & {u["pk"] for u in following}

One account, two exports, every graph question answered — try it with 100 free calls on getsocialapi.com.

Build with GetSocialAPI​

Explore Instagram API for capabilities, pricing and integration examples. Create an account to start with 100 free calls, or follow the quickstart.

Step 1: search the neighborhood​

GET /v1/ig/hashtag/search/{query}

The hashtag search returns every tag matching the query with its media count — #gymgirl, #gymgirlfit, #gymgirls… This is the expansion step: from one seed to the full variant list, volume-ranked:

from getsocialapi import Client

ig = Client(api_key="gsa_live_...").instagram

tags = ig.hashtag_search("gymgirl")["results"]
for t in sorted(tags, key=lambda x: -x.get("media_count", 0)):
    print(t["name"], t["media_count"])

A leading # is accepted and trimmed — #gym girl resolves the same as gymgirl.

Step 2: size each tag​

GET /v1/ig/hashtag/info/{tag}

Hashtag info resolves a tag to its id and authoritative media count. In search results the counts can be cached; before committing crawl budget, re-check the finalists.

The volume tiers that matter:

Step 3: walk the posts​

GET /v1/v2/hashtag/posts/{tag}?max_id=<cursor>

Hashtag posts return the native page (~15–18 posts) with next_max_id for pagination. Items carry caption, like/comment counts, owner and timestamps — everything needed for engagement-rate scoring per tag:

posts, cursor = [], None
while True:
    page = ig.hashtag_posts("#gymgirl", max_id=cursor)
    posts += page["posts"]
    cursor = page.get("next_max_id")
    if not cursor or len(posts) >= 200:
        break

avg_er = sum(p["like_count"] for p in posts) / len(posts)

What the dataset answers​

• Tag selection — relevance × competitiveness × observed engagement, per variant.
• Posting patterns — taken_at histograms: when a tag's audience actually posts (proxy for when they browse).
• Creator discovery — owners recurring across a tag's top posts are its real community anchors; pull their profiles next.

Scale honestly​

A 50-tag neighborhood at 200 posts each is ~700 requests. Checkpoint next_max_id per tag — cursors are stable strings, so the crawl can resume across days within plan limits.

Search, size, walk — three calls, one dataset, on getsocialapi.com. First 100 free.

Build with GetSocialAPI​

Explore Instagram API for capabilities, pricing and integration examples. Create an account to start with 100 free calls, or follow the quickstart.

The endpoint​

GET /v1/ig/media/likers/{pk|shortcode}

The argument accepts the numeric media pk or the shortcode from the post URL (Deu3BoCBbDP from instagram.com/p/Deu3BoCBbDP/) — no oEmbed round-trip needed:

from getsocialapi import Client

ig = Client(api_key="gsa_live_...").instagram

likers = ig.media_likers("Deu3BoCBbDP")["users"]
print(len(likers), "likers")

The honest limits​

• Up to ~100 users, no pagination. Instagram caps the likers surface; the endpoint returns what the platform exposes. For a post with 95 740 likes you get the visible sample — typically the most recent or most relevant hundred.
• The like counter on the media card is the true total; the likers list is a sample. Report both.

What the sample is good for​

Even a sample supports real analysis:

1. Audience composition — private/public ratio, verified share, follower-count distribution of the accounts that engaged.
2. Engaged-audience diff — likers minus commenters: the silent majority vs the conversational core.
3. Influencer vetting — a creator whose likers are 80% faceless private accounts with default avatars is telling you something.
4. Competitor benchmarking — same sample across competing posts normalizes engagement claims.

info = ig.media_info("Deu3BoCBbDP")["items"][0]
print("declared:", info["like_count"], "| sample:", len(likers))
private_share = sum(1 for u in likers if u.get("is_private")) / len(likers)

Combining the three engagement surfaces​

Counters first (cheap), samples and comments second (deeper). That ordering keeps request budgets sane on large analyses.

Likes are one call away — 100 free calls profile a dozen posts end to end.

Build with GetSocialAPI​

Explore Instagram API for capabilities, pricing and integration examples. Create an account to start with 100 free calls, or follow the quickstart.

The two endpoints​

GET /v1/ig/location/info/{pk}        # place card
GET /v1/ig/location/media/{pk}       # posts at the place, paginated

The location card returns name, address, coordinates and the media count — everything needed to verify you have the right place among same-named venues:

from getsocialapi import Client

ig = Client(api_key="gsa_live_...").instagram

loc = ig.location_info(pk)
print(loc["name"], loc.get("lat"), loc.get("lng"), loc.get("media_count"))

Walking the media​

The location media route is native-page paginated: pass next_max_id back as max_id while it is returned. Items are the standard media shape — captions, counters, owners, timestamps.

posts, cursor = [], None
while True:
    page = ig.location_media(pk, max_id=cursor)
    posts += page["items"]
    cursor = page.get("next_max_id")
    if not cursor or len(posts) >= 500:
        break

One trap: the response also carries a next_page counter. It is a page number, not a cursor — using it as max_id returns Invalid Cursor. next_max_id or bust.

Where place ids come from​

• Media items themselves: every geotagged post from user media or hashtag posts carries its location id in the payload.
• The venue's own Instagram profile often pins its place.

Harvest ids from any media stream you already collect, dedupe, then expand each into its own post set.

What location datasets answer​

Coordinates in the location card make radius queries trivial — harvest cards for all candidate venues, filter by haversine distance, then walk only the ones inside your fence.

Scale notes​

A venue with 50k geotagged posts is ~2 500 pages at native size — checkpoint the cursor per location and resume across sessions (see the rate limits guide). For dense city-center research, sample by time window instead of full walks: the goal is usually the distribution, not the census.

Place ids in, posts out — getsocialapi.com, first 100 calls free.

Build with GetSocialAPI​

Explore Instagram API for capabilities, pricing and integration examples. Create an account to start with 100 free calls, or follow the quickstart.

Active stories​

GET /v1/ig/user/stories/{user_id}

The stories endpoint returns the currently live tray: images, videos, timestamps, and for video items the view and reaction counters the account itself can see. No pagination — the tray is small by nature (24h lifetime, max 100 items).

from getsocialapi import Client

ig = Client(api_key="gsa_live_...").instagram

stories = ig.user_stories(user_id="25025320")  # items[] with taken_at, media urls
for s in stories.get("items", []):
    print(s["taken_at"], s.get("media_type"))

Highlights: the curated archive​

GET /v1/ig/user/highlights/{user_id}          # tray: ids + titles
GET /v1/ig/highlight/stories/{highlight_id}   # stories inside one highlight

The highlights tray lists the account's highlight reels — id, title, cover media. Each reel unfolds through highlight stories:

tray = ig.user_highlights(user_id="25025320")
for h in tray.get("tray", []):
    reel = ig.highlight_stories(h["id"].replace("highlight:", ""))
    print(h.get("title"), "->", len(reel.get("items", [])), "stories")

Note the highlight: prefix some trays carry on ids — strip it before the second call (the SDK does this for you).

Why highlights matter more than they look​

Highlights are the only Instagram surface where the account itself performs permanent editorial selection. The tray order, titles, and what got promoted from stories to highlight — that combination is a free, self-reported content strategy:

• Product catalogs — shops keep catalogs as highlights; the tray is the catalog structure.
• Link-in-bio analytics — link stickers inside highlight stories are permanent CTAs; extracting them gives a real conversion surface inventory.
• Compliance archiving — regulated industries must archive ephemeral marketing; highlights capture what the account chose to keep, stories what existed.

The daily pipeline​

1. Poll stories for target accounts (they live 24h — cadence matters).
2. Diff against your store; save new items with taken_at.
3. On tray changes, pull the affected highlight and link its stories.
4. Enrich with the profile card for follower context.

Two endpoints, one id quirk, no pagination to get wrong. Start tracking on getsocialapi.com — 100 free calls.

Build with GetSocialAPI​

Explore Instagram API for capabilities, pricing and integration examples. Create an account to start with 100 free calls, or follow the quickstart.

The endpoint​

GET /v1/ig/user/media/{user_id}?count=12&max_id=<cursor>

user_id is the numeric pk (see username resolution); count sets the requested page size; max_id carries the cursor from the previous response's next_max_id.

The walk​

from getsocialapi import Client

ig = Client(api_key="gsa_live_...").instagram

posts, cursor = [], None
while True:
    page = ig.user_medias(user_id="25025320", count=12, max_id=cursor)
    posts += page["items"]
    cursor = page.get("next_max_id")
    if not cursor:
        break

print(len(posts), "posts")

Pages concatenate cleanly — no dedupe needed for a stable account. For an account that posts mid-export, re-run and merge by media pk.

What each item carries​

The media-type split alone answers most content-strategy questions: photo/video/carousel ratio, engagement by format, posting cadence from taken_at deltas.

Variants worth knowing​

• Tagged posts — posts where the account appears tagged; same pagination contract. Good for UGC monitoring.
• Stories — the ephemeral layer, no pagination (active stories in one response).
• Hashtag posts — the same item shape from a different entry point.

Sizing the export​

A 500-post archive is ~40 requests at count=12 — under a minute within plan RPS. For 10 000+ post archives, checkpoint the cursor every N pages; it is stable across sessions, so the export can resume after any interruption without re-walking.

The Python walker above is ~8 lines — 100 free calls cover a medium-sized profile end to end.

Build with GetSocialAPI​

Explore Instagram API for capabilities, pricing and integration examples. Create an account to start with 100 free calls, or follow the quickstart.

Path 1: search (the default)​

GET /v1/search/username/{query}?count=10

Returns up to ten matches with pk, username, full_name, is_private, is_verified. For a unique handle the first hit is the account; for ambiguous handles (@john), rank by follower_count or require exact username equality:

from getsocialapi import Client

ig = Client(api_key="gsa_live_...").instagram

hits = ig.search_username("natgeo", count=10)["users"]
match = next(u for u in hits if u["username"] == "natgeo")
uid = match["pk"]

Path 2: username lookup (exact)​

When you already trust the handle, the username endpoint resolves it to the full profile in one call — pk plus biography, counters, category. One call instead of search + info.

The trap: shortcodes are not ids​

Media shortcodes — the Deu3BoCBbDP in instagram.com/p/Deu3BoCBbDP/ — historically encoded the media pk in base64, and half the internet still "decodes" them client-side. Two reasons to stop:

1. The encoding changed. New shortcodes (the D… family) decode to wrong numbers — silently, with no error.
2. It was never a contract.

The robust options:

• Media endpoints that accept a shortcode directly (media info, comments, likes) — pass it as the argument, no conversion needed.
• For the raw pk: Instagram's public oEmbed endpoint returns the media_id — the number before the underscore.

import requests
from urllib.parse import quote

r = requests.get(
    "https://i.instagram.com/api/v1/oembed/",
    params={"url": "https://www.instagram.com/p/Deu3BoCBbDP/"},
    timeout=15)
pk = r.json()["media_id"].split("_")[0]   # e.g. 4012386322294878415

User id vs media id vs comment id​

The suffix after the underscore in a media id is the owner pk — strip it before passing the id anywhere else.

Caching discipline​

Resolution is the cheapest call you will make and the most wasteful to repeat. Cache handle → pk pairs (they are stable; handles change, ids never do), and re-resolve only on 404 from downstream endpoints.

All the endpoints above are live on getsocialapi.com — 100 free calls, no cookies required.

Build with GetSocialAPI​

Explore Instagram API for capabilities, pricing and integration examples. Create an account to start with 100 free calls, or follow the quickstart.

Why cookie-based scraping fails structurally​

A self-hosted scraper logs in as you (or accounts you manage) and browse the way a human would. Three structural problems follow:

1. One identity, one fingerprint. Every request comes from your IP with your cookies. Anomaly detection needs one signal — you.
2. You are the bottleneck. Rate limits are per-account. Scale means more accounts, which means more bans, which means more accounts.
3. The client breaks weekly. Frontend changes, challenge pages, forced re-logins — the maintenance tax compounds until the maintainer quits.

The API-key model inverts all three: many identities on the provider side, your IP never touches Instagram, and the client contract is a stable REST surface with cursors instead of DOM selectors.

What "no cookies" means in practice​

With a data API the only credential you hold is an API key. No accounts, no sessions, no 2FA puzzles. Concretely, on getsocialapi.com:

• collection runs on provider infrastructure and pool accounts — your profiles stay out of the loop entirely (there is nothing to ban);
• a request is either a paginated cursor walk or a single lookup — deterministic, retryable, cacheable;
• failures are states, not surprises: HTTP codes tell you exactly what happened and what to do next.

The failure model, honestly​

Billed states are only 200/404 — a request that times out or errors costs nothing. Cursors are stable strings, independent of sessions: any interrupted walk resumes exactly where it stopped, from any client. That single property is what makes million-request exports tractable.

Idempotent pagination: the quiet superpower​

DOM scraping checkpoints are fragile because page N is re-derived from UI state. Cursor pagination is a pure function of the cursor: same cursor in, same page out. Combine that with a 503-retry and you get exactly-once collection semantics at the page level — the unit that matters for billing and for data integrity.

while True:
    try:
        page = ig.followers(uid, count=50, max_id=cursor)
    except ServiceUnavailable as e:      # 503
        time.sleep(e.retry_after); continue
    store(page); cursor = page.get("next_max_id")
    if not cursor: break

The official Python SDK ships this loop's retry logic built in — three attempts, backoff, Retry-After respected.

When self-hosted still makes sense​

Honesty cuts both ways: if your volume is tiny, your targets obscure, and your timeline flexible — a self-hosted scraper is free. The moment any of those three changes, the maintenance tax exceeds any API bill. The API is not the cheap option; it is the flat-cost option.

Takeaway​

Scrapers die because identity is fragile. Data APIs survive because they move the fragile part behind a contract: a key, a cursor, an HTTP code. 100 free calls is enough to feel the difference.

Build with GetSocialAPI​

Explore Instagram API and Facebook API for capabilities, pricing and integration examples. Create an account to start with 100 free calls, or follow the quickstart.

What we export​

Four paginated walks, one shared helper — every list is cursor-based, so the pattern is identical (see the followers export guide for the loop; Facebook uses after instead of max_id).

from getsocialapi import Client
from getsocialapi_facebook import FacebookAPI, Transport

ig = Client(api_key="gsa_live_...").instagram
fb = FacebookAPI(Transport(
    base_url="https://api.getsocialapi.com/fb",
    api_key="gsa_live_..."))

def ig_export(fn, uid):
    rows, cursor = [], None
    while True:
        page = fn(uid, count=50, max_id=cursor)
        rows += page["users"]
        cursor = page.get("next_max_id")
        if not cursor:
            return rows

ig_followers  = ig_export(ig.followers, ig_uid)
ig_following  = ig_export(ig.following, ig_uid)

Mutuals: the community core​

f_ids = {u["pk"] for u in ig_followers}
g_ids = {u["pk"] for u in ig_following}
mutuals = f_ids & g_ids
print(f"followers={len(f_ids)}, following={len(g_ids)}, mutual={len(mutuals)}")

Mutuals are the strongest relationship signal both networks expose: each side opted into the other. Growth teams treat mutual-count trajectory as a leading engagement indicator — it moves before follower count does.

Ratio and asymmetry​

ratio = len(f_ids) / max(len(g_ids), 1)
one_way = g_ids - f_ids   # follows them, they don't follow back

• ratio >> 1 — broadcast account (media, brand).
• ratio ≈ 1 with high mutuals — personal/community account.
• one_way dominated by spam-pattern profiles — audience quality debt.

Cross-network identity hints​

Facebook pages and Instagram accounts of the same brand rarely share ids — but they share people. Sample usernames/normalized names from both follower lists and intersect: the overlap coefficient between the two audiences measures how separable the communities really are (marketing teams use it to decide whether to run one strategy or two).

Storage shape​

One table beats clever schemas at collection time:

edges(source, target, network, edge_type, first_seen, last_seen)

Re-running the export updates last_seen; edges that disappear move to an archive table. Churn (edges with stale last_seen) is itself a dataset — audience decay per account.

Budget math​

A brand with 50k Instagram followers + 3k following and a Facebook page with 20k followers is ~1 500 + 60 + ~1 300 + ~200 requests — about 3 100 calls, an hour of polite pacing, resumable via cursors at any point. The rate limits guide covers the retry loop.

Four walks, one table, every graph question — getsocialapi.com, first 100 calls free.

Build with GetSocialAPI​

Explore Instagram API and Facebook API for capabilities, pricing and integration examples. Create an account to start with 100 free calls, or follow the quickstart.