This endpoint allows you to search and discover Communities based on keywords.

The endpoint accepts one or more keywords as a query. By default, a request will return both public and closed Communities that match the specified query.

Account setup

To access these endpoints, you will need:

Learn more about getting access to the X API v2 endpoints in our getting started guide.

Getting started

​
Authentication

You can authenticate this endpoint with either OAuth 1.0a User Context, [OAuth 2.0 App-Only](https://developer.twitter.com(/resources/fundamentals/authentication#app-only-authentication-and-oauth-2-0-bearer-token), or OAuth 2.0 Authorization Code with PKCE.  

​
Making a request

You can call the Search Communities endpoint as shown below:

curl --location 'https://api.twitter.com/2/communities/search?query=anime' --header 'Authorization: ••••••'

If the request is successful, you should see the JSON response as shown below:

{

   "data": [

       {

           "access": "Public",

           "description": "Welcome to the Anime Community! Where anime fans gather to share their favorite shows and discuss everything anime-related.",

           "join_policy": "Open",

           "name": "Anime Community"

       },

       {

           "access": "Public",

           "description": "Join and text about anime 🥰",

           "join_policy": "Open",

           "name": "Anime World 🌸"

       },

       {

           "access": "Public",

           "description": "For all anime lovers and creators!",

           "join_policy": "Open",

           "name": "Anime"

       },

   ],

   "meta": {

       "next_token": "7140dibdnow9c7btw481s8m561gat797rboud5r80xvzm"

   }

}

​
Community fields

You can fetch additional data associated with a community by specifying Community Fields.

The following Community Fields are available:

Field valueTypeDescription
created_atdate (ISO 8601)Creation time of the Community.
idstringThe unique identifier of the Community.
namestringThe name of the Community.
descriptionstringThe text of the Community’s description, if provided.
accessstringThe access level of the Community.

Can be one of:

* Public
* Closed
join_policystringThe join policy for the Community.

Can be one of:

* Open
* RestrictedJoinRequestsDisabled
* RestrictedJoinRequestsRequireAdminApproval
* RestrictedJoinRequestsRequireModeratorApproval
* SuperFollowRequired
member_countintegerThe number of members that have joined the Community.

​
Example Request

You can call the Search Communities endpoint with additional community fields as shown below:

curl --location 'https://api.twitter.com/2/communities/search?query=anime&community.fields=access,created_at,description,id,join_policy,member_count,name' --header 'Authorization: ••••••'

Example Response

If the request is successful, you should see the JSON response as shown below:

{

   "data": [

       {

           "id": "Q29tbXVuaXR5OjE3NTg3NDc4MTc2NDI3MDA5MjI=",

           "description": "Welcome to the Anime Community! Where anime fans gather to share their favorite shows and discuss everything anime-related.",

           "join_policy": "Open",

           "access": "Public",

           "member_count": 39915,

           "name": "Anime Community",

           "created_at": "2024-02-17T06:58:50.000Z"

       },

       {

           "id": "Q29tbXVuaXR5OjE1MDY3OTM5NTMxMDYwNDI4OTE=",

           "description": "Join and text about anime 🥰",

           "join_policy": "Open",

           "access": "Public",

           "member_count": 26019,

           "name": "Anime World 🌸",

           "created_at": "2022-03-24T00:44:07.000Z"

       },

       {

           "id": "Q29tbXVuaXR5OjE0OTY3NzYyMTU5Mzk1MzQ4NDk=",

           "description": "For all anime lovers and creators!",

           "join_policy": "Open",

           "access": "Public",

           "member_count": 5612,

           "name": "Anime",

           "created_at": "2022-02-24T09:17:13.000Z"

       }

   ],

   "meta": {

       "next_token": "7140dibdnow9c7btw481s8m561gat797rboud5r80xvzm"

   }

}
Communities lookup by Community ID.Search Communities