Introduction

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:

• An approved developer account.
• To authenticate using the keys and tokens from a developer App that is located within a Project. 

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.x.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.x.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 value	Type	Description
created_at	date (ISO 8601)	Creation time of the Community.
id	string	The unique identifier of the Community.
name	string	The name of the Community.
description	string	The text of the Community’s description, if provided.
access	string	The access level of the Community. Can be one of: * Public * Closed
join_policy	string	The join policy for the Community. Can be one of: * Open * RestrictedJoinRequestsDisabled * RestrictedJoinRequestsRequireAdminApproval * RestrictedJoinRequestsRequireModeratorApproval * SuperFollowRequired
member_count	integer	The 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.x.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"
   }
}