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

# Unfollow a User

> Make the authenticated source user unfollow a target user on X/Twitter. Proxies the official X v2 unfollow-user endpoint through the AIsa gateway.

Unfollow a user on X/Twitter on behalf of the authenticated source user. This is a proxy for the official [X v2 `DELETE /2/users/{source_user_id}/following/{target_user_id}` endpoint](https://docs.x.com/x-api/users/unfollow-user), exposed through the AIsa gateway at `https://api.aisa.one/apis/v1/twitter/unfollow_twitter`. AIsa uses `POST` for consistency with the other Twitter write endpoints.

## Prerequisites

* An **AIsa API key** (Bearer token for every request).
* A one-time **OAuth authorization** for the source user account. Link your X account by calling [`POST /apis/v1/twitter/auth_twitter`](/api-reference/twitter/auth_twitter) — that endpoint kicks off the OAuth flow and stores the resulting session against your AIsa key, so you do not pass OAuth tokens in the request body here.
* The X session must hold the following scopes: `follows.write`, `tweet.read`, `users.read`.

<Tip>
  Looking to unfollow by `@username` instead of numeric ID? Resolve the user first with [`GET /twitter/user/info`](/api-reference/twitter/get_twitter-user-info), then pass the returned `id` as `target_user_id`.
</Tip>

## Response fields

| Field            | Type    | Meaning                                                                                                                                                                    |
| ---------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data.following` | boolean | `false` once the source user no longer follows the target. Returned as `false` even if the source user wasn't following the target to begin with — unfollow is idempotent. |

## Idempotency

Calling `unfollow_twitter` against a user you're not following is a no-op. The endpoint still returns `200` with `{ "data": { "following": false } }`. This matches X's own behavior and means you can safely retry.

For the full set of error responses and retry guidance, see [Error Codes](/api-reference/errors). Write endpoints count toward your standard key RPM/TPM — see [Rate Limits](/api-reference/rate-limits).

## Related

<CardGroup cols={3}>
  <Card title="Link an X Account" icon="key" href="/api-reference/twitter/auth_twitter">
    Start the OAuth flow that enables this endpoint.
  </Card>

  <Card title="Follow a User" icon="user-plus" href="/api-reference/twitter/follow_twitter">
    The inverse operation.
  </Card>

  <Card title="Check Follow Relationship" icon="user-group" href="/api-reference/twitter/get_twitter-user-check-follow-relationship">
    Verify the relationship before calling.
  </Card>
</CardGroup>


## OpenAPI

````yaml openapi/twitter-actions.json POST /twitter/unfollow_twitter
openapi: 3.0.3
info:
  title: Twitter Actions API
  version: 1.0.0
  description: >-
    Write actions against X/Twitter, routed through the AIsa gateway. Modeled
    after the official X v2 API endpoints (e.g., POST /2/users/{id}/following).
servers:
  - url: https://api.aisa.one/apis/v1
security:
  - BearerAuth: []
paths:
  /twitter/unfollow_twitter:
    post:
      summary: Unfollow a user on X/Twitter
      description: >-
        Make the authenticated source user unfollow the given target user on
        X/Twitter. Mirrors the [official X v2 `DELETE
        /2/users/{source_user_id}/following/{target_user_id}`
        endpoint](https://docs.x.com/x-api/users/unfollow-user), routed through
        the AIsa gateway. Uses POST (not DELETE) for consistency with the other
        AIsa Twitter write actions.


        **Authentication.** Requires an OAuth session for the source user,
        attached to your AIsa API key. Link the account once via `POST
        /apis/v1/twitter/auth_twitter`.


        **Scopes.** The underlying X session must hold `follows.write`,
        `tweet.read`, and `users.read`.


        Unfollowing a user you don't currently follow is a no-op and still
        returns `200` with `following: false`.
      operationId: unfollowTwitterUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - target_user_id
              properties:
                target_user_id:
                  type: string
                  description: >-
                    Numeric ID of the X/Twitter user to unfollow. Must match the
                    X regex `^[0-9]{1,19}$`.
                  pattern: ^[0-9]{1,19}$
                  example: '2244994945'
            examples:
              unfollow_user:
                summary: Unfollow @TwitterDev (id 2244994945)
                value:
                  target_user_id: '2244994945'
      responses:
        '200':
          description: >-
            Unfollow succeeded (or the source user wasn't following the target
            to begin with).
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      following:
                        type: boolean
                        description: >-
                          `false` once the source user no longer follows the
                          target user.
              example:
                data:
                  following: false
        '400':
          description: Invalid request — missing or malformed `target_user_id`.
        '401':
          description: Missing or invalid AIsa API key.
        '403':
          description: >-
            OAuth session missing, expired, or lacking the `follows.write`
            scope. Re-authorize via `POST /apis/v1/twitter/auth_twitter`.
        '429':
          description: >-
            Rate limit hit — either your AIsa key's RPM cap or the upstream X
            rate limit.
        '500':
          description: Internal error.
        '502':
          description: >-
            Upstream X API unreachable or returned an error. Safe to retry with
            exponential backoff.
      security:
        - BearerAuth: []
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: AISA API Key
      description: >-
        Your AIsa API key. The authenticated source user (the account doing the
        follow) is determined by the OAuth session attached to your key.

````