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, 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 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.
|
|
join_policy |
string |
The join policy for the Community.
|
|
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.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"
}
}