GET https://xquik.com/api/v1/x/users/{id}/followers-you-know
When to read mutual followers
Use this route for mutual followers your connected X account can see. It supports warm introductions, CRM scoring, and pre-message checks. Use profile lookup when mutual relationship rows are unnecessary. The route reads through your connected X account. Callers without a connected X account get424 account_required. Use Connect X account to add one. Guest keys get 403 forbidden. When your connected X accounts are busy, the route returns 503. Retry after the Retry-After delay.Requested result counts are upper bounds for paid authenticated calls. Remaining credits may not cover the full page or ID list. If so, 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
GET /api/v1/x/users/{id}/followers-you-know.next_cursor without duplicating
imported profiles.Direct mutual followers handoff
For one JSON page of a target user’s mutual followers, useGET /x/users/{id}/followers-you-know. It suits sales, community, recruiting, support, CRM, or agent workflows. It returns people who follow both your connected X account and the target user. The path id is the target numeric X (Twitter) user ID.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 deduplication.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. The write response tells you whether X delivered the DM.
Next page
Store
has_next_page and next_cursor. Then 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 these uses.- 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 your own 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. A mutual follower and a verified follower are different facts.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. With these fields, reviewers can identify the shared connection. Do not rank profiles from follower count alone. Review biography, location, recent profile context, and the purpose of the outreach. 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, keep 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. Keep the original snapshot for review evidence.Compare mutual follower graph snapshots
Complete every cursor page before comparing 2 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. Username and profile changes are attribute changes. The user ID still identifies the same relationship. 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. An audience
warehouse can then keep the 3 relationship types apart.
When the target changes, create a new comparison group. Never reuse cursors or
relationship labels across different target user IDs.Path parameters
Query parameters
Choose fields
Which follower graph endpoint?
Mutual followers
Use
GET /x/users/{id}/followers-you-know for people who follow both your
connected X account and the target.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.See user filters for every filter. Common ones areminFollowers, verifiedOnly, hasWebsite, hasEmail, bioContains, and locationContains.Headers
Response
200 OK
400 Invalid user ID
{ "error": "invalid_user_id" }
The user ID is empty or invalid.401 Unauthenticated
Missing or invalid API key.402 Payment required
Account keys get account options. 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
You exceeded your tier rate limit. Wait for theRetry-After header before retrying.424 Dependency failed
The normalized v1 response contract can return 424 when the read service is unavailable. Without a connected X account, the route returns424 account_required. Connect one, then retry.
{ "error": "account_required", "message": "This read needs your own connected X account. Connect or restore it at dashboard.xquik.com/account, then retry." }Related. Direct message workflow for user-approved outreach. Send DM to send and store
messageId. DM history to read participant-scoped context. See also Get followers, Get following, and Get verified followers.Response examples
- 400
{ "error": "invalid_input", "message": "Invalid input. Check the request body." } - 401
{ "error": "unauthenticated", "message": "Authentication required. Provide a valid API key or bearer token." } - 402
{ "error": "insufficient_credits", "message": "Insufficient credits. Top up or subscribe to continue." } - 403
{ "error": "api_key_paused", "message": "This API key is paused. Resume it at dashboard.xquik.com/api-keys to use it again." } - 424
{ "error": "x_api_unavailable", "message": "X data source temporarily unavailable. Try again later." } - 429
{ "error": "rate_limit_exceeded", "message": "Too many requests. Try again later.", "retryAfter": 60 } - 502
{ "error": "x_api_unavailable", "message": "X data source temporarily unavailable. Try again later." } - 503
{ "error": "x_api_unavailable", "message": "Xquik is busy right now. Retry shortly." }