TwitterAPIs Docs
API ReferenceFollower Graph

Twitter Followers API v2 | Richer Follower Data

The v2 variant of the followers endpoint. Same data, with a more consistent cursor model and additional user fields. Prefer v2 for new integrations. Cost: $0.0008 per call.

User Followers v2 is the upgraded followers endpoint: the same follower data with a more consistent cursor model and additional user fields such as created_at. Prefer it for new integrations. Page until the users array comes back empty, since the cursor stays non-null on the last page. Each page is one $0.0008 read.

GET
/user/followers_v2

Authorization

bearerAuth
AuthorizationBearer <token>

Pass your API key as a bearer token on every request: Authorization: Bearer <API_KEY>.

In: header

Query Parameters

username*string

Handle without the leading @.

user_id?string

Numeric user ID; provide either username or user_id.

cursor?string

Pagination cursor from a previous response.

count?integer

Max items to return for this page. Default 20; documented range 1-100. NOTE: on follower/following lists X returns pages in fixed chunks, so a small count may still return up to a full page (~100). Treat count as an upper-bound hint here, not an exact limit; paginate with the cursor for more.

fields?string

Comma-separated list of dotted field paths to keep in the response (one parameter, never repeated), applied to every object in the returned lists and to nested objects (for example fields=id,text,author.username; the list's own name may prefix a path, fields=tweets.id). A path prefix that lands on an array applies to each element (media.media_url_https). Pagination and envelope keys (next_cursor, cursor, has_more, count, partial, error, message, reason) are always kept. Unknown paths are ignored; up to 50 paths of up to 6 segments. Projection never changes status codes or billing, and applies to data reads only: account, feedback, session status, monitor (other than deliveries), webhook and stream-compat reads return their bodies unchanged.

compact?string

Set to 1 (or true) to apply the built-in compact preset: ids, url, text, created_at, lang, the engagement counts, the is_retweet/is_reply/is_quote flags, conversation ids, the author's id/username/name/followers_count/verification, and the quoted or retweeted tweet's id/url/author username. The preset trims what it recognises and leaves alone what it would empty, so it never turns a body into {}. Combine with fields to add paths on top of the preset. Typically cuts a tweet page by 70 to 90 percent for LLM tool callers.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/user/followers_v2?username=naval&user_id=44196397&count=20&fields=id%2Ctext%2Ccreated_at%2Cauthor.username&compact=1"
{  "users": [    {      "id": "9921",      "username": "devjane",      "name": "Jane",      "followers_count": 4200,      "verified": false,      "created_at": "Wed Jan 04 09:11:00 +0000 2023"    }  ],  "next_cursor": "DAABCgABF..."}
{  "error": "bad_request",  "message": "Missing or malformed parameter. Fix the request before retrying."}
{  "error": "unauthorized",  "message": "The API key is missing, malformed, or revoked. Check the Authorization header."}
{  "error": "insufficient_credits",  "message": "Your balance is exhausted. Top up your credits to continue.",  "top_up_url": "https://www.twitterapis.com/dashboard/buy-credits?utm_source=api&utm_medium=402"}
{  "error": "forbidden",  "message": "X refused this resource for the acting account: on a read, the account is not a participant in the DM thread, the target is protected or has blocked it, or the session was attestation-blocked for calling from a datacenter or rotating IP; on a write, the account is not authorized for the action or has no logged-in session. The credentials are still valid, so do not re-register."}
{  "error": "not_found",  "message": "The resource does not exist, for example a deleted tweet or a private account."}
{  "error": "rate_limited",  "message": "Too many requests. Back off and retry with exponential backoff."}
{  "error": "server_error",  "message": "Something failed on our side. Retry with backoff; if it persists, contact support."}

Pricing

UnitPrice
Per call$0.0008
Per 1,000 calls$0.80
Per 1,000 records (~20 per call)~$0.04

Each page is one $0.0008 read, so a large follower export costs one call per page. Budget big pulls and stop at the depth you need.

When to use

Use it for new follower-export builds, for example exporting followers when you also need each account's creation date.

Pagination

This endpoint is cursor-paginated and returns roughly 20 records per call. Pass the next_cursor from each response back as the cursor parameter to read the next page. Stop when the records array comes back empty: follower-graph endpoints return a non-null cursor even on the final page, so the empty array is the only reliable stop signal. See Pagination for the full loop.

FAQ

Why choose v2 over v1 followers?

v2 returns the same followers with a more consistent cursor model and extra user fields like created_at. It is the recommended choice for new builds.

Does v2 change how paging stops?

No. As with v1, the follower graph keeps a non-null cursor on the last page, so stop when the users array comes back empty.

Is v2 priced differently from v1?

No. Both are standard reads at $0.0008 per page. v2 simply returns richer fields for the same cost.

Was this page helpful?