---
title: "Find communities by name or topic"
method: POST
path: "/v1/reddit/search/subreddits"
tags: ["Reddit"]
---

# Find communities by name or topic

`POST /v1/reddit/search/subreddits`

## Request

- Base URL: `https://api.weirapp.io`
- URL: `https://api.weirapp.io/v1/reddit/search/subreddits`
- Auth: HTTP bearer

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.

## Request body

- object
  - `query` string, required: Words to match against community names and descriptions.
  - `sort` 'relevance' | 'activity': `activity` favours communities that are busy right now.
  - `includeNsfw` boolean: Include results marked NSFW. Off by default; what it removes is reported in `meta.omittedNsfw`.
  - `limit` integer
  - `cursor` string: `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.

## Response `200`

Communities, in Reddit's own field names.

- object
  - `data` object[], required
    - `id` string, required: Reddit's fullname for the community, `t5_` included.
    - `name` string, required: Community name without the `r/` prefix.
    - `title` string, required
    - `description` string, nullable, required: The short public description. Null if unset.
    - `url` string, required
    - `subscribers` integer, required
    - `over18` boolean, required: The whole community is marked NSFW.
    - `createdUtc` number, required
    - `createdAt` string, date-time, required
    - `subredditType` string, required: `public`, `restricted`, `private`, `archived`, `gold_restricted`, or `user`.
    - `submissionType` string, nullable, required: What may be posted: `any`, `link`, or `self`.
    - `lang` string, nullable, required: The community's declared language, such as `en`.
    - `quarantine` boolean, required: Quarantined by Reddit: hidden from search and listings.
    - `communityIcon` string, nullable, required: URL of the community icon. Null if unset.
    - `bannerImg` string, nullable, required: URL of the banner image. Null if unset.
  - `meta` object, required
    - `requestId` string, required
    - `nextCursor` string, nullable
    - `omittedNsfw` integer: 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.

## Other responses

- `400`: The request failed validation.
- `401`: The API key is missing, malformed, expired, or revoked.
- `402`: The account is out of credit. Not retryable: this cannot clear until the billing period resets or the plan changes.
- `403`: The API key does not carry the scope this route requires.
- `404`: The requested resource does not exist.
- `429`: The per-minute rate limit is exhausted. Retryable: wait for Retry-After and try again.
- `500`: An unexpected error occurred.
- `503`: The source is temporarily unavailable. The request is safe to retry.

---

[API](https://skmtc.dev/weirapp/apis/weir-api.md) · [All operations](https://skmtc.dev/weirapp/apis/weir-api/llms.txt) · [OpenAPI document](https://skmtc.dev/weirapp/apis/weir-api/revisions/4c6a9ae0bfca?raw)