Twitter mutual followers API & shared connections

{
  "users": [],
  "has_next_page": false,
  "next_cursor": ""
}

{
  "error": "invalid_input",
  "message": "Invalid input. Check the request body."
}

{
  "error": "unauthenticated",
  "message": "Authentication required. Provide a valid API key or bearer token."
}

{
  "error": "insufficient_credits",
  "message": "Insufficient credits. Top up or subscribe to continue."
}

{
  "error": "forbidden",
  "message": "This API key can access paid read endpoints only."
}

{
  "error": "x_api_unavailable",
  "message": "X data source temporarily unavailable. Try again later."
}

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Try again later.",
  "retryAfter": 60
}

{
  "error": "x_api_unavailable",
  "message": "X data source temporarily unavailable. Try again later."
}

{
  "error": "x_api_unavailable",
  "message": "Xquik is busy right now. Retry shortly."
}

GET

users

{id}

followers-you-know

Twitter mutual followers API & shared connections

curl --request GET \
  --url https://xquik.com/api/v1/x/users/{id}/followers-you-know \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://xquik.com/api/v1/x/users/{id}/followers-you-know', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://xquik.com/api/v1/x/users/{id}/followers-you-know"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "users": [
    {
      "id": "<string>",
      "username": "<string>",
      "name": "<string>",
      "description": "<string>",
      "followers": 123,
      "following": 123,
      "verified": true,
      "profilePicture": "<string>",
      "location": "<string>",
      "createdAt": "<string>",
      "statusesCount": 123,
      "coverPicture": "<string>",
      "mediaCount": 123,
      "url": "<string>",
      "favouritesCount": 123,
      "hasCustomTimelines": true,
      "isTranslator": true,
      "withheldInCountries": [
        "<string>"
      ],
      "possiblySensitive": true,
      "pinnedTweetIds": [
        "<string>"
      ],
      "isAutomated": true,
      "automatedBy": "<string>",
      "unavailable": true,
      "unavailableReason": "<string>",
      "verifiedType": "<string>",
      "profile_bio": {},
      "isBlueVerified": true,
      "isVerified": true,
      "profileBannerUrl": "<string>",
      "protected": true,
      "communityRole": "<string>"
    }
  ],
  "has_next_page": true,
  "next_cursor": "<string>"
}

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. 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

Get followers you know returns mutual followers between your connected X account and one target X user. The endpoint is GET /api/v1/x/users/{id}/followers-you-know.

curl https://xquik.com/api/v1/x/users/44196397/followers-you-know \
  -H "x-api-key: xq_your_api_key_here" | jq

curl -G https://xquik.com/api/v1/x/users/44196397/followers-you-know \
  --data-urlencode "cursor=abc123" \
  -H "x-api-key: xq_your_api_key_here" | jq

const userId = "44196397";
const response = await fetch(`https://xquik.com/api/v1/x/users/${userId}/followers-you-know`, {
  headers: { "x-api-key": "xq_your_api_key_here" },
});
const data = await response.json();
const mutualRows = data.users.map((user) => ({
  target_user_id: userId,
  x_user_id: user.id,
  username: user.username,
  display_name: user.name,
  follower_count: user.followers ?? null,
  verified: user.verified ?? false,
  verified_type: user.verifiedType ?? null,
  profile_image_url: user.profilePicture ?? null,
}));
const nextCursor = data.has_next_page ? data.next_cursor : null;
const checkpoint = { target_user_id: userId, next_cursor: nextCursor };

for (const row of mutualRows) {
  process.stdout.write(`${JSON.stringify(row)}\n`);
}
process.stdout.write(`${JSON.stringify(checkpoint)}\n`);

import json
import requests

user_id = "44196397"
response = requests.get(
    f"https://xquik.com/api/v1/x/users/{user_id}/followers-you-know",
    headers={"x-api-key": "xq_your_api_key_here"},
)
data = response.json()
mutual_rows = [
    {
        "target_user_id": user_id,
        "x_user_id": user["id"],
        "username": user["username"],
        "display_name": user["name"],
        "follower_count": user.get("followers"),
        "verified": user.get("verified", False),
        "verified_type": user.get("verifiedType"),
        "profile_image_url": user.get("profilePicture"),
    }
    for user in data["users"]
]
next_cursor = data["next_cursor"] if data["has_next_page"] else None
checkpoint = {"target_user_id": user_id, "next_cursor": next_cursor}

for row in mutual_rows:
    print(json.dumps(row))
