X Hide Replies API: the cap that is not in the docs

#Quick answer

The X hide replies API is a single call: PUT /2/tweets/:tweet_id/hidden with {"hidden": true}, authenticated as the person who started the conversation, with the tweet.moderate.write scope. X documents one ceiling on it, 50 requests per 15 minutes per user. It does not document the second one: each conversation can only hold a limited number of hidden replies, and when that fills, every hide returns a bare 403 while unhide keeps returning 200.

Last updated: October 2026

If you just want to hide one rude reply by hand, none of this applies and how to hide replies on X is three taps. This page is about building moderation on top of the endpoint, which is a different problem with two undocumented edges.

#The endpoint itself

curl -X PUT "https://api.x.com/2/tweets/2090000000000000001/hidden" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"hidden": true}'

{ "data": { "hidden": true } }

Unhiding is the identical request with false. Four constraints apply:

That rate limit is the one people plan around, and it is worth knowing it used to be far worse. The Labs version allowed 10 requests per 15 minutes shared across every authenticated user of your app. The v2 endpoint moved it to 50 per user, which is 200 hides an hour for one account. A post that attracts a few thousand hostile replies in an afternoon cannot be swept clean in real time, no matter how good your classifier is. Design for a queue.

Token scope planning is its own exercise, and X API OAuth maps every scope to the endpoints it unlocks.

#The 403 that is not an auth error

In August 2026 a security vendor opened a forum thread with an unusually clean bug report: the same token, on the same reply, got a 403 Forbidden for {"hidden": true} and a 200 for {"hidden": false}.

That combination rules out almost everything. A broken token fails both ways. A missing tweet.moderate.write scope fails both ways. Not owning the conversation fails both ways. X staff agreed in the thread and suggested testing the hide from the X app instead, to separate an account-level restriction from an API problem. The app hid the reply without complaint. The API still refused it.

Seven weeks of thread followed. Status updates, no root cause, a production feature broken for paying customers the whole time.

On 11 October 2026 the reporting team found it themselves, and the answer was a limit X used to publish and quietly stopped publishing. The conversation had hit the maximum number of replies it could hold hidden. Their first 403 landed on 19 August 2026 at 21:43 UTC, after about 730 hides in that one conversation. The archived version of the hide replies introduction, captured in April 2024, states it plainly: "Each conversation supports hiding up to 725 Tweets." Search the current page for that sentence and it is gone.

Their reproduction is the part worth copying into your own runbook:

1. Hide a fresh reply in the full conversation. 403.
2. Unhide any reply hidden earlier in the same conversation. 200.
3. Retry the hide from step 1. 200.
4. Re-hide the reply from step 2. 403.

Unhiding a reply on a different post did not help, so the budget is per conversation, not per account or per app. X staff acknowledged the finding on 13 October 2026 and said they had passed three questions to the team: whether the cap can be raised, whether deleted replies and hides made in the app count against it, and whether the bare 403 can be replaced by a specific error. None of that is answered yet, and the docs still do not mention any cap.

Practical consequence: treat 403 on hidden: true as a capacity signal, not an auth failure. Log the conversation ID, count your own hides per conversation, and surface "this thread is full" to the user rather than retrying.

#What X now recommends instead of Perspective

On 1 October 2026 X rewrote its real-time reply moderation guide, and the rewrite matters because it invalidates nearly every tutorial on the subject. The old version scored replies with Google Jigsaw's Perspective API and received them through the Account Activity API. Perspective is deprecated. Account Activity is being replaced.

X's current pipeline is three hops:

1. The X Activity API delivers a post.reply.create event to your webhook when someone replies to the subscribed user's post.
2. The xAI API asks Grok to judge that reply against a moderation policy you write in plain English, returning a strict JSON schema with violates_policy, confidence, categories and reason.
3. Hide Replies hides it when violates_policy is true and confidence clears your threshold. X's example uses 0.9.

Two request fields in the xAI call are easy to miss and worth setting on purpose. store: false keeps the reply text and the verdict out of xAI's 30-day retention. reasoning.effort: "low" keeps latency down on what is a short classification job. Strict structured output means a malformed answer cannot reach the hide step at all.

X's own guidance on the policy prompt is better than the code: say what to leave alone as loudly as you say what to hide, pass the original post along with the reply so the model can tell hostility from blunt relevance, run in log-only mode before switching on auto-hide, and give users a list of everything the app hid with one-click undo. A reply left visible for a minute costs very little. A legitimate voice silenced by a false positive costs a lot more.

#The gaps in the event stream

post.reply.create is narrower than it sounds, and three limits shape what you can build.

Direct replies only. The event fires when someone replies to the subscribed user's post. It does not fire for replies to replies. Hide Replies can still hide anything in a conversation the user started, so deeper threads need a separate sweep with recent search and conversation_id.

Protected accounts are invisible. Posts from protected accounts are not delivered through the X Activity API at all, so those replies never reach your webhook.

Tokens expire in two hours. The hide call runs on the user's access token, so offline.access and a working refresh loop are not optional for anything that runs unattended.

#What it costs to run

Every delivered post.reply.create event is billed as a Post. At current pay-per-use rates that is $0.005 per event, charged on reply volume rather than on moderation actions, so a noisy account costs the same whether you hide one reply or none.

There is a documentation quirk here worth flagging, because it is the second time this pattern has shown up on X's rate card. The pricing page has a webhook events table that prices post.create at $0.005, follow.follow at $0.010 and so on. post.reply.create is not in that table. The Activity API page is the one that says all Post events bill as a Post, so the price is derivable but never stated next to the event you are actually subscribing to. The same gap exists for media upload and for the News endpoints, as our X API pricing breakdown covers.

Add xAI tokens per classification on top. X API credit purchases earn free xAI credits, which softens it, but the honest budgeting line is: reply volume drives the bill, and a single viral post can multiply it overnight.

#Before you automate it

Hiding replies on your own posts is a native control, and X ships both the endpoint and an official auto-hide guide, so the mechanism itself is supported. Automating account actions at scale is still governed by X's automation rules, and X has not given a public, general answer on where an AI-driven moderation service sits. In February 2026 a developer asked that exact question on X's own forum about an auto-block service and the thread closed automatically with no staff reply. Read the rules, keep a human in the loop at low confidence, and get written clarification before you sell it.

One last thing to tell your users honestly: hiding is not deletion. A hidden reply stays public behind "View hidden replies", and its author is never notified. Any interface that implies otherwise is lying to the person paying for it.

If reply volume rather than reply moderation is the problem, that is a different tool. X-Autopilot runs replies from your own browser on your own machine, and X comment bots covers what that does and does not get flagged for.