Followers You Know API

GET user/followers_you_know returns the followers of a target account, identified by user_id, that the authenticated caller's own account also follows. It surfaces the mutual-connection overlap between the caller and the target, returning full user objects with cursor-based pagination via next_cursor and has_more.

curl -X GET "https://example.com/user/followers_you_know?user_id=44196397&fields=id%2Ctext%2Ccreated_at%2Cauthor.username&compact=1"

{  "count": 1,  "next_cursor": "1353384573435056128|2071116068906074107",  "users": [    {      "id": "1353384573435056128",      "username": "cryptorover",      "name": "Crypto Rover",      "description": "#Bitcoin Crypto YouTuber",      "followers_count": 1596989,      "following_count": 555,      "verified": true,      "tweet_count": 70185,      "location": "Bitcoin",      "created_at": "Sun Jan 24 16:50:08 +0000 2021",      "profile_image_url": "https://pbs.twimg.com/profile_images/1891433835675475969/J-TloTb6_normal.png"    }  ]}

{  "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."}

{  "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

When to use

Use this endpoint when you need the intersection of a target account's followers with the accounts your own registered session follows, for example to show "people you both follow" on a profile. Reach for the plain Followers or Following endpoints instead when you need a target account's full follower or following list with no filtering against your own session.

Notes

• Needs a registered session for the account you are reading (POST /customer/session). This endpoint does not accept per-call inline credentials: x-auth-token and x-ct0 headers are ignored here. Returns 409 session_required if no session is registered, 401 session_dead when the session has expired.
• Like the other follower-graph endpoints, next_cursor can stay non-null on the final page; stop when the users array is empty.

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: Page through the accounts a user follows.

FAQ

How is this different from the regular Followers or Following endpoints in the Follower Graph category?

Followers or Following returns every follower or followed account of a single user with no filtering. This endpoint intersects two sets: the followers of user_id and the accounts your registered session follows. Use it only when you need the overlap, not the full follower list.

How do I know if there are more results, and what does each page cost?

Check has_more in the response; if true, pass the value from next_cursor as the cursor parameter on your next request. Each call costs $0.0008 regardless of how many users are returned, and count (default 20) controls page size, so fewer, larger pages reduce total cost for a full walk.