# Find communities by name or topic

`POST /v1/reddit/search/subreddits`

Communities whose name or description matches the query, with member counts. Use it to
find where a topic is discussed before reading or watching those communities. To search
*posts* inside one community, use `POST /v1/reddit/subreddits/{name}/search` instead.

**Price:** 1 credit per call, plus 1 credit per subreddit returned. Failed and refused calls cost nothing.

**Rate limit:** Counts as 2 requests against your per-minute rate limit.

**MCP tool:** `search_subreddits`, on every [MCP](/mcp) connection.

Requires an API key, sent as `Authorization: Bearer <key>`.

## Request

```bash
curl --request POST \
  --url https://api.weirapp.io/v1/reddit/search/subreddits \
  --header "Authorization: Bearer $WEIR_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"query":"payment failures"}'
```

### Body

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `query` | string | yes | Words to match against community names and descriptions. · 1–500 chars |
| `sort` | string | no | `activity` favours communities that are busy right now. · `relevance`, `activity`, default `"relevance"` |
| `includeNsfw` | boolean | no | Include results marked NSFW. Off by default; what it removes is reported in `meta.omittedNsfw`. · default `false` |
| `limit` | integer | no | 1–100, default `25` |
| `cursor` | string | no | `meta.nextCursor` from the previous page, unchanged. Opaque, signed, and bound to the other parameters: change any of them and start again without a cursor. · 1–4096 chars |

## Response

Communities, in Reddit's own field names.

### `200`

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `data` | array of object | yes |  |
| `data[].id` | string | yes | Reddit's fullname for the community, `t5_` included. |
| `data[].name` | string | yes | Community name without the `r/` prefix. |
| `data[].title` | string | yes |  |
| `data[].description` | string or null | yes | The short public description. Null if unset. |
| `data[].url` | string | yes |  |
| `data[].subscribers` | integer | yes | min 0 |
| `data[].over18` | boolean | yes | The whole community is marked NSFW. |
| `data[].createdUtc` | number | yes |  |
| `data[].createdAt` | string (date-time) | yes |  |
| `data[].subredditType` | string | yes | `public`, `restricted`, `private`, `archived`, `gold_restricted`, or `user`. |
| `data[].submissionType` | string or null | yes | What may be posted: `any`, `link`, or `self`. |
| `data[].lang` | string or null | yes | The community's declared language, such as `en`. |
| `data[].quarantine` | boolean | yes | Quarantined by Reddit: hidden from search and listings. |
| `data[].communityIcon` | string or null | yes | URL of the community icon. Null if unset. |
| `data[].bannerImg` | string or null | yes | URL of the banner image. Null if unset. |
| `meta` | object | yes |  |
| `meta.requestId` | string | yes |  |
| `meta.nextCursor` | string or null | no |  |
| `meta.omittedNsfw` | integer | no | Items removed from this page because they are marked NSFW and `includeNsfw` is false. Absent when nothing was removed. A page can be short, or even empty with a non-null `nextCursor`, because of it. · min 0 |

## Errors

| Status | Meaning | What to do |
| --- | --- | --- |
| `400` | The request failed validation. | The request was malformed. The `details` object names the field. |
| `401` | The API key is missing, malformed, expired, or revoked. | The key is missing, malformed, revoked, or expired. |
| `402` | The account is out of credit. Not retryable: this cannot clear until the billing period resets or the plan changes. | Out of credits. **Never retry.** Only a person can clear it, by adding credits at https://weirapp.io/dashboard/billing. Retrying never will. |
| `403` | The API key does not carry the scope this route requires. | The key is valid but lacks the scope this operation needs. |
| `404` | The requested resource does not exist. | No such resource, or it is not public. |
| `429` | The per-minute rate limit is exhausted. Retryable: wait for Retry-After and try again. | Rate limited. Retryable: wait for `Retry-After`, then try again. |
| `500` | An unexpected error occurred. | Something failed on our side. Retryable with backoff. |
| `503` | The source is temporarily unavailable. The request is safe to retry. | A source was unreachable. Retryable with backoff. |