print(json.dumps(checkpoint))

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

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 your connected X account 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 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.

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:

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

string

required

User ID, username with or without @, or URL-encoded profile URL, such as x.com/nasa. See path IDs.

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 your connected X account 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.

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 or 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 X flags the account as possibly sensitive. Omitted if unavailable.

string[]

IDs of pinned tweets. Omitted if none.

boolean

Whether X marks the account 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 (for example 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.

{
  "users": [
    {
      "id": "987654321",
      "username": "username",
      "name": "Xquik",
      "followers": 10000,
      "verified": true,
      "profilePicture": "https://pbs.twimg.com/profile_images/xquik/photo.jpg"
    }
  ],
  "has_next_page": true,
  "next_cursor": "DAADDAABCgABF..."
}

400 Invalid user ID

{ "error": "invalid_user_id" }

The user ID is empty or invalid.

401 Unauthenticated

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

{ "error": "x_api_unavailable" }

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

429 Rate limit exceeded

{ "error": "rate_limit_exceeded", "retryAfter": 60 }

You exceeded your tier rate limit. Wait for the Retry-After header before retrying.

424 Dependency failed

{ "error": "x_api_unavailable" }

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, Get followers, Get following, and Get verified followers.

{
  "users": [],
  "has_next_page": false,
  "next_cursor": ""
}

{
  "error": "invalid_input",
  "message": "Invalid input. Check the request body."
}

{
  "error": "unauthenticated",
  "message": "Authentication required. Provide a valid API key or bearer token."
}

{
  "error": "insufficient_credits",
  "message": "Insufficient credits. Top up or subscribe to continue."
}

{
  "error": "forbidden",
  "message": "This API key can access paid read endpoints only."
}

{
  "error": "x_api_unavailable",
  "message": "X data source temporarily unavailable. Try again later."
}

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Try again later.",
  "retryAfter": 60
}

{
  "error": "x_api_unavailable",
  "message": "X data source temporarily unavailable. Try again later."
}

{
  "error": "x_api_unavailable",
  "message": "Xquik is busy right now. Retry shortly."
}

Twitter mutual followers API & shared connections

curl --request GET \
  --url https://xquik.com/api/v1/x/users/{id}/followers-you-know \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://xquik.com/api/v1/x/users/{id}/followers-you-know', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://xquik.com/api/v1/x/users/{id}/followers-you-know"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "users": [
    {
      "id": "<string>",
      "username": "<string>",
      "name": "<string>",
      "description": "<string>",
      "followers": 123,
      "following": 123,
      "verified": true,
      "profilePicture": "<string>",
      "location": "<string>",
      "createdAt": "<string>",
      "statusesCount": 123,
      "coverPicture": "<string>",
      "mediaCount": 123,
      "url": "<string>",
      "favouritesCount": 123,
      "hasCustomTimelines": true,
      "isTranslator": true,
      "withheldInCountries": [
        "<string>"
      ],
      "possiblySensitive": true,
      "pinnedTweetIds": [
        "<string>"
      ],
      "isAutomated": true,
      "automatedBy": "<string>",
      "unavailable": true,
      "unavailableReason": "<string>",
      "verifiedType": "<string>",
      "profile_bio": {},
      "isBlueVerified": true,
      "isVerified": true,
      "profileBannerUrl": "<string>",
      "protected": true,
      "communityRole": "<string>"
    }
  ],
  "has_next_page": true,
  "next_cursor": "<string>"
}

​When to read mutual followers

​Direct mutual followers handoff

Mutual rows

Stable upserts

Warm-intro labels

Profile context

Priority signals

Approved contact

Next page

​Explain mutual follower context

​Build a mutual connection brief

​Prepare a warm-introduction review

​Compare mutual follower graph snapshots

​Path parameters

​Query parameters

​Which follower graph endpoint?

Mutual followers

All followers

Verified followers

DM handoff

​User result filters

​Headers

​Response

​200 OK

​400 Invalid user ID

​401 Unauthenticated

​402 Payment required

​502 X API unavailable

​429 Rate limit exceeded

​424 Dependency failed

When to read mutual followers

Direct mutual followers handoff

Explain mutual follower context

Build a mutual connection brief

Prepare a warm-introduction review

Compare mutual follower graph snapshots

Path parameters

Query parameters

Which follower graph endpoint?

User result filters

Headers

Response

200 OK

400 Invalid user ID

401 Unauthenticated

402 Payment required

502 X API unavailable

429 Rate limit exceeded

424 Dependency failed