X API Communities: the permission you cannot check

#Quick answer

The X API Communities namespace is two read-only endpoints: GET /2/communities/:id and GET /2/communities/search. Neither has ever appeared in X's developer changelog. You cannot create, join, moderate or list the members of a Community through the API, and the only way to write into one is a community_id parameter on POST /2/tweets. When that write returns 403, X's documented remedy is to check a permission that no endpoint and no field will tell you.

Last updated: November 2026

Everything below is checked against the live API description at api.x.com/2/openapi.json, version 2.174, read on 6 November 2026. Where X's prose documentation and its own machine-readable spec disagree, the spec is what the servers run.

#Two endpoints, and neither was ever announced

X's rate-limit reference settles the count in its heading: "Communities (2 endpoints)". Both get 300 requests per 15 minutes, per app and per user.

The absence is more interesting than the presence. Search X's developer changelog for Communities and you get two entries, both about the Posts endpoint rather than this namespace: community_id as a post field on 22 November 2024, and the share_with_followers broadcast flag on 28 July 2025. The lookup and search endpoints themselves were shipped without an announcement, which is why so few integrations use them and why the pages describing them have gone three releases without a correction.

They are also missing from the front door. The "What you can build" panel on X's X API introduction lists six namespaces: Posts, Users, Spaces, Direct Messages, Lists and Trends. Communities appears only one level deeper, in the API reference index. If you were scoping a Communities product from the landing page, you would conclude the API did not have one.

#The example request X publishes cannot authenticate

This is the fastest way to lose an afternoon. The search endpoint's documentation offers exactly one example:

curl "https://api.x.com/2/communities/search?query=Python&max_results=10" \
  -H "Authorization: Bearer $BEARER_TOKEN"

An app-only Bearer token. The live spec lists two security schemes on that path, OAuth 2.0 user context with the users.read and tweet.read scopes, and OAuth 1.0a. BearerToken is not one of them. The lookup endpoint does accept a Bearer token, so the pattern works on /2/communities/:id and then stops working the moment you move to search, which reads as an intermittent auth bug rather than a documented restriction.

X's own tooling agrees with the spec rather than the page. The generated CommunitiesClient in the official Python SDK, version 0.10.6, builds its acceptable-scheme list for the search call as OAuth 2.0 user token and OAuth 1.0a, with no Bearer branch at all. If you had reached for the SDK first you would never have hit this. Our notes on the official X API Python SDK cover the rest of that gap between the generated client and the hand-written docs.

There is a second asymmetry hiding in the lookup path. With a Bearer token it needs no scope. With OAuth 2.0 user context it needs three, including list.read, which has nothing to do with Communities and exists because Communities inherited plumbing from Lists. Picking the stricter auth mode costs you an extra scope on your consent screen. The trade-offs between the modes are in our breakdown of X API OAuth.

#A documented field that does not exist

X's lookup page publishes a response-fields table. It lists id, name, description, created_at, member_count and is_private.

is_private is not real. The community.fields enum has exactly seven values and that is not one of them:

So the one field in that table that would answer "is this Community private" is invented, and the two fields that actually answer it, access and join_policy, are missing from the table entirely. They are also untyped: both come back as bare strings with no published vocabulary, so you discover the accepted values by collecting responses and guessing at the set. created_at has no format either, which means no promise that it stays ISO 8601.

What you cannot get at all is anything visual or social. A developer asked for the banner image and the creator on 5 August 2025, quoting the same seven fields back at X. That thread has one post and no reply. Fifteen months later the enum is unchanged.

#The 403 that cannot be debugged

Reads are not the real wall. Writes are, and there is no Communities write endpoint. To post into a Community you call POST /2/tweets with community_id set to a numeric ID of up to 19 digits, which bills as Post: Create at $0.015 like any other post.

In February 2026 a developer reported that posting to a Community they owned and managed had started returning 403 Forbidden with the body "Your account is not permitted to access this feature", while an otherwise identical timeline post from the same authenticated user succeeded. Three other developers reported the same shape of failure in the same thread. On 6 March 2026 an X staff member answered that the 403 is intended behaviour "when requests are made where the authenticated user is unable to create a post for the provided Community", and advised checking that the authenticated user has the right permissions.

That advice is sound and impossible to follow. Nothing in the API exposes a user's relationship to a Community:

• community.fields has no membership, role or moderator value.
• There is no /2/communities/:id/members path, and no /2/users/:id/communities path either.
• The user object carries no Community list.

So the permission state that decides whether your write succeeds is readable only by attempting the write. For a scheduler or an agent that means a Community post has to be treated as a call that can fail permanently for reasons you cannot pre-flight, with retries that will never succeed. Build the 403 handler before you build the feature.

#Why 10 is the cheapest search you can buy

Community reads bill at $0.005 per resource returned. The documentation's parameter table says max_results has a "max 100" and stops there. The spec adds the part that matters: the minimum is 10, and the default is 10.

A search is therefore never cheaper than ten lookups, even when you only wanted the top hit. At the documented 300 requests per 15 minutes with full pages, the namespace will spend about $150 per window if you let it run flat out. Communities is also absent from the Owned Reads table, the $0.001 per-resource tier for reading your own data, so owning the Community buys you no discount. The full rate card and what deduplication does and does not cover is in our guide to X API pricing, and the per-endpoint ceilings are in X API rate limits.

One more detail for anyone writing a paginator: search accepts both next_token and pagination_token, but the response meta object only ever returns next_token. Read the one you are given.

#One boolean with two documented meanings

share_with_followers is worth a paragraph of its own because the two places X documents it describe different features.

The changelog entry of 28 July 2025 is explicit: pass it alongside community_id with true and the Community post is also broadcast to the authenticated user's followers' timelines, matching the "Also share with followers" checkbox on x.com. The live spec and the Create Post reference page describe the same boolean as "Share an exclusive (super-follower) tweet with all followers", which is a different product entirely, sitting next to the separate for_super_followers_only flag.

One parameter, two documented behaviours, and no prose anywhere on the reference page about Community posting at all. This is exactly the point the developer in the 403 thread was making when they wrote that the documentation still shows Community posting as supported: what "shows" it is a single schema line that describes something else.

#Long Community posts still truncate in search

A brand monitoring its own Community found in April 2025 that recent search would not return Community posts longer than 280 characters, and that asking for note_tweet did not recover the text. An X staff member confirmed the gap the same day and said it would be added in future. The developer followed up in June 2025. The thread ends there.

If your use case is reading a Community rather than posting to it, test this against your own account before committing. The mechanics of the two search endpoints and what reads cost are in our notes on X API search.

#What the namespace is actually good for

Discovery, and only discovery. Keyword search plus a lookup by ID gives you a usable map of public Communities with names, descriptions and member counts, which is a reasonable input to a research or audience-sizing tool. Pay the $0.05 floor, cache aggressively, and remember that neither endpoint tells you anything about your own standing.

Everything participatory still happens in the product. Joining, moderating, reading a Community timeline and seeing who is in it are human tasks on x.com, which is why our walkthrough of how to use X Communities is a UI guide rather than an API one.

If what you actually wanted was consistent participation in a Community you belong to, the API will not get you there, and the gray-area alternative deserves to be described honestly. X-Autopilot runs on your own Mac, in your own browser session, on your residential connection, so there is no shared cloud IP pool and no delegate account in the path. That is a smaller detection surface than a hosted scheduler, not an absent one, and automating engagement through a browser sits in a gray area under X's automation rules rather than being something X sanctions. The Communities endpoints are fully sanctioned. They are also, for now, a read-only window onto a product built around taking part.