X Community Search API | Find Twitter Communities by Keyword

GET community/search finds X (Twitter) Communities by keyword and returns their ids, so you can then call Community Info, Community Members, Community Moderators, Community About or Community Tweets on them. It searches COMMUNITIES, not posts inside communities. Each hit carries id, name, member_count, is_nsfw, the topic name, both banners and the facepile avatar urls, which is the complete set X's search operation sends. It deliberately does not return description, rules, join policy or created_at, because those would all be null rather than real. A search that matches nothing returns 200 with an empty array, not 404. $0.0008 per call.

curl -X GET "https://example.com/community/search?query=build+in+public"

{  "communities": [    {      "id": "1493446837214187523",      "name": "Build in Public",      "member_count": 265158,      "is_nsfw": false,      "primary_topic": {        "topic_id": null,        "name": "Entrepreneurship"      },      "banner_url": "https://pbs.twimg.com/community_banner_img/...",      "custom_banner": {        "url": "https://pbs.twimg.com/community_banner_img/...",        "width": 805,        "height": 322      },      "default_banner": {        "url": "https://pbs.twimg.com/media/....jpg",        "width": 1200,        "height": 480      },      "member_avatar_urls": [        "https://pbs.twimg.com/profile_images/.../photo_normal.jpg"      ]    }  ],  "next_cursor": "WzM1Mi4xMzgzLDE5NDM4NDIyMDQwNzU4NjgyMzhd",  "has_more": 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."}

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

When to use

Use it as step one of any community workflow: turn a topic or brand keyword into community ids, rank them by member_count, then pull the ones worth having in full with Community Info.

Notes

• THIS SEARCHES COMMUNITIES, NOT POSTS. It answers which communities are about a topic. It does not search the posts inside them, and there is no Top or Latest ordering parameter, because the X operation behind it takes none.
• THE HITS ARE DELIBERATELY SMALLER THAN Community Info RETURNS. X's search operation sends nine fields per hit and no more, so rather than hand you a full community object with description, rules, join policy, created_at and moderator_count all null, this returns only what X sent. A null here always means the community has none, never that we did not ask. Follow up with Community Info on any id you want in full.
• primary_topic carries a name but a null topic_id on this endpoint, because X's search operation sends the name only. Community Info returns both.
• member_avatar_urls is urls only, and the name is literal: the facepile entries on this operation carry no user id and no handle, unlike the facepile on Community Info. Use Community Members to find out who those people are.
• A SEARCH THAT MATCHES NOTHING RETURNS 200 with an empty array, not 404. Only a genuine transport failure or an unrecognised upstream shape produces an error, and an unrecognised shape is a 502 parse_failed that is not billed to you.

Pagination

Pass the returned next_cursor straight back as ?cursor= and stop when has_more is false. An empty first page is NOT a 404 here: a keyword that matches no community is a real answer.

Related endpoints

• Community Info: Metadata, rules and banners for one X Community.
• Community About: A community's moderators and a members preview, as full profiles.
• Community Members: Page through a community's member roster, each row carrying that member's role.
• Community Tweets: Page through a community's post timeline, with the pinned post returned separately.

FAQ

Does this search posts inside communities?

No. It searches for communities themselves, by keyword, and returns the communities. Searching posts across all communities is a different capability and is not part of this endpoint.

Can I sort by Top or Latest?

No. The X operation behind this endpoint accepts no ordering parameter, so exposing one would be inventing a control that does not exist. Results come back in X's own relevance order, and member_count is on every hit if you want to re-rank them yourself.

Why do the results have no description or rules?

Because X's search operation does not send them. Returning a full community object with those fields null would be telling you the community has no rules, which is a different and false statement. Take the id and call Community Info for the complete object.

What does an empty communities array mean?

That no community matched your keyword. It comes back as a 200, because that is a true answer, and 404-ing it would make every unusual keyword look like a broken endpoint.