> ## 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 follower checker API for X accounts

> Check whether one X user follows another in either direction for giveaway eligibility, campaign proof, CRM flags, and relationship audits. 5 credits per call.

<Panel>
  <Tabs defaultTabIndex={0} sync={false}>
    <Tab title="200" id="response-x-check-follower-200">
      ```json theme={null}
      {
        "isFollowing": false,
        "isFollowedBy": true,
        "sourceId": "11348282",
        "sourceUsername": "nasa",
        "targetId": "34743251",
        "targetUsername": "spacex"
      }
      ```
    </Tab>

    <Tab title="400" id="response-x-check-follower-400">
      ```json theme={null}
      {
        "error": "missing_params"
      }
      ```
    </Tab>

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

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

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

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

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

    <Tab title="503" id="response-x-check-follower-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>

This route checks one follow relationship in both directions. Supply 2 accounts, each by user ID or username, and store both boolean results.

<Callout icon="coins" color="#5c3327">
  **5 credits per call** · [All plans](https://xquik.com/#pricing) from \$0.00012/credit · Direct [MPP](/mpp/machine-payments-protocol): USD 0.00075 per call
</Callout>

<Info>
  Check follower verifies one known relationship without exporting a follower
  list. Pass the participant as `source` and the required brand, creator, or
  partner account as `target`. Each input accepts a user ID, a username,
  `@username`, or supported X or Twitter profile URL. Xquik resolves profile URLs
  and converts both usernames to lowercase before lookup. The response returns both directions:
  `isFollowing` for source-to-target proof and `isFollowedBy` for
  target-to-source context.
</Info>

<CodeGroup>
  ```bash Follow task theme={null}
  curl -G https://xquik.com/api/v1/x/followers/check \
    --data-urlencode "source=participant_handle" \
    --data-urlencode "target=brand_handle" \
    -H "x-api-key: xq_your_api_key_here" | jq
  ```

  ```javascript Node.js theme={null}
  async function buildFollowCheckAudit() {
    const campaignId = "spring-launch-2026";
    const participantHandle = "participant_handle";
    const requiredFollowHandle = "brand_handle";
    const params = new URLSearchParams({
      source: participantHandle,
      target: requiredFollowHandle,
    });

    const response = await fetch(`https://xquik.com/api/v1/x/followers/check?${params}`, {
      headers: { "x-api-key": "xq_your_api_key_here" },
    });

    if (!response.ok) {
      throw new Error(`Follow check failed with status ${response.status}`);
    }

    const data = await response.json();
    return {
      campaign_id: campaignId,
      participant_handle: data.sourceUsername,
      required_follow_handle: data.targetUsername,
      proof_endpoint: "GET /api/v1/x/followers/check",
      participant_follows_required_account: data.isFollowing,
      required_account_follows_participant: data.isFollowedBy,
      verification_state: data.isFollowing ? "matched" : "not_matched",
    };
  }

  const auditEvent = await buildFollowCheckAudit();
  // Replace this with your DB, queue, or warehouse write.
  await saveAuditEvent(auditEvent);
  ```

  ```python Python theme={null}
  import requests

  def build_follow_check_audit():
      campaign_id = "spring-launch-2026"
      participant_handle = "participant_handle"
      required_follow_handle = "brand_handle"
      response = requests.get(
          "https://xquik.com/api/v1/x/followers/check",
          params={
              "source": participant_handle,
              "target": required_follow_handle,
          },
          headers={"x-api-key": "xq_your_api_key_here"},
      )
      response.raise_for_status()
      data = response.json()
      return {
          "campaign_id": campaign_id,
          "participant_handle": data["sourceUsername"],
          "required_follow_handle": data["targetUsername"],
          "proof_endpoint": "GET /api/v1/x/followers/check",
          "participant_follows_required_account": data["isFollowing"],
          "required_account_follows_participant": data["isFollowedBy"],
          "verification_state": "matched" if data["isFollowing"] else "not_matched",
      }

  audit_event = build_follow_check_audit()
  # Replace this with your DB, queue, or warehouse write.
  save_audit_event(audit_event)
  ```
</CodeGroup>

The Node.js and Python snippets build a campaign audit event. They do not print
the raw response page. Store the event with your campaign, entrant, or CRM row.
Reviewers can then see the proof endpoint, the 2 handles checked, and the
matched or not-matched state.

## Campaign follow-check handoff

Use `GET /api/v1/x/followers/check` when a workflow already has both usernames,
`@usernames`, user IDs, or supported profile URLs. It returns one proof for a follow task.
Use it for campaign entry validation, giveaway eligibility, creator
partnerships, CRM qualification, and agent review queues.

<CardGroup cols={2}>
  <Card title="Single proof" icon="user-check">
    Store one audit event per participant and required account pair.
  </Card>

  <Card title="Both directions" icon="repeat-2">
    Store `isFollowing` as the required proof and `isFollowedBy` as reciprocal
    context.
  </Card>

  <Card title="Accepted inputs" icon="at-sign">
    Pass a user ID, a username, `@username`, or supported X or Twitter profile URL.
    A number is a user ID. An `x.com/i/user/<id>` link names an account by ID too.
  </Card>

  <Card title="Audit row" icon="clipboard-check">
    Store the campaign ID, participant handle, required follow handle,
    endpoint, result booleans, and verification state.
  </Card>

  <Card title="Draw handoff" icon="trophy">
    Use [Create draw](/api-reference/draws/create) when winner selection also
    needs reply, repost, keyword, or unique-author filters.
  </Card>

  <Card title="Stopped audit" icon="coins">
    After `402 insufficient_credits`, stop the audit. Resume after
    you add credits.
  </Card>
</CardGroup>

## Query parameters

<ParamField query="source" type="string" required>
  Source user ID, username, `@username`, or supported X or Twitter profile URL,
  such as `x.com/i/user/11348282`. A number is a user ID. Xquik resolves profile
  URLs and converts the username to lowercase. In campaign verification, this is
  usually the participant or entrant.
</ParamField>

<ParamField query="target" type="string" required>
  Target user ID, username, `@username`, or supported X or Twitter profile URL,
  such as `x.com/i/user/11348282`. A number is a user ID. Xquik resolves profile
  URLs and converts the username to lowercase. In campaign verification, this is
  usually the required brand, creator, or partner account.
</ParamField>

## Which verification endpoint?

<CardGroup cols={2}>
  <Card title="Follow task" icon="user-check">
    Use `GET /x/followers/check` for one participant-account follow proof.
  </Card>

  <Card title="Retweet task" icon="repeat-2">
    Use [`GET /x/tweets/{id}/retweeters`](/api-reference/x/retweeters) to page
    accounts that reposted one source tweet.
  </Card>

  <Card title="Reply task" icon="message-square-reply">
    Use [`GET /x/tweets/{id}/replies`](/api-reference/x/tweet-replies) to check
    public replies under the source tweet.
  </Card>

  <Card title="Quote task" icon="quote">
    Use [`GET /x/tweets/{id}/quotes`](/api-reference/x/tweet-quotes) to inspect
    quote-tweet entries.
  </Card>

  <Card title="Follower export" icon="users">
    Use [`GET /x/users/{id}/followers`](/api-reference/x/followers) or a saved
    follower export when you need many followers for one profile.
  </Card>

  <Card title="Giveaway draw" icon="trophy">
    Use [`POST /draws`](/api-reference/draws/create) when Xquik should apply
    follow, repost, reply, keyword, and winner rules together.
  </Card>
</CardGroup>

## Headers

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

<ParamField header="Authorization" type="string">
  `Bearer xq_your_guest_key_here` authenticates `paid_reads` guest keys. Direct MPP uses the `Payment ...` credential. Get it from the `WWW-Authenticate: Payment` challenge.
</ParamField>

## Response

### 200 OK

<ResponseField name="sourceId" type="string">
  The source account's user ID, as X gives it. Omitted when X names no account.
</ResponseField>

<ResponseField name="sourceUsername" type="string">
  The source account's username, in lowercase.
</ResponseField>

<ResponseField name="targetId" type="string">
  The target account's user ID, as X gives it. Omitted when X names no account.
</ResponseField>

<ResponseField name="targetUsername" type="string">
  The target account's username, in lowercase.
</ResponseField>

<ResponseField name="isFollowing" type="boolean">
  `true` if the source user follows the target user.
</ResponseField>

<ResponseField name="isFollowedBy" type="boolean">
  `true` if the target user follows the source user.
</ResponseField>

```json theme={null}
{
  "sourceId": "11348282",
  "sourceUsername": "nasa",
  "targetId": "34743251",
  "targetUsername": "spacex",
  "isFollowing": false,
  "isFollowedBy": true
}
```

### 400 Invalid params

```json theme={null}
{
  "error": "missing_params",
  "message": "Send both source and target, each a user ID or username.",
  "required": ["source", "target"]
}
```

One or both query parameters are missing. Provide both `source` and `target`.

```json theme={null}
{
  "error": "invalid_username",
  "message": "Invalid source. Use a user ID, username, @username or X profile URL.",
  "parameter": "source"
}
```

The named parameter is invalid. Use a user ID, a username, `@username`, or supported X or Twitter profile URL. The API rejects foreign hosts, profile status URLs, credentials, and custom ports.

### 401 Unauthenticated

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

Missing or invalid API key. Check the `x-api-key` header value.

### 402 Payment required

Account keys get account options. Guest keys get guest top-up only.
Anonymous calls receive a direct MPP `WWW-Authenticate: Payment` challenge plus a guest wallet creation action.
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.

<Note>
  **Next steps.** [Campaign verification workflow](/guides/campaign-verification-workflow)
  for audit rows and draw handoffs, [Get User](/api-reference/x/twitter-profile-lookup) to
  resolve profile details before checking, or [Get Account](/api-reference/account/get)
  to check remaining credits.
</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.