Skip to main content
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 get 424 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 followers you know returns mutual followers. They follow both your connected X account and one target X user. The endpoint is GET /api/v1/x/users/{id}/followers-you-know.
The Node.js and Python snippets build mutual follower rows. They do not print the full response page. Store the rows with the checkpoint. A worker can then resume pagination with next_cursor without duplicating imported profiles.

Direct mutual followers handoff

For one JSON page of a target user’s mutual followers, use GET /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.
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 these uses.
  • 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 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 name followers-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 are minFollowers, 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 the Retry-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 returns 424 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." }