# Search communities

`GET https://api.twittrapi.com/communities/search/{searchTerm}`

Find X Communities by keyword.

HTML page: https://www.twittrapi.com/docs/reference/communities-search-searchterm

## Parameters

| Name | In | Type | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `searchTerm` | path | string | yes |  | Keyword, URL-encoded. |
| `count` | query | integer | no | 20 | Number of communities to ask X for. Sent to X as is; X treats it as a hint and decides how many it returns (follower and following pages often hold 50 to 70 users for count=20). A value that is not a number falls back to 20. |
| `cursor` | query | string | no |  | Bottom cursor from the previous page. Leave it out for the first page. See Pagination. |
| `sort` | query | string | no | Relevance | Sort order, passed to X as is. |

Every read endpoint also accepts `format=simple` (or the header `X-Response-Format: simple`) for compact, flat JSON with a fixed schema. Same price.

Paginated: pass the bottom cursor of one page as `cursor` to get the next. Each page is one billed call.

## Response

Raw JSON of X's CommunitiesSearchQuery. Communities are in data.communities_search_slice.items_results; the next-page cursor is data.communities_search_slice.slice_info.next_cursor (there are no cursor entries).

With `format=simple`: Collection of Community objects (description and rules are empty in search results).

## Errors

| Status | When |
| --- | --- |

Shared errors (401 missing key, 402 no balance, 429 rate limit, 5xx) are listed on https://www.twittrapi.com/docs/helpful-infos/error-handling. Calls that fail with 400, 408, 409 or a 5xx error are refunded.

## Example request

curl:

```bash
curl 'https://api.twittrapi.com/communities/search/python' \
  --header 'X-API-KEY: YOUR_API_KEY'
```

Python:

```python
from twittrapi import TwittrAPI

client = TwittrAPI(api_key="YOUR_API_KEY")
data = client.communities.search("python")
```

Node.js:

```js
import { TwittrAPI } from "twittrapi";

const client = new TwittrAPI({ apiKey: process.env.TWITTRAPI_API_KEY });
const data = await client.communities.search({ query: "python" });
```

RapidAPI:

```bash
curl 'https://twitter-aio.p.rapidapi.com/communities/search/python' \
  --header 'x-rapidapi-key: YOUR_RAPIDAPI_KEY' \
  --header 'x-rapidapi-host: twitter-aio.p.rapidapi.com'
```

## Example response

Shortened: arrays keep their first items and long strings are cut.

Raw (default):

```json
{
  "data": {
    "communities_search_slice": {
      "items_results": [
        {
          "id": "Q29tbXVuaXR5UmVzdWx0czoxNzYyNDk0Mjc2NTY1NDI2NTky",
          "result": {
            "__typename": "Community",
            "custom_banner_media": {
              "id": "QXBpTWVkaWE6DAATCgABG9hLw10WsAAAAA==",
              "media_info": {
                "__typename": "ApiImage",
                "color_info": {
                  "palette": [
                    {
                      "percentage": 71.75,
                      "rgb": {
                        "blue": 74,
                        "green": 45,
                        "red": 21
                      }
                    },
                    "… 4 more"
                  ]
                },
                "original_img_height": 720,
                "original_img_url": "https://pbs.twimg.com/community_banner_img/2006436936446029824/n1OK-QV1?format=jpg&name=orig",
                "original_img_width": 1800,
                "salient_rect": {
                  "height": 1,
                  "left": 899,
                  "top": 360,
                  "width": 1
                }
              }
            },
            "default_banner_media": {
              "id": "QXBpTWVkaWE6DAABCgABFECTH+kUUAQKAAITiFWq8lUQBAAA",
              "media_info": {
                "__typename": "ApiImage",
                "color_info": {
                  "palette": [
                    {
                      "percentage": 57.34,
                      "rgb": {
                        "blue": 178,
                        "green": 171,
                        "red": 3
                      }
                    },
                    "… 4 more"
                  ]
                },
                "original_img_height": 480,
                "original_img_url": "https://pbs.twimg.com/media/FECTH-kUUAQMe8W.jpg",
                "original_img_width": 1200
              }
            },
            "id": "Q29tbXVuaXR5OjE3NjI0OTQyNzY1NjU0MjY1OTI=",
            "is_nsfw": false,
            "member_count": 30718,
            "members_facepile_results": [
              {
                "id": "VXNlclJlc3VsdHM6MTAwMDAwMDAwMDAwMDAwMDAwMQ==",
                "result": {
                  "__typename": "User",
                  "id": "VXNlcjoxMDAwMDAwMDAwMDAwMDAwMDAx",
                  "legacy": {
                    "profile_image_url_https": "https://pbs.twimg.com/profile_images/1000000000000000000/example_normal.jpg"
                  }
                }
              },
              "… 4 more"
            ],
            "name": "AI — Rumors & Insights",
            "primary_community_topic": {
              "topic_name": "Artificial Intelligence"
            },
            "rest_id": "1762494276565426592"
          }
        },
        "… 1 more"
      ],
      "slice_info": {
        "next_cursor": "WzExMy41ODc5MSwxODk3OTI3NDQxNDQxNTEzNzE4XQ=="
      }
    }
  }
}
```

Simple (`format=simple`):

```json
{
  "data": [
    {
      "id": "1762494276565426592",
      "name": "AI — Rumors & Insights",
      "description": "",
      "createdAt": null,
      "memberCount": 30718,
      "moderatorCount": 0,
      "joinPolicy": null,
      "nsfw": false,
      "topic": "Artificial Intelligence",
      "bannerUrl": "https://pbs.twimg.com/community_banner_img/2006436936446029824/n1OK-QV1?format=jpg&name=orig",
      "creator": null,
      "rules": []
    },
    "… 1 more"
  ],
  "nextCursor": "WzExMy41ODc5MSwxODk3OTI3NDQxNDQxNTEzNzE4XQ==",
  "previousCursor": null,
  "hasNextPage": true
}
```