> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xquik.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Twitter mutual followers API & shared connections

> Retrieve mutual X followers between your connected X account and one target user for warm-intro, CRM, scoring, and agent workflows. 1 credit per result.

<Panel>
  <Tabs defaultTabIndex={0} sync={false}>
    <Tab title="200" id="response-x-followers-you-know-200">
      ```json theme={null}
      {
        "users": [],
        "has_next_page": false,
        "next_cursor": ""
      }
      ```
    </Tab>

    <Tab title="400" id="response-x-followers-you-know-400">
      ```json theme={null}
      {
        "error": "invalid_input",
        "message": "Invalid input. Check the request body."
      }
      ```
    </Tab>

    <Tab title="401" id="response-x-followers-you-know-401">
      ```json theme={null}
      {
        "error": "unauthenticated",
        "message": "Authentication required. Provide a valid API key or bearer token."
      }
      ```
    </Tab>

    <Tab title="402" id="response-x-followers-you-know-402">
      ```json theme={null}
      {
        "error": "insufficient_credits",
        "message": "Insufficient credits. Top up or subscribe to continue."
      }
      ```
    </Tab>

    <Tab title="403" id="response-x-followers-you-know-403">
      ```json theme={null}
      {
        "error": "forbidden",
        "message": "This API key can access paid read endpoints only."
      }
      ```
    </Tab>

    <Tab title="424" id="response-x-followers-you-know-424">
      ```json theme={null}
      {
        "error": "x_api_unavailable",
        "message": "X data source temporarily unavailable. Try again later."
      }
      ```
    </Tab>

    <Tab title="429" id="response-x-followers-you-know-429">
      ```json theme={null}
      {
        "error": "rate_limit_exceeded",
        "message": "Too many requests. Try again later.",
        "retryAfter": 60
      }
      ```
    </Tab>

    <Tab title="502" id="response-x-followers-you-know-502">
      ```json theme={null}
      {
        "error": "x_api_unavailable",
        "message": "X data source temporarily unavailable. Try again later."
      }
      ```
    </Tab>

    <Tab title="503" id="response-x-followers-you-know-503">
      ```json theme={null}
      {
        "error": "x_api_unavailable",
        "message": "Xquik is busy right now. Retry shortly."
      }
      ```
    </Tab>
  </Tabs>
</Panel>

<blockquote className="agent-llms-directive">
  For the complete documentation index, see <a href="/llms.txt">llms.txt</a>.
</blockquote>

## 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](/api-reference/x-accounts/connect) 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.

<Note>
  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`.
</Note>

<Callout icon="coins" color="#5c3327">
  **1 credit per result returned** · [All plans](https://xquik.com/#pricing) from \$0.00012/credit
</Callout>

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

<CodeGroup>
  ```bash First page theme={null}
  curl https://xquik.com/api/v1/x/users/44196397/followers-you-know \
    -H "x-api-key: xq_your_api_key_here" | jq
  ```

  ```bash Next page theme={null}
  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
  ```

  ```javascript Node.js theme={null}
  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`);
  ```

  ```python Python theme={null}
  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))
  ```
</CodeGroup>

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.

<CardGroup cols={2}>
  <Card title="Mutual rows" icon="users-round">
    Store `users[]` as the mutual follower profile rows returned on this page.
  </Card>

  <Card title="Stable upserts" icon="key-round">
    Store `users[].id` as `x_user_id` for CRM, warehouse, scoring, and agent deduplication.
  </Card>

  <Card title="Warm-intro labels" icon="badge">
    Store `users[].username` and `users[].name` for handles, owner review, routing, and handoff labels.
  </Card>

  <Card title="Profile context" icon="file-text">
    Store `users[].description`, `location`, `url`, `profilePicture`, and `coverPicture` when returned.
  </Card>

  <Card title="Priority signals" icon="chart-no-axes-combined">
    Store `users[].followers`, `users[].following`, `verified`, and `verifiedType` for scoring and queue priority.
  </Card>

  <Card title="Approved contact" icon="message-square">
    Use DM endpoints only after a user-approved message flow. The write response tells you whether X delivered the DM.
  </Card>

  <Card title="Next page" icon="arrow-right">
    Store `has_next_page` and `next_cursor`, then pass `next_cursor` back as `cursor` only when `has_next_page` is true.
  </Card>
</CardGroup>

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

