Twitter Followers API: Pull Any Account's List for $0.016/1K

Every field the follower object returns

A follower record is a full user object, not a handle and an id. That matters because most of the work people do after an export, scoring accounts, filtering bots, segmenting by size or recency, needs profile fields that a thin response would force you to fetch separately at a second cost per row. The table below is the published schema, the same one the OpenAPI document describes, so you can size your database columns before writing a line of client code.

Three of those repay a second look. is_automated and automated_by come from X's own automated-account label, so a bot filter can start from a declared signal rather than a heuristic. unavailable with unavailable_reason is how a suspended or deleted account arrives, which is a state you want to record rather than silently drop, since it is the difference between an unfollow and a suspension. And created_at beside followers_count is the cheapest two-field plausibility check there is: an account made last week with 40,000 followers is worth a closer look.

Error responses, and what to do about each

Every error comes back as the same envelope, a machine-readable error code and a human message, so a client can branch on the code and log the message rather than parse prose. The distinction that matters in a paging loop is which of these you retry and which you must not.

The rule that keeps a long export honest: retry 429 and 5xx, never retry 400, 401 or 404. A client that retries everything turns a typo into a twenty-minute stall and still ends with the same error.

What a full follower export costs, by account size

A flat per-call rate makes this arithmetic rather than a quote. At roughly $0.012 to $0.016 per 1,000 follower records (the exact figure depends on where in the crawl a page falls, since the first page returns more records than later ones), the cost of an export is the follower count times that rate, and the wall clock is governed by the 600 requests a minute ceiling on a single key.

The third column is the one worth reading twice, because it is where most follower projects overspend. Re-pulling two million records every day is thirty times the cost of pulling them once, and for most questions it buys nothing: a follower list of that size does not change materially in 24 hours. Pull the full list on a weekly or monthly cadence, and track the daily delta through the account's followers_count, which is one cheap profile call rather than a full crawl. Only crawl in full when the count moved enough to be worth explaining.

Detecting new followers and unfollows with a set diff

X does not publish an unfollow event, and no third-party API can invent one. The only honest way to know who left is to hold two snapshots and subtract. That is straightforward, and it has exactly one trap worth naming: an account that was suspended, deactivated or went private looks identical to an unfollow in a naive diff, and telling them apart is why the unavailable field is in the response.

import requests

BASE = "https://api.twitterapis.com/twitter/user/followers_v2"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

def snapshot(username):
    """Full follower list as {id: user}. One billed call per page."""
    out, cursor = {}, ""
    while True:
        body = requests.get(BASE, headers=HEADERS, timeout=30,
                            params={"username": username,
                                    "cursor": cursor}).json()
        for u in body.get("users", []):
            out[u["id"]] = u
        # Follower-graph endpoints keep returning a non-null cursor
        # past the end, so has_more is the reliable stop signal.
        if not body.get("has_more"):
            break
        cursor = body.get("next_cursor", "")
    return out

today = snapshot("someaccount")
yesterday = load_previous_snapshot()

gained = today.keys() - yesterday.keys()
lost = yesterday.keys() - today.keys()

# Split the losses. An account X reports as unavailable did not
# unfollow you, it stopped existing, and counting it as churn
# makes a suspension wave look like a content problem.
suspended = {i for i in lost if yesterday[i].get("unavailable")}
real_unfollows = lost - suspended

Two operational notes for a diff job. Take both snapshots at roughly the same time of day, because a list crawled over two hours is a moving target and a large account will gain followers mid-crawl, showing up as phantom churn. And store the snapshot rather than only the diff: the second time someone asks a question about last quarter, a stored snapshot answers it for free and a stored diff does not.

Five things people get wrong reading a follower list

The endpoint is simple. The conclusions drawn from it are where the errors live, and none of these surface as a failure: the pipeline stays green and the number is quietly wrong, which is why they survive so long.

