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.
Authorization
bearerAuth Pass your API key as a bearer token on every request: Authorization: Bearer <API_KEY>.
In: header
Query Parameters
Handle without the leading @.
Numeric user ID; provide either username or user_id.
Pagination cursor from a previous response.
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.
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.
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
| Unit | Price |
|---|---|
| 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.
Related endpoints
- User Followers: Page through the accounts that follow a user.
- User Following (v2): Following endpoint with the v2 response shape and richer cursoring.
- Verified Followers: Page through only the verified accounts that follow a user.
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.
User Following GET
Fetch the accounts a user follows, cursor-paginated. Returns full user objects. Page with next_cursor until the users array comes back empty (the follower graph keeps returning a non-null cursor even on the final page). Cost: $0.0008 per call.
User Following (v2) GETNew
The v2 variant of the following endpoint. Same data as the v1 following call, with a more consistent cursor model and additional user fields. Prefer v2 for new integrations. Cost: $0.0008 per call.