Skip to main content
GET
Twitter mutual followers API & shared connections

Choose mutual followers

Use this route for mutual followers in the authenticated context. It supports warm introductions, CRM scoring, and pre-message checks. Use profile lookup when mutual relationship rows are unnecessary.
Requested result counts are upper bounds for paid authenticated calls. When remaining credits cannot cover the full page or ID list, Xquik returns fewer results. If zero paid results are affordable, it returns 402 insufficient_credits.
1 credit per result returned · All plans from $0.00012/credit · Supports guest paid reads
Get followers you know returns mutual followers between the authenticated context and one target X user. It is also useful as a mutual followers API, followers you know API, X mutual followers API, or Twitter mutual followers API. The canonical endpoint remains GET /api/v1/x/users/{id}/followers-you-know.
The Node.js and Python snippets shape durable mutual follower rows instead of printing the full response page. Persist the rows with the checkpoint so a worker can resume pagination with next_cursor without duplicating already imported profiles.

Direct mutual followers handoff

Use GET /x/users/{id}/followers-you-know when a sales, community, recruiting, support, CRM, or agent workflow needs one JSON page of mutual followers for a target user. The path id is the target numeric X user ID. The endpoint returns people who follow both the authenticated context and the target user.

Mutual rows

Store users[] as the mutual follower profile rows returned on this page.

Stable upserts

Store users[].id as x_user_id for CRM, warehouse, scoring, and agent dedupe.

Warm-intro labels

Store users[].username and users[].name for handles, owner review, routing, and handoff labels.

Profile context

Store users[].description, location, url, profilePicture, and coverPicture when returned.

Priority signals

Store users[].followers, users[].following, verified, and verifiedType for scoring and queue priority.

Approved contact

Use DM endpoints only after a user-approved message flow. Treat the write response as the delivery authority.

Next page

Store has_next_page and next_cursor; pass next_cursor back as cursor only when has_next_page is true.
Direct mutual followers cost 1 credit per user returned. Low credit balances can return fewer users than a full page; zero affordable results return 402 insufficient_credits.

Explain mutual follower context

Use this route to find profiles that connect the acting account with another profile. Keep both account identities with every returned user. Mutual-follower rows can support:
  • Relationship context during account review.
  • Introductions through already known profiles.
  • Trust research around a public conversation.
  • CRM notes tied to shared followers.
Store user ID, username, profile name, verification state, and follower counts. Also store the target profile ID and acting account. Do not describe a mutual follower as an endorsement. The route reports a public relationship, not intent. Avoid inferring consent, employment, or affiliation. Paginate by cursor and deduplicate by user ID. Keep a collection timestamp because follow relationships can change.

Build a mutual connection brief

Keep the target user ID with every mutual follower result. Store each user ID, username, profile summary, and biography. Add verification state, follower count, request time, and cursor. Rank mutual followers for the downstream review. The API does not declare endorsement, relationship strength, or personal familiarity. Refresh the target profile before a time-sensitive decision. Use stable user IDs when usernames change. Do not merge these results with verified followers without a source column. Mutual context and verification answer different questions.

Prepare a warm-introduction review

Begin with the acting account and target account. Store both stable user IDs. Every returned profile belongs to the mutual-follower context between them. Keep each mutual follower’s stable user ID, username, and profile name. Add biography, location, verification, and audience counts. Add the page cursor and collection time. These fields let reviewers identify the shared connection. Do not rank profiles from follower count alone. Review biography, location, recent profile context, and the downstream purpose. Record the chosen priority outside returned API fields. Never describe a mutual follower as an introduction, endorsement, or consent. The route reports a public relationship. A person must approve any outreach or introduction step. When a reviewer approves outreach, preserve the mutual-follower snapshot. Link the later message result through stable user IDs. Keep message content and delivery state outside the relationship row. Refresh time-sensitive profiles before contacting anyone. Usernames, bios, verification, and audience counts can change. Preserve the original snapshot for review evidence.

Compare mutual follower graph snapshots

Complete every cursor page before comparing two runs. Mark a capped, credit-bounded, failed, or interrupted run as partial. Exclude partial runs from complete graph-change claims. Use acting account ID, target account ID, and mutual user ID as the key. Report newly observed and missing mutual profiles separately. Do not infer why a relationship changed. Treat username and profile changes as attributes. Stable user IDs preserve the relationship identity. Record each snapshot’s collection time and page count. Keep mutual followers separate from all followers and verified followers. A source column should name followers-you-know. This prevents an audience warehouse from mixing distinct relationship questions. When the target changes, create a new comparison group. Never reuse cursors or relationship labels across different target user IDs.