<ParamField path="id" type="string" required>
  User ID, username with or without `@`, or URL-encoded profile URL, such as
  `x.com/nasa`. See [path IDs](/api-reference/overview#path-ids).
</ParamField>

## Query parameters

<ParamField query="cursor" type="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.
</ParamField>

<ParamField query="pageSize" type="integer">
  Profiles per page. Range: `20-200`. Defaults to `200`.
</ParamField>

## Which follower graph endpoint?

<CardGroup cols={2}>
  <Card title="Mutual followers" icon="users-round">
    Use `GET /x/users/{id}/followers-you-know` for people who follow both your
    connected X account and the target user.
  </Card>

  <Card title="All followers" icon="list-tree">
    Use [`GET /x/users/{id}/followers`](/api-reference/x/followers) for all
    followers of one target profile.
  </Card>

  <Card title="Verified followers" icon="badge-check">
    Use [`GET /x/users/{id}/verified-followers`](/api-reference/x/verified-followers)
    when you only need verified followers of the target profile.
  </Card>

  <Card title="DM handoff" icon="message-square">
    Use [`Send DM`](/api-reference/x-write/send-dm) only after your workflow has
    a user-approved outreach step.
  </Card>
</CardGroup>

### User result filters

These filters apply before billing. Selective filters can return fewer rows.

<ParamField query="minFollowers" type="integer">
  Require this minimum follower count. Filtering happens before billing.
</ParamField>

<ParamField query="maxFollowers" type="integer">
  Allow this maximum follower count. Missing counts pass this filter.
</ParamField>

<ParamField query="minFollowing" type="integer">
  Require this minimum following count.
</ParamField>

<ParamField query="maxFollowing" type="integer">
  Allow this maximum following count. Missing counts pass this filter.
</ParamField>

<ParamField query="minStatuses" type="integer">
  Require this minimum post count.
</ParamField>

<ParamField query="maxStatuses" type="integer">
  Allow this maximum post count. Missing counts pass this filter.
</ParamField>

<ParamField query="minAccountAgeDays" type="integer">
  Require this minimum account age in days.
</ParamField>

<ParamField query="verifiedOnly" type="boolean">
  When `true`, only return verified profiles.
</ParamField>

<ParamField query="verifiedType" type="string">
  Match the exact verification type.
</ParamField>

<ParamField query="hasWebsite" type="boolean">
  When `true`, require a profile website.
</ParamField>

<ParamField query="hasLocation" type="boolean">
  When `true`, require a profile location.
</ParamField>

<ParamField query="bioContains" type="string">
  Require every comma-separated or line-separated bio term.
</ParamField>

<ParamField query="locationContains" type="string">
  Require this text in the profile location.
</ParamField>

<ParamField query="usernameContains" type="string">
  Require this text in the username.
</ParamField>

## Headers

<ParamField header="x-api-key" type="string">
  Full account key. Sessions and OAuth also work.
</ParamField>

## Response

### 200 OK

<ResponseField name="users" type="object[]">
  Array of mutual follower profiles.
  **User object fields.**

  <ResponseField name="id" type="string">
    User ID.
  </ResponseField>

  <ResponseField name="username" type="string">
    X username.
  </ResponseField>

  <ResponseField name="name" type="string">
    Display name.
  </ResponseField>

  <ResponseField name="description" type="string">
    Profile bio. Omitted if empty.
  </ResponseField>

  <ResponseField name="followers" type="number">
    Follower count. Omitted if unavailable.
  </ResponseField>

  <ResponseField name="following" type="number">
    Following count. Omitted if unavailable.
  </ResponseField>

  <ResponseField name="verified" type="boolean">
    Whether the user is verified. Omitted if unavailable.
  </ResponseField>

  <ResponseField name="profilePicture" type="string">
    Profile picture URL. Omitted if unavailable.
  </ResponseField>

  <ResponseField name="location" type="string">
    Profile location. Omitted if empty.
  </ResponseField>

  <ResponseField name="createdAt" type="string">
    ISO 8601 account creation timestamp. Omitted if unavailable.
  </ResponseField>

  <ResponseField name="statusesCount" type="number">
    Total number of tweets posted. Omitted if unavailable.
  </ResponseField>

  <ResponseField name="coverPicture" type="string">
    Cover or banner image URL. Omitted if unavailable.
  </ResponseField>

  <ResponseField name="mediaCount" type="number">
    Total number of media tweets posted. Omitted if unavailable.
  </ResponseField>

  <ResponseField name="url" type="string">
    Website URL from profile. Omitted if empty.
  </ResponseField>

  <ResponseField name="favouritesCount" type="number">
    Total number of tweets liked. Omitted if unavailable.
  </ResponseField>

  <ResponseField name="hasCustomTimelines" type="boolean">
    Whether the user has custom timelines. Omitted if unavailable.
  </ResponseField>

  <ResponseField name="isTranslator" type="boolean">
    Whether the user is an X translator. Omitted if unavailable.
  </ResponseField>

  <ResponseField name="withheldInCountries" type="string[]">
    Country codes where the account is withheld. Omitted if empty.
  </ResponseField>

  <ResponseField name="possiblySensitive" type="boolean">
    Whether X flags the account as possibly sensitive. Omitted if unavailable.
  </ResponseField>

  <ResponseField name="pinnedTweetIds" type="string[]">
    IDs of pinned tweets. Omitted if none.
  </ResponseField>

  <ResponseField name="isAutomated" type="boolean">
    Whether X marks the account as automated. Omitted if unavailable.
  </ResponseField>

  <ResponseField name="automatedBy" type="string">
    Username of the account operator if automated. Omitted if not automated.
  </ResponseField>

  <ResponseField name="unavailable" type="boolean">
    Whether the account is unavailable. Omitted if available.
  </ResponseField>

  <ResponseField name="unavailableReason" type="string">
    Reason the account is unavailable. Omitted if available.
  </ResponseField>

  <ResponseField name="verifiedType" type="string">
    Verification type (for example `Business`, `Government`). Omitted if not verified or standard blue
    check.
  </ResponseField>

  <ResponseField name="profile_bio" type="object">
    Structured profile bio with entity annotations. Omitted if unavailable.
  </ResponseField>

  <ResponseField name="isBlueVerified" type="boolean">
    Whether the account has X Premium verification. Omitted if unavailable.
  </ResponseField>

  <ResponseField name="isVerified" type="boolean">
    Normalized verification status. Omitted if unavailable.
  </ResponseField>

  <ResponseField name="profileBannerUrl" type="string">
    Profile banner URL. Omitted if unavailable.
  </ResponseField>

  <ResponseField name="protected" type="boolean">
    Whether the account protects its posts. Omitted if unavailable.
  </ResponseField>

  <ResponseField name="communityRole" type="string">
    Role within the requested community context. Omitted outside community results.
  </ResponseField>
</ResponseField>

<ResponseField name="has_next_page" type="boolean">
  Whether more results are available.
</ResponseField>

<ResponseField name="next_cursor" type="string">
  Opaque cursor for the next page. Empty string when no more results.
</ResponseField>

```json theme={null}
{
  "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

```json theme={null}
{ "error": "invalid_user_id" }
```

The user ID is empty or invalid.

### 401 Unauthenticated

```json theme={null}
{ "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

```json theme={null}
{ "error": "x_api_unavailable" }
```

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

### 429 Rate limit exceeded

```json theme={null}
{ "error": "rate_limit_exceeded", "retryAfter": 60 }
```

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

### 424 Dependency failed

```json theme={null}
{ "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.

```json theme={null}
{
  "error": "account_required",
  "message": "This read needs your own connected X account. Connect or restore it at dashboard.xquik.com/account, then retry."
}
```

<Note>
  **Related.** [Direct message workflow](/guides/direct-message-workflow) for user-approved outreach, [Send DM](/api-reference/x-write/send-dm) to send and store `messageId`, [DM history](/api-reference/x/dm-history) to read participant-scoped context, [Get followers](/api-reference/x/followers), [Get following](/api-reference/x/following), and [Get verified followers](/api-reference/x/verified-followers).
</Note>

<div className="related-api-links">
  <Accordion title="Related follower, list & community APIs" icon="link">
    * Profiles: [Search users](/api-reference/x/search-users) · [Search autocomplete](/api-reference/x/search-autocomplete) · [Get user](/api-reference/x/twitter-profile-lookup) · [Batch users](/api-reference/x/batch-users)
    * Followers: [Followers](/api-reference/x/followers) · [Following](/api-reference/x/following) · [Follower IDs](/api-reference/x/follower-ids) · [Following IDs](/api-reference/x/following-ids) · [Creator subscriptions](/api-reference/x/user-subscriptions) · [Affiliates](/api-reference/x/user-affiliates) · [Similar accounts](/api-reference/x/user-similar) · [Verified followers](/api-reference/x/verified-followers) · [Followers you know](/api-reference/x/followers-you-know) · [Check follower](/api-reference/x/check-follower)
    * Lists: [Search lists](/api-reference/x/search-lists) · [User lists](/api-reference/x/user-lists) · [List memberships](/api-reference/x/user-list-memberships) · [List members](/api-reference/x/list-members) · [List followers](/api-reference/x/list-followers)
    * Communities: [Find](/api-reference/x/community-find) · [Popular](/api-reference/x/community-popular) · [Topics](/api-reference/x/community-topics) · [Suggested](/api-reference/x/community-suggested) · [Details](/api-reference/x/community-info) · [Members](/api-reference/x/community-members) · [Moderators](/api-reference/x/community-moderators) · [Timeline](/api-reference/x/community-tweets) · [Media](/api-reference/x/community-media) · [Keyword search](/api-reference/x/community-search)
  </Accordion>
</div>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.