Getting a user's followers from the X API

The call

A handle in, a page of followers out. No app review, no OAuth dance, no elevated access tier. An API key and a GET.

curl -H "Authorization: Bearer $SOCIALPIPE_KEY" \
  "https://api.socialpipe.dev/v1/twitter/web/fetch_user_followers?screen_name=jack"

What comes back is X's own JSON, with nothing renamed and nothing added. Trimmed here to one follower and the fields you are most likely to read:

{
  "followers_count": null,
  "followers": [
    {
      "user_id": "1337780902680809474",
      "screen_name": "DocumentingBTC",
      "name": "Documenting ₿itcoin 📄",
      "followers_count": 1124871,
      "created_at": "Sat Dec 12 15:26:42 +0000 2020",
      "blue_verified": true
    }
  ],
  "next_cursor": "1795069038947442688|1337780902680809474"
}

Pass next_cursor back as cursor to walk further. Each page is one call and one credit, so the cost of a full audience is the number of pages, not the number of accounts. A cached read inside its window and a call that returns nothing both cost zero.

Note followers_count at the top level can be null, because it is the platform's field and we do not substitute a computed one. The per-account followers_count inside each record is the reliable one. If you want the subject's own totals, the profile endpoint is the honest place to read them.

What you may keep, which is the part most pages skip

This response is personal data about people who are neither our customers nor yours: handles, display names, bios, profile images. Section 5 of our terms draws a line through the middle of it, and it is a line we would rather you hit now than after you have shipped.

• Allowed: aggregate measurement. Counting a page, measuring how an audience is made up, tracking how a follower count moves, comparing one account's audience shape against another's.
• Not allowed: keeping the people. Retaining the individuals as a list, assembling a social graph about identified people, or building anything whose purpose is to profile, rank or score them.

Plainly: this endpoint is for measuring an audience, not for exporting one. If you need a list of people to contact, we are not the right supplier, and saying so here is cheaper for both of us than saying it after you have written the integration.

The related endpoints

Three routes answer follower-shaped questions, and which one you want depends on whose audience you are asking about.

• fetch_user_followers returns the accounts following a handle. The call above.
• fetch_user_followings goes the other direction: who that handle follows.
• fetch_list_followers returns the subscribers of an X list rather than of an account.

A fourth is worth knowing about because it answers the question without returning anybody: fetch_check_follow tells you whether one account follows another. If that is all you need, it is a smaller answer and it keeps no people.