TwitterAPIs Docs
API ReferenceWrite Actions

Unfollow a User API | Twitter Unfollow Endpoint

Unfollow a user as the authenticated account. Requires a logged-in session for the acting account. Billed at $0.0008 per call, the same as a standard read. Cost: $0.0008 per call.

Unfollow User removes a follow from your own authenticated X account. It requires a registered X session and returns ok:true when the unfollow is recorded. Pass the target's numeric user_id or its username (resolved for you) as a query parameter or in a JSON body. This is a write action billed at $0.0008 per call, the same as a standard read.

POST
/user/unfollow

Authorization

bearerAuth
AuthorizationBearer <token>

Pass your API key as a bearer token on every request: Authorization: Bearer <API_KEY>.

In: header

Query Parameters

user_id?string

Numeric ID of the user to unfollow. Send this or username; user_id wins when both are present.

username?string

Handle of the user to unfollow, with or without the leading @. Resolved to its numeric ID for you through the same cached lookup as Check Follow Relationship; an unknown handle returns 404 and no unfollow is issued.

proxy?string

Optional. Pass your own proxy (http(s)/socks URL) to egress the write through your clean IP for best success; if omitted, we use the session's proxy / our default.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/user/unfollow?user_id=44196397&username=elonmusk"
{  "ok": true}
{  "error": "bad_request",  "message": "Missing or malformed parameter. Fix the request before retrying."}
{  "error": "unauthorized",  "message": "The API key is missing, malformed, or revoked. Check the Authorization header."}
{  "error": "insufficient_credits",  "message": "Your balance is exhausted. Top up your credits to continue.",  "top_up_url": "https://www.twitterapis.com/dashboard/buy-credits?utm_source=api&utm_medium=402"}
{  "error": "forbidden",  "message": "X refused this resource for the acting account: on a read, the account is not a participant in the DM thread, the target is protected or has blocked it, or the session was attestation-blocked for calling from a datacenter or rotating IP; on a write, the account is not authorized for the action or has no logged-in session. The credentials are still valid, so do not re-register."}
{  "error": "not_found",  "message": "The resource does not exist, for example a deleted tweet or a private account."}
{  "error": "rate_limited",  "message": "Too many requests. Back off and retry with exponential backoff."}
{  "error": "server_error",  "message": "Something failed on our side. Retry with backoff; if it persists, contact support."}

Pricing

UnitPrice
Per call$0.0008
Per 1,000 calls$0.80

Writes are billed at $0.0008 per call, the same as a standard read. A write that fails before reaching X is not billed.

When to use

Use it to unfollow accounts programmatically, for example pruning inactive accounts from who you follow.

FAQ

What does Unfollow User take?

The target account's numeric user_id or its username (with or without @), as a query parameter or in a JSON body, plus a registered X session. A username is resolved to its ID for you; if both are sent, user_id wins. It returns ok:true once the unfollow is recorded.

Is a session required to unfollow?

Yes. The action edits your own account's following graph, so a registered session is required or the call returns session_required.

What if I do not follow the account?

It returns ok:true since the resulting state is not following. The action is safe to repeat.

Was this page helpful?