X API Community Notes: the mode you cannot turn off

#Quick answer

The X API Community Notes endpoints ship with a parameter you are not allowed to set to false. test_mode is required on the searches and on note submission, and it stays required until an automated evaluator admits your writer. Admission needs 50 submitted test notes clearing four thresholds, and then a random draw. Every one of those notes is billed at production rates and seen by nobody.

Last updated: November 2026

X announced three endpoints. There are five. The numbers that decide whether you ever leave test mode are published on a different domain from the API reference.

#Five paths, and what each one costs

Community Notes on X (formerly Twitter) are crowd-sourced context panels. If you want how the product works for a human contributor, that is a separate walkthrough of Community Notes on X. This is the developer surface, which is a narrower thing: it lets a programme propose notes and read its own scores. It cannot rate anyone else's note, ever. X's guide is explicit that ratings come from humans, and that humans decide what shows.

Two rows there are worth staring at.

Three of those paths have no price anywhere. The pay-per-use rate card has a Note: Read row at $0.005 per resource. It has no Note: Create, no Note: Delete and nothing for evaluation, and the write table does carry rows for bookmarks, list management, media metadata and privacy updates, so the omission is not a category gap. The nearest plausible match is Content: Manage at $0.005 per request, but X does not say that, which leaves three endpoints you can call without knowing what they draw down. Compare that to how precisely the rest of the card is specified in our breakdown of X API pricing.

And max_results defaults to 10 on both searches, with a ceiling of 100. X's quickstart passes 100 in every example. At $0.005 per Post that documented call is 50 cents, not 5. Ninety requests fit inside the 15-minute window the namespace intro publishes, which puts the ceiling on the eligible-posts search alone at $45 per window.

#The endpoint that moved and the one nobody announced

The changelog entry dated 17 September 2025 says X added POST /2/evaluate_note. The namespace introduction repeats that path today. The live OpenAPI description at version 2.174 has no such path. The endpoint is POST /2/notes/evaluate, and the string notes/evaluate does not appear in the changelog once.

This matters more than a typo normally would, because the reference pages for this namespace carry no prose. Open search-for-posts-eligible-for-community-notes and you get a title, a one-line description, and a dump of the entire OpenAPI document. The only human-written documentation X publishes for Community Notes is a 2 KB intro and a 7 KB quickstart, so the stale path in the intro is a third of the prose on the subject. Search results for the API repeat /2/evaluate_note back at you, which is what happens when the primary source is wrong.

DELETE /2/notes/:id is the other way round: it is in the schema, it returns {"data": {"deleted": true}}, its externalDocs points at the Community Notes guide, and no changelog entry has ever mentioned it. If you want to know what exists in this namespace, read the live description at api.x.com/2/openapi.json. It is the only complete list.

Neither do the rate limits live where you would look for them. X's central rate-limit reference has sections for Posts, Users, Spaces, DMs, Lists, Bookmarks, Compliance, Usage, Trends, Communities, Analytics, Media and a catch-all Other. There is no Notes section and no /2/notes row in any of them. The 90 per 15 minutes and 250 per day figures exist only in the namespace intro, which is a pattern worth knowing about before you plan capacity against X API rate limits.

#test_mode is an exam, not a sandbox

Here is the part the API reference does not tell you at all.

Notes submitted with test_mode: true are invisible to the public and are scored by an open-source automated evaluator rather than by human raters. The evaluator returns three measures, which you read back through the test_result field on notes_written:

To get out of test mode, among your most recent 50 test notes:

• at least 30% must score high on ClaimOpinion
• no more than 30% may score low on ClaimOpinion
• at least 95% must score high on UrlValidity
• at least 98% must score high on HarassmentAbuse

Clear all four and you enter a pool. X then selects admitted writers "automatically and randomly" because the pilot is deliberately small. There is no appeal, no queue position and no published wait. You get an email if it happens.

Of those four, two do the real filtering. The 98% on HarassmentAbuse and the 95% on UrlValidity are nearly pass-or-fail: 49 of your last 50 notes have to clear harassment and 48 have to have every link return a 200. X's own guide warns that UrlValidity produces occasional false positives when a source is briefly unreachable, so a news site having a bad afternoon can cost you a slot. Linking stable, fast, static sources is not a style preference here. It is the admission criterion.

#Your daily cap is a formula, not a number

Once you are writing real notes, X computes your daily writing limit from your own rating history. The guide publishes the whole thing. In plain terms:

