Relationships
Twitter mutual followers API & shared connections
Retrieve mutual X followers between the authenticated context and one target user for warm-intro, CRM, scoring, and agent workflows. See request fields.
- 200
- 400
- 401
- 402
- 424
- 429
- 502
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.next_cursor without duplicating already
imported profiles.
Direct mutual followers handoff
UseGET /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.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.
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 namefollowers-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.
Whether the account is unavailable. Omitted if available.
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
401 Unauthenticated
Anonymous requests getWWW-Authenticate: Bearer and a guest wallet checkout action. This is not a Payment challenge.
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
429 Rate limit exceeded
Retry-After header before retrying.
424 Dependency failed
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.- 200
- 400
- 401
- 402
- 424
- 429
- 502
Twitter mutual followers API & shared connections