Path parameters

string
required
Target X user ID as a numeric string. Use Get user first if you only have a username.

Query parameters

string
Pagination cursor from next_cursor in a previous response. Omit for the first page. Pass a cursor only when has_next_page is true.
integer
Profiles per page. Range: 20-200. Defaults to 200.

Which follower graph endpoint?

Mutual followers

Use GET /x/users/{id}/followers-you-know for people who follow both the authenticated context and the target user.

All followers

Use GET /x/users/{id}/followers for all followers of one target profile.

Verified followers

Use GET /x/users/{id}/verified-followers when you only need verified followers of the target profile.

DM handoff

Use Send DM only after your workflow has a user-approved outreach step.

User result filters

These filters apply before billing. Selective filters can return fewer rows.
integer
Require this minimum follower count. Filtering happens before billing.
integer
Allow this maximum follower count. Missing counts pass this filter.
integer
Require this minimum following count.
integer
Allow this maximum following count. Missing counts pass this filter.
integer
Require this minimum post count.
integer
Allow this maximum post count. Missing counts pass this filter.
integer
Require this minimum account age in days.
boolean
When true, only return verified profiles.
string
Match the exact verification type.
boolean
When true, require a profile website.
boolean
When true, require a profile location.
string
Require every comma-separated or line-separated bio term.
string
Require this text in the profile location.
string
Require this text in the username.

Headers

string
Full account key. Sessions and OAuth also work.
string
Bearer xq_your_guest_key_here for paid_reads.

Response

200 OK

object[]
Array of mutual follower profiles. User object fields.
string
User ID.
string
X username.
string
Display name.
string
Profile bio. Omitted if empty.
number
Follower count. Omitted if unavailable.
number
Following count. Omitted if unavailable.
boolean
Whether the user is verified. Omitted if unavailable.
string
Profile picture URL. Omitted if unavailable.
string
Profile location. Omitted if empty.
string
ISO 8601 account creation timestamp. Omitted if unavailable.
number
Total number of tweets posted. Omitted if unavailable.
string
Cover/banner image URL. Omitted if unavailable.
number
Total number of media tweets posted. Omitted if unavailable.
string
Website URL from profile. Omitted if empty.
number
Total number of tweets liked. Omitted if unavailable.
boolean
Whether the user has custom timelines. Omitted if unavailable.
boolean
Whether the user is an X translator. Omitted if unavailable.
string[]
Country codes where the account is withheld. Omitted if empty.
boolean
Whether the account is flagged as possibly sensitive. Omitted if unavailable.
string[]
IDs of pinned tweets. Omitted if none.
boolean
Whether the account is marked as automated. Omitted if unavailable.
string
Username of the account operator if automated. Omitted if not automated.
boolean
Whether the account is unavailable. Omitted if available.
string
Reason the account is unavailable. Omitted if available.
string
Verification type (e.g. Business, Government). Omitted if not verified or standard blue check.
object
Structured profile bio with entity annotations. Omitted if unavailable.
boolean
Whether the account has X Premium verification. Omitted if unavailable.
boolean
Normalized verification status. Omitted if unavailable.
string
Profile banner URL. Omitted if unavailable.
boolean
Whether the account protects its posts. Omitted if unavailable.
string
Role within the requested community context. Omitted outside community results.
boolean
Whether more results are available.
string
Opaque cursor for the next page. Empty string when no more results.

400 Invalid user ID

The user ID is empty or invalid.

401 Unauthenticated

Anonymous requests get WWW-Authenticate: Bearer and a guest wallet checkout action. This is not a Payment challenge.
Missing or invalid API key.

402 Payment required

Account keys get account options; guest keys get guest top-up only. No checkout starts automatically. Confirm any payment action.

502 X API unavailable

The read service returned an error. Retry after a short delay.

429 Rate limit exceeded

Your tier rate limit was exceeded. Wait for the Retry-After header before retrying.

424 Dependency failed

The normalized v1 response contract can return 424 when the read service is unavailable.
Related. Direct message workflow for user-approved outreach, Send DM to send and store messageId, DM history to read participant-scoped context, Get followers, Get following, and Get verified followers.