Unpin a Tweet API | Remove a Pinned Post on X

Unpin Tweet removes a pinned tweet from the top of your X profile, acting as your authenticated account. It requires a registered X session and returns ok:true with changed:true once X confirms the unpin. Pass the tweet id or url as a query parameter. This is a write action billed at $0.0008 per call, the same as a standard read.

curl -X POST "https://example.com/tweet/unpin?id=1759123456789012345&url=https%3A%2F%2Fx.com%2Fnaval%2Fstatus%2F1759123456789012345"

{  "ok": true,  "changed": true,  "action": "unpin",  "target_id": "1759123456789012345"}

{  "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."}

{  "ok": false,  "changed": false,  "reason": "no_op_declined",  "retryable": false,  "detail": {    "data": {      "pin_tweet": {}    }  },  "action": "pin",  "target_id": "1759123456789012345"}

{  "error": "write_cap_reached",  "reason": "write_cap_reached",  "message": "This session has reached its daily write limit of 50 writes. The limit counts each stored or per-call session on your API key separately and resets at 00:00 UTC (see Retry-After). Nothing was sent to X and this call is not charged.",  "daily_write_limit": 50,  "retry_after_seconds": 43200,  "action": "favorite",  "target_id": "1759123456789012345"}

{  "error": "server_error",  "message": "Something failed on our side. Retry with backoff; if it persists, contact support."}

Pricing

Writes are billed at $0.0008 per call, the same as a standard read. A change X confirms is billed, and so is an answer where X reports the post is already in that state (ok true, changed false); a 422 not-applied answer, an X error and a call that fails before reaching X are free.

When to use

Use it to take a post off the top of your profile programmatically, for example when a campaign ends and the launch post should no longer lead.

Notes

• Success is read from X's own confirmation that the post was unpinned. Any other successful answer from X is returned as 422 with ok false, changed false and X's body in detail, and is not billed. An error status from X is answered like the other writes: 401 for a dead session, 403 when forbidden, 429 when rate limited and 502 for an upstream error.
• Needs a session for the account you are acting as: register one once (POST /customer/session), or pass per-call x-auth-token and x-ct0 headers. Returns 409 session_required if neither is supplied.
• This call counts toward a daily write limit per stored or per-call session on your API key, 50 writes per UTC day by default, shared by the like, retweet, bookmark, follow and pin calls and their undos. At the limit the call answers 429 write_cap_reached with a Retry-After header to the next 00:00 UTC. Nothing is sent to X and the call is not billed. daily_write_limit in the body is the limit in force. Retrying before the reset gets the same answer.

Related endpoints

• Pin Tweet: Pin a tweet to the top of the authenticated account's profile.
• Delete Tweet: Delete one of your registered account's tweets by ID or status URL.
• Unlike Tweet: Remove a like (unfavorite) from a tweet.

FAQ

What does Unpin Tweet take?

The id or url of the pinned tweet as a query parameter, plus a registered X session. It returns ok:true and changed:true once X confirms the unpin.

Is a session required to unpin?

Yes. Like pinning, unpinning changes your own profile and runs as your account, so it needs a registered session or per-call credentials, or it returns session_required.

What does a 422 no_op_declined mean?

X answered without an error but did not confirm the unpin, so nothing is billed. detail carries X's own body so you can see what it said.