• Treating the follower count and the crawl total as the same number. They rarely match exactly. The count on a profile is X's own aggregate at that instant, while a crawl is a walk over pages taken across minutes, during which the list moves. A small gap is normal and is not evidence of missing data.
• Reading follower order as recency. The order pages come back in is the platform's, and it is not a documented chronological sort. If you need to know who followed recently, the answer is a diff between two snapshots, not the top of page one.
• Quoting an engagement rate off a raw follower total. A follower list contains inactive accounts, automated accounts and accounts X has since suspended. The response already carries the fields to filter them, the automated-account label, the default-avatar flag, the follower-to-following ratio, the tweet count and account age, so a filtered denominator is a filter over data you have rather than a second integration.
• Comparing two accounts' lists without normalising for size. Overlap between a 2,000-follower account and a 2,000,000-follower account is dominated by the larger one. If the question is affinity rather than reach, use a proportion of the smaller audience, not a raw intersection count.
• Assuming a handle is a stable identity. Handles change. An account that renamed itself reads as one departure plus one arrival in any diff keyed on the username, which manufactures churn that never happened. Key on the numeric id and treat the handle as a display field that happens to be searchable.

The habit that catches most of these is recording provenance beside every number: what was crawled, when it started, when it finished, and which filters were applied to the denominator. A figure without those four is not reproducible next quarter, which is usually when somebody asks.

Rate limits, concurrency, and how long a crawl takes

One key carries 600 requests a minute. That number is the whole capacity plan, and it is worth converting into wall clock before you schedule anything, because the answer decides whether a job is a cron entry or a queue with checkpoints.

600 requests a minute is 36,000 calls an hour on a single key. Converting that into followers depends on how many records a page returns, which X varies, so the honest way to plan is to divide your target by the page size you actually observe on your first run rather than by a number we quote. On the roughly $0.012 to $0.016 per 1,000 basis this page prices against, 36,000 calls an hour is roughly 1.8 to 2.6 million records, so a 50,000-follower account is a couple of minutes, half a million is a quarter of an hour or so, and two million is a little over an hour. That last one is the point where a crawl stops being instantaneous relative to the thing it measures: the list changes while you read it, so treat the result as a reading taken over a window rather than a state at an instant, and record the start and end times with the snapshot.

Two practical notes. Run fewer workers than the ceiling allows, not more: a client that sits at 600 spends its time being rate limited and backing off, and the effective throughput of a job that trips 429 constantly is lower than one pacing itself at 80 percent. And pagination is sequential by construction, because each page needs the cursor from the one before it, so concurrency comes from crawling several accounts at once rather than from parallelising a single list.

Checkpoint the cursor. If a two-million-record crawl dies forty minutes in, resuming from the last successful cursor costs a few calls, and restarting costs forty minutes and the credits already spent. Failed calls are not billed, but successful ones you throw away are.

Storing follower snapshots without the table exploding

The API side of follower work is a loop. The part that usually goes wrong is what happens after, because the obvious design, one row per follower per snapshot, turns a 500,000-follower account tracked daily into 15 million rows a month, almost all of them identical to the row before.

The shape that holds up is two tables. One holds the account itself, keyed on the numeric id as text or bigint, carrying the profile fields and a last_seen timestamp, updated on each crawl. The other holds membership as intervals rather than snapshots: one row per follow relationship with a first_seen and a nullable last_seen, closed off when the account stops appearing. That answers who followed us in March, who left in June, and who has been here the whole time, all without storing a row per day.

Three details that cause real bugs. Store ids as text or bigint and never as a float or a JavaScript number, because X ids exceed the safe integer range and rounding two accounts onto the same key is a silent corruption rather than an error. Never key on the handle, because handles change and the same person then reads as one departure plus one arrival. And record unavailable when it comes back true rather than deleting the row, or a suspension wave shows up in your dashboard as a churn spike caused by something you did.

On volume: profile fields change far more slowly than membership does. Re-writing a full profile row on every crawl is mostly write amplification. Compare a hash of the fields you care about and update only when it moves, and the storage cost of tracking a large account drops by an order of magnitude.

Followers API, common questions