• If 8 of your last 10 notes that reached a decision are Currently Rated Not Helpful, your limit is 2 notes a day.
• Else if 3 of your last 5 are Not Helpful, it is 5.
• Else, if you have written fewer than 20 notes total, it is 10.
• Otherwise it scales with your hit rate, defined as (Helpful minus Not Helpful) over total notes, up to an internal ceiling of 500.

One clause in that last step catches people: your limit is max(5, floor(min(DN_30 * 5, WL_L))), where DN_30 is your average daily notes over the last 30 days. Your cap can never exceed five times your own recent output. A writer averaging 10 notes a day is capped at 50 no matter how good the hit rate is, so volume has to be ramped rather than switched on. X also says writers must keep writing regularly to retain access at all.

That same writing-impact gate controls what you can see. scoring_status, the field that breaks your ratings down per rater factor bucket, is returned only to writers with a writing impact of 100 or more over the past 90 days. So is the is_media_note flag on note creation, which is in the request schema at 2.174 and is not mentioned in the quickstart.

#The parameter documented on the wrong domain

post_selection on the eligible-posts search is a string. That is everything the X API reference says about it: no description, no enum, no example. Its actual values are in the Community Notes guide:

# default feed, English only, the documented 100-result call
curl "https://api.x.com/2/notes/search/posts_eligible_for_notes?\
test_mode=true&max_results=100" -H "Authorization: OAuth ..."

# larger feed, Japanese - note the escaped colon
curl "https://api.x.com/2/notes/search/posts_eligible_for_notes?\
post_selection=feed_size%3Alarge,feed_lang%3Aja&max_results=100" \
  -H "Authorization: OAuth ..."

feed_size takes small, large, xl or xxl. Small is the default and, per X, has the highest density of Posts where a note can plausibly earn Helpful status; xxl has by far the lowest. The larger feeds require at least 100 notes written, a longer-term hit rate of 5% or better and a Not Helpful rate of 10% or less on your last 100 notes, and they are unavailable in test mode, so no new writer can touch them. xxl additionally needs writing impact of 100 or more in 90 days.

feed_lang defaults to English and accepts a language code or all. This one does work in test mode, which is the single most useful undocumented fact in the namespace: you can earn admission writing in any language.

#The fields that hand you the crowd's homework

Five values in the post.fields enum exist because of Community Notes, and the eligible-posts search accepts all of them:

• note_request_suggestions gives you the explanations people wrote when they requested a note on that Post, each with its suggested source URL.
• suggested_source_links_with_counts gives you the URLs those people proposed, each with a count of how many distinct people proposed it.
• matched_media_notes returns (note_id, match_status) pairs for your own media notes, where status is matched_but_not_shown or matched_and_shown. Creating a note on a Post that already has a matched_and_shown note is an error, so this field is how you avoid a wasted write.
• note_post carries the Post's full text when it runs past 280 characters, because text does not.
• suggested_source_links is the plain list without counts.

None of these are exclusive to the notes search. All five are in the post.fields enum on roughly 50 paths in the 2.174 description, including ordinary Post lookup, which means note-request data is readable far more widely than the Community Notes docs imply.

#Four places the quickstart and the schema disagree

Worth checking against the live description before you write a client:

Scope requirements are plainer than they look. There is no notes-specific OAuth scope. Reading uses tweet.read and all three writes use tweet.write, the same scope that posts to a timeline, so an app granted note-writing access is an app granted posting access.

#Before you build on this

Two constraints sit outside the API, and both are easy to miss.

X's AI Note Writer terms state that you may process Community Notes API data solely for the purpose of Community Notes AI note writing, and that you may not use the X API or X Content to fine-tune or train a foundation or frontier model. Read the developer guidelines before you plan a data pipeline around this, because the obvious use of a stream of fact-checked claims is the one that is ruled out.

And enrollment burns an account. The account must not already be a Community Notes contributor, needs a verified phone from a trusted carrier, and that phone can back one AI Note Writer plus at most one regular contributor account. The app must be registered with type Bot and read-write permissions, which is the same registration path as any other programmatic account and is covered in our notes on the X Bots API. You cannot bolt this onto the app you already use for posting without rethinking its permissions.

If what you actually wanted was distribution rather than fact-checking infrastructure, this is the wrong namespace. The Community Notes API is a volunteer pipeline with a pilot-sized gate in front of it, and the write endpoints do not have a price yet. For growing an account, X-Autopilot runs on your own Mac in your own browser session, which keeps a smaller detection surface than cloud schedulers that post from shared IP pools. That is a lower-risk posture, not a risk-free one, and automating engagement through a browser remains a gray area under X's rules rather than anything X sanctions. The API route here is the sanctioned one. It just does not do what most people hope it does.