InstagramAnswer

Instagram API followers list: Meta returns counts only

Meta's Instagram API returns follower counts, not the list. Ours lists public followers at 1 credit a call; big accounts stop at one page of up to 50.

Updated 6 min read

Short answer

  • Meta's Instagram APIs return follower counts and audience breakdowns, and no endpoint or field lists the accounts that follow someone.
  • ToolzerHub's /v2/instagram/user/followers lists a public account's followers, but a big account stops at one page of 7 to 50. Small business accounts page on; we read 1,492 from one.
  • A call costs 1 credit, and 1,000 followers on an account that pages cost about 40 credits. Private accounts return an empty list.
On this page

No. Meta's Instagram APIs return follower counts, not the accounts behind them, and no endpoint or field lists who follows someone. Our API lists a public account's followers by username, but a big account stops at one page of 7 to 50 followers, and only smaller accounts page on. The script below saves either list to CSV.

What Meta's API returns about followers

Meta's IG User reference has two fields, followers_count and follows_count, and none of its 19 edges lists followers or following. Use Meta's API when the account is yours: counts, demographics and growth are accurate there. For your own list, Instagram's data export is the route.

You want Official route You get
Your own count followers_count One number
Another account's count Business Discovery One number
Who follows you follower_demographics Age, place, gender
The list itself Not found Nothing

Business Discovery returns another account's counts, and follower_demographics works for your own professional account only. Details are in our post on the Instagram Basic Display API replacement.

List a public account's followers

We make ToolzerHub. Our Instagram API lists a public account's followers and following by username with one API key and no Meta app. GET /v2/instagram/user/followers pages with end_cursor and GET /v2/instagram/user/following with max_id; both cost 1 credit a call. The v2 response has no total; /v1/instagram/user/info returns it at 1 credit.

Export either list to CSV

This script pages a followers or following list to CSV with a page cap, one row per account, de-duplicated by id because pages can overlap. cell() puts an apostrophe in front of text that starts with =, +, - or @, so a spreadsheet shows it as text.

python
import csv
import os
import sys
import time

import requests

BASE = "https://api.toolzerhub.com/v2/instagram/user"
HEADERS = {"x-api-key": os.environ.get("TOOLZERHUB_API_KEY", "")}
FIELDS = ["account", "list", "username", "full_name", "is_private", "is_verified", "id"]
calls = 0


def cell(value):
    # Spreadsheets run text that starts with = + - or @ as a formula; an apostrophe keeps it text.
    if isinstance(value, str) and value[:1] in ("=", "+", "-", "@", "\t", "\r"):
        return "'" + value
    return value


def get(kind, params, tries=5):
    # 429 and 503 are retryable; the wait comes from the error body or the Retry-After header.
    global calls
    for attempt in range(tries):
        r = requests.get(f"{BASE}/{kind}", headers=HEADERS, params=params, timeout=90)
        calls += 1
        if r.status_code == 400:  # bad username: skip this account, keep the rest of the run
            print("bad request:", r.json()["error"]["message"].splitlines()[0])
            return None
        if r.status_code not in (429, 503) or attempt == tries - 1:
            r.raise_for_status()
            return r.json().get("data")  # None when there is nothing to return
        try:
            wait = r.json()["error"]["details"]["retryAfter"]
        except (ValueError, KeyError, TypeError):
            wait = None
        try:
            wait = int(wait or r.headers.get("Retry-After") or 5 * (attempt + 1))
        except ValueError:
            wait = 5 * (attempt + 1)
        time.sleep(min(wait, 60))


def next_followers(data):
    info = data.get("page_info") or {}
    return ("end_cursor", info["end_cursor"]) if info.get("has_next_page") and info.get("end_cursor") else None


def next_following(data):
    return ("max_id", data["next_max_id"]) if data.get("has_more") and data.get("next_max_id") else None


NEXT = {"followers": next_followers, "following": next_following}


def export_list(writer, account, kind, max_pages):
    params, seen, rows, pages = {"username_or_id": account}, set(), 0, 0
    while pages < max_pages:
        data = get(kind, params)
        if not data or not data.get("users"):
            break  # null data, a private account or an empty list
        pages += 1
        for u in data["users"]:
            if u["id"] in seen:  # pages can overlap
                continue
            seen.add(u["id"])
            rows += 1
            writer.writerow({
                "account": account, "list": kind, "username": cell(u.get("username")),
                "full_name": cell((u.get("full_name") or "").replace("\n", " ")),
                "is_private": u.get("is_private"), "is_verified": u.get("is_verified"), "id": u["id"],
            })
        nxt = NEXT[kind](data)
        if not nxt:
            break
        params[nxt[0]] = nxt[1]
        time.sleep(0.3)
    note = "" if pages else " (nothing returned: unknown, private or empty)"
    print(f"{account} {kind}: {rows} accounts, {pages} pages{note}")
    return rows


def main(accounts, max_pages="20", which="followers", out="followers.csv"):
    kinds = ["followers", "following"] if which == "both" else [which]
    total = 0
    with open(out, "w", newline="", encoding="utf-8") as f:
        writer = csv.DictWriter(f, fieldnames=FIELDS)
        writer.writeheader()
        for account in [a.strip().lstrip("@") for a in accounts.split(",") if a.strip()]:
            for kind in kinds:
                total += export_list(writer, account, kind, int(max_pages))
    print(f"wrote {total} rows to {out} in {calls} calls")


if __name__ == "__main__":
    if len(sys.argv) < 2 or (len(sys.argv) > 3 and sys.argv[3] not in ("followers", "following", "both")):
        sys.exit("usage: python instagram_followers.py nasa,natgeo [max_pages]"
                 " [followers|following|both] [file.csv]")
    if not HEADERS["x-api-key"]:
        sys.exit("set TOOLZERHUB_API_KEY first")
    main(*sys.argv[1:])

python instagram_followers.py nasa,natgeo,nike,spacex 20 both followers.csv pages both lists for four accounts and prints:

text
nasa followers: 50 accounts, 1 pages
nasa following: 64 accounts, 4 pages
natgeo followers: 50 accounts, 1 pages
natgeo following: 131 accounts, 8 pages
nike followers: 48 accounts, 1 pages
nike following: 183 accounts, 11 pages
spacex followers: 39 accounts, 1 pages
spacex following: 3 accounts, 1 pages
wrote 568 rows to followers.csv in 28 calls

Of the 187 follower rows, 48 were private accounts and 3 were verified; of the 381 following rows, 351 were verified. The following list repeats accounts across pages: nasa follows 90, and 64 distinct accounts came back.

What the lists showed

We tried 28 public accounts, mostly brands.

  • 24 of the 28 returned one page of 7 to 50 followers and stopped. They ranged from 9,307 followers to 290,970,089 (nike).
  • Smaller accounts page. Three accounts, with 2,389, 4,173 and 13,597 followers, had a next page. On the two business accounts, 20 pages gave 478 and 498 accounts, and 60 pages gave 1,492 unique followers on the larger one, with more still available.
  • Private accounts return 200 with an empty users list.

The response for nasa, trimmed. should_limit_list_of_followers: true with has_next_page: false means the list ended on this page:

json
{
  "data": {
    "users": [{ "id": "<id>", "username": "<redacted>", "full_name": "<redacted>", "is_private": false, "is_verified": false }],
    "page_size": 50,
    "big_list": false,
    "should_limit_list_of_followers": true,
    "has_more": false,
    "page_info": { "has_next_page": false, "end_cursor": null }
  }
}

What it costs

A call is 1 credit, and the run above cost 28. On an account that pages, 60 calls returned 1,492 followers, so 1,000 followers take about 40 credits. A big account that stops at one page returns at most 50 followers however many calls you make. You get 100 free credits a month; $19 buys 10,000 credits that never expire, and plans for higher volume cover more accounts. Set your key and the first list is a CSV in under a minute.

For posts and comments instead of followers, see our Instagram scraper in Python and Instagram comments to CSV.

We are not affiliated with Instagram.

Get this data from your own code

The Instagram API returns it as JSON with one x-api-key header. 100 free credits monthly.