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

# Twitter Follow Checker

> Check whether X accounts follow each other.

# Twitter Follow Checker

Check the follow relationship between one X account and a set of others. For every pair you get both directions at once: whether `username` follows the other account, whether that account follows back, and whether the follow is mutual. Use it to verify that campaign participants follow your brand, confirm that a partner account actually follows you back, or map the connections between a group of creators.

```json theme={"dark"}
{
  "username": "elonmusk",
  "usernames": [
    "SpaceX",
    "NASA"
  ]
}
```

Provide the account to check in username and up to 100 accounts to compare it with in usernames. Each pair returns whether username follows the other account and whether it is followed back.

## Standard Result Fields

Task results use the stable SocQ fields below. Source-specific field names and formats are normalized without inferring or enriching values that the source did not provide. To request a smaller field set, use `fields` for MCP queries, `_result_fields` for typed tools, or `--result-fields` in the CLI. Declared fields remain present when their value is `null`.

| Field | Type | Nullable | Description |
| - | - | - | - |
| `id` | `string` | Yes | Identifier of the account pair, as `source_username:target_username`. |
| `platform` | `string` | No | Platform the result belongs to, such as `instagram` or `linkedin`. |
| `resource` | `string` | No | SocQ resource represented by the result, such as `videos` or `comments`. |
| `type` | `string` | No | Category of the result item, such as `video`, `post`, or `comment`. |
| `url` | `string` | Yes | Profile URL of `target_username`. |
| `published_at` | `string` | Yes | Time the source item was published, in ISO 8601 format when available. |
| `collected_at` | `string` | No | Time SocQ collected or processed this result, in ISO 8601 format. |
| `source_username` | `string` | Yes | Username of the account being checked. |
| `target_username` | `string` | Yes | Username of the account it is compared with. |
| `is_following` | `boolean` | Yes | Whether `source_username` follows `target_username`. |
| `is_followed_by` | `boolean` | Yes | Whether `target_username` follows `source_username` back. |
| `is_mutual` | `boolean` | Yes | Whether the two accounts follow each other. |

The following example shows the response format for a completed task. Actual data depends on your query.

## Completed Task Response

```json theme={"dark"}
{
  "code": 200,
  "data": {
    "task_id": "example-x-check-follow",
    "status": "succeeded",
    "public_id": "x/check-follow",
    "result_count": 2,
    "credits_amount": 1.4,
    "results": {
      "limit": 50,
      "next_cursor": null,
      "has_more": false,
      "schema_id": "follow-check",
      "schema_version": "1.0",
      "items": [
        {
          "id": "elonmusk:SpaceX",
          "platform": "x",
          "resource": "check-follow",
          "type": "follow-check",
          "url": "https://x.com/SpaceX",
          "published_at": null,
          "collected_at": "2026-11-13T10:15:28Z",
          "source_username": "elonmusk",
          "target_username": "SpaceX",
          "is_following": true,
          "is_followed_by": true,
          "is_mutual": true
        },
        {
          "id": "elonmusk:NASA",
          "platform": "x",
          "resource": "check-follow",
          "type": "follow-check",
          "url": "https://x.com/NASA",
          "published_at": null,
          "collected_at": "2026-11-13T10:15:28Z",
          "source_username": "elonmusk",
          "target_username": "NASA",
          "is_following": true,
          "is_followed_by": false,
          "is_mutual": false
        }
      ]
    }
  }
}
```


## OpenAPI

````yaml api-manual/agent-api/agent-api.json POST /v1/x/check-follow
openapi: 3.1.0
info:
  title: SocQ Agent API
  version: v1-1fa58609f514
  description: Asynchronous social data API generated from the SocQ Capability Registry.
servers:
  - url: https://api.socq.ai
security: []
paths:
  /v1/x/check-follow:
    post:
      tags:
        - x
      summary: Twitter Follow Checker API
      description: Check whether X accounts follow each other.
      operationId: socq_x_check_follow
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $schema: https://json-schema.org/draft/2020-12/schema
              type: object
              additionalProperties: false
              properties:
                callback_url:
                  type: string
                  format: uri
                username:
                  type: string
                  minLength: 1
                  description: The X account to check, with or without @.
                usernames:
                  type: array
                  items:
                    type: string
                    minLength: 1
                  minItems: 1
                  description: X accounts to compare it with, with or without @.
                  maxItems: 100
              required:
                - username
                - usernames
              description: >-
                Provide the account to check in username and up to 100 accounts
                to compare it with in usernames. Each pair returns whether
                username follows the other account and whether it is followed
                back.
      responses:
        '200':
          description: Task accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentSubmitResponse'
        '422':
          description: Input validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentValidationErrorResponse'
      security:
        - bearerAuth: []
        - apiKeyAuth: []
components:
  schemas:
    AgentSubmitResponse:
      type: object
      properties:
        code:
          type: integer
          const: 200
        data:
          type: object
          properties:
            task_id:
              type: string
            status:
              type: string
            created_time:
              type:
                - string
                - 'null'
          required:
            - task_id
            - status
    AgentValidationErrorResponse:
      type: object
      properties:
        code:
          type: integer
          const: 422
        error:
          type: object
          properties:
            message:
              type: string
            type:
              type: string
            details:
              type: object
          required:
            - message
            - type
      required:
        - code
        - error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````

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