> **For coding agents and LLMs:** This is one page from the Social Fetch docs (markdown export). The sections below mirror the orientation block in [`/llms.txt`](https://www.socialfetch.dev/llms.txt); use [`/llms.json`](https://www.socialfetch.dev/llms.json) when you need a structured operation inventory. The catalog covers documented operations with on-site reference pages.

## This page

- **On-site (HTML):** [https://www.socialfetch.dev/docs/api/v1/reddit/subreddits/get](https://www.socialfetch.dev/docs/api/v1/reddit/subreddits/get)
- **Markdown (.mdx) URL:** [https://www.socialfetch.dev/docs/api/v1/reddit/subreddits/get.mdx](https://www.socialfetch.dev/docs/api/v1/reddit/subreddits/get.mdx)

## API base URL and authentication

- **API origin (from OpenAPI `servers`):** `https://api.socialfetch.dev`
- **Authentication:** send `x-api-key: sfk_...` on `/v1/**` routes unless the operation is explicitly anonymous (check OpenAPI `security`, the [API reference hub](https://www.socialfetch.dev/docs/api.mdx), [`/llms.txt`](https://www.socialfetch.dev/llms.txt), or [`/llms.json`](https://www.socialfetch.dev/llms.json) for each route).
- **OpenAPI JSON:** [https://www.socialfetch.dev/openapi.json](https://www.socialfetch.dev/openapi.json)

## Recommended docs entrypoints (this site)

- [Documentation overview](https://www.socialfetch.dev/docs.mdx) — top-level orientation (markdown).
- [Quickstart](https://www.socialfetch.dev/docs/quickstart.mdx) — authenticate with `x-api-key`, validate auth with `whoami`, and understand the JSON envelope.
- [SDK](https://www.socialfetch.dev/docs/sdk.mdx) — official TypeScript SDK guide, including `SocialFetchClient`, `Result`, and `unwrap()`.
- [SDK reference](https://www.socialfetch.dev/docs/sdk-reference.mdx) — exhaustive SDK method inventory and route mapping for agents, tooling, and power users.
- [Choose the right endpoint](https://www.socialfetch.dev/docs/choose-endpoint.mdx) — task-oriented route selection for smoke tests, profiles, list endpoints, and single-item lookups.
- [Capability matrix](https://www.socialfetch.dev/docs/capability-matrix.mdx) — fast comparison of identifiers, pagination, outcomes, media download, and SDK coverage.
- [`/llms.json`](https://www.socialfetch.dev/llms.json) — structured machine-readable operation inventory with parameter names, pagination, outcomes, credits, and SDK mapping.
- [API reference hub](https://www.socialfetch.dev/docs/api.mdx) — human-friendly index of operations with links into generated pages.
- [Errors](https://www.socialfetch.dev/docs/errors.mdx) — shared error envelope and HTTP status guidance.
- [Credits](https://www.socialfetch.dev/docs/credits.mdx) — metering, `402`, and planning batch jobs.
- Outcome semantics such as `found`, `not_found`, and `private` are documented in [Errors](https://www.socialfetch.dev/docs/errors.mdx) and on operation pages when present in the OpenAPI contract.

## Markdown docs convention

- Every docs page has a markdown twin: append **`.mdx`** to the docs pathname (for example `/docs/quickstart` → `/docs/quickstart.mdx`).
- Agents that send `Accept: text/markdown` on `/docs/**` HTML URLs may receive markdown directly (same URL, `Vary: Accept`).

---
# Get Reddit subreddit (https://www.socialfetch.dev/docs/api/v1/reddit/subreddits/get)

## Summary

Get details for a Reddit community.

**Tags:** `Reddit`

## HTTP

- **Method:** GET
- **Path:** `/v1/reddit/subreddits`
- **Base URL:** `https://api.socialfetch.dev`

## Capability summary

- **SDK mapping:** `client.reddit.getSubreddit({ subreddit } | { url }) — subreddit names are case-sensitive`
- **Accepted identifiers:** `url` (query)
- **Pagination:** none
- **Business outcome field:** `data.lookupStatus` with values `found`, `not_found`

## Authentication

- **`x-api-key`**: API key (`sfk_...`)

## Parameters

### `subreddit` (query)

- **Required:** no
- **Constraints:** type `string`; minLength: 1; maxLength: 256
- **Description:** Subreddit name, optional `r/` prefix, or Reddit subreddit URL. Must match Reddit's exact casing (for example `AskReddit`, not `askreddit`).

### `url` (query)

- **Required:** no
- **Constraints:** type `string`; minLength: 1; maxLength: 4096
- **Description:** Optional subreddit URL for the request.

## Responses (status codes)

- **200**: Lookup result. Check `data.lookupStatus` for `found` or `not_found`.
- **400**: Invalid query or bad request
- **401**: Missing or invalid API key
- **402**: Insufficient credits
- **500**: Unexpected or billing error
- **502**: Lookup could not be completed from the response (unexpected or invalid data).
- **503**: Service temporarily unavailable; safe to retry with backoff.

## Response body (200)

Lookup result. Check `data.lookupStatus` for `found` or `not_found`.

### Field outline

- **data** (required) — type `object`. Endpoint-specific response payload.
  - **lookupStatus** (required) — type `string`; enum: found, not_found. Whether the subreddit was found or not found.
  - **subreddit** (required) — type `object`; nullable. Subreddit details when available.
    - **platform** (required) — type `string`; enum: reddit. Social platform for this subreddit.
    - **name** (required) — type `string`. Public subreddit name.
    - **subredditId** (optional) — type `string`. Stable subreddit identifier when available.
    - **url** (required) — type `string`; minLength: 1. Canonical public subreddit URL.
    - **description** (required) — type `string`; nullable. Subreddit description text when available.
    - **rules** (required) — type `string`; nullable. Subreddit rules text when available.
    - **iconUrl** (required) — type `string`; nullable. Subreddit icon image URL when available.
    - **bannerUrl** (required) — type `string`; nullable. Subreddit banner image URL when available.
    - **advertiserCategory** (optional) — type `string`; nullable. Advertiser category label when available.
    - **submitText** (optional) — type `string`; nullable. Submission guidance text shown to members when available.
    - **createdAt** (required) — type `string`; nullable. Subreddit creation timestamp when available.
  - **metrics** (required) — type `object`; nullable. Subreddit metrics when available.
    - **subscribers** (required) — type `integer`; minimum: 0; nullable. Subscriber count when available.
    - **weeklyActiveUsers** (required) — type `integer`; minimum: 0; nullable. Approximate weekly active users when available.
    - **weeklyContributions** (required) — type `integer`; minimum: 0; nullable. Approximate weekly contributions when available.
- **meta** (required) — type `object`. Metadata describing the request and billing outcome.
  - **requestId** (required) — type `string`; minLength: 1. Unique request identifier for tracing this API call.
  - **creditsCharged** (required) — type `integer`; minimum: 0. Credits charged for this request.
  - **version** (required) — type `string`; enum: v1. Public API version that served the response.

### Example JSON (found)

```json
{
  "data": {
    "lookupStatus": "found",
    "subreddit": {
      "platform": "reddit",
      "name": "AbsoluteUnits",
      "subredditId": "t5_a7wuv",
      "url": "https://www.reddit.com/r/AbsoluteUnits/",
      "description": "Absolute Unit : an Animal or Public Figure, who is larger than we should normally expect.",
      "rules": "#ABSOLUTE UNITS\n\n---\n\n    Be in awe at the size of these lads\n\n---\n\n###[Check out our deep, well-reflected definitions of an absolute unit.](https://www.reddit.com/r/AbsoluteUnits/wiki/index)  \n\n---\n\n#RULES:\n\n###Posting\n\n\n####1) Post Absolute Units only.\n\n -  **Only Absolute Units are allowed**. **No normal units**.  \n\n [See definition here](https://www.reddit.com/r/AbsoluteUnits/wiki/definition).\n\n -  **Post absolute units, not actual units**\n\n Absolute units only.  Not measuring units.   It was punny the first time, now it's old. Straight out bans will be handed. \n\n\n - **No Photoshopped Units**\n\n Only real absolute units are allowed. No AI, art, cartoon, edited or video game units.\n \n#### 2) Post public figures only\n\n- **No creepshots / No fat shaming pics allowed / No female bodybuilders**\n\n We're looking for animals mostly, particularly cute animals which happen to be very large. Only public figures are allowed; no harassment, creep-shots, witch-hunts, fat-shaming is allowed. Female bodybuilders are expressly forbidden and anyone making transphobic comments will be permanently banned. **Identify the public figure in the title. Don't assume they are well known**\n\n\n#### 3) No NSFW posts\n\n- **No NSFW and NSFL content** \n\n This includes content that is sexual in nature, gory, anything unpalatable to the eyes.  \n\n- **Don't post pictures of private parts**\n\n Honestly, nobody comes here to see magnum dongs. Just don't.\n\n- **Don't post pictures of shit**\n\n No one wants to see that.  No dung, no dong. Dings are allowed.     \n\n#### 4) No Recent or Common reposts\n\n  - Frequent reposts or those from last 60 days or top 50 posts of all time will be removed.\n\n  - Moderators reserve the right to remove any posts they feel will improve the quality of this sub\n\n\n\n\n###Commenting\n\n####5) Be nice.  \n\n - **There's no reason to be an unfriendly unit**.\n\n -  **Excessively derogatory comments are not allowed**.\n\n - **Toxic behavior of any kind is banned**.\n\n - **Follow the site-wide rules / general [Rediquette](https://reddit.zendesk.com/hc/en-us/articles/205926439-Reddiquette)**\n\n####6) No doxing or brigading \n\n - **No witch hunts**.\n\n - **Do not direct link any personal information or social media profiles**.\n\n - **No brigading to or from any other threads, whether on or off Reddit**.     \n\n#### 7) Shut up about pitbulls \n\n - **No pitbull hate comments, stats, copypasta, links or calls to ban.**\n\n This is a place to enjoy Absolute Units.  Not to discuss your hate for any specific breeds, spamming stats and starting flame wars about whether or not they are dangerous.  If you love pitbulls, please visit r/pitbulls.  If you hate them, please visit r/banpitbulls.   \n\n Now please kindly shut up about it, or risk being banned. \n\n#### 8) Post titles must start with the string \"of \".\n\nPlease note that the word \"of\" is **case sensitive**.\n\n\n\n\n#### Don't be the guy that makes us add more rules\n - \n\n The moderators of this subreddit will take any action (which includes banning and removing comments) that they feel improves the quality of the subreddit.  \n\n---\n\n#OUR FRIENDS:\n\n\n-  **/r/Adoptableunits**\n\n\n-  **/r/Chonkers**\n\n\n-  **/r/PeepingPooch**\n\n\n-  **/r/TinyUnits**\n\n---\n\n#HEALTH:\n\nWe are in awe at the size of Absolute Units, and the only thing we love more is a fine lad who used to be an Absolute Unit and has become healthy! \n\n- [The American Veterinary Medical Association](https://www.avma.org/public/PetCare/Pages/yourpetshealthyweight.aspx) (AVMA) says \"Even a modest reduction in weight can significantly reduce your pet’s risk of life-threatening diseases.\" \n\n- [Pet Weight Calculator](https://www.petmd.com/healthyweight)",
      "iconUrl": "https://styles.redditmedia.com/t5_a7wuv/styles/communityIcon_t3cspt08bl681.png?width=256&s=a44312a0b6611844daea17277b70bcbdc23961ae",
      "bannerUrl": "https://styles.redditmedia.com/t5_a7wuv/styles/bannerBackgroundImage_6dyzaasgzdag1.png?width=4000&s=13383688b7c6aada983cf92990591f1d5c9bcc67",
      "advertiserCategory": "",
      "submitText": "",
      "createdAt": "2018-01-05T10:35:24.000Z"
    },
    "metrics": {
      "subscribers": 2039745,
      "weeklyActiveUsers": 2374665,
      "weeklyContributions": 19793
    }
  },
  "meta": {
    "requestId": "req_01example",
    "creditsCharged": 1,
    "version": "v1"
  }
}
```

### Example JSON (not_found)

```json
{
  "data": {
    "lookupStatus": "not_found",
    "subreddit": null,
    "metrics": null
  },
  "meta": {
    "requestId": "req_01example_nf",
    "creditsCharged": 1,
    "version": "v1"
  }
}
```

### Machine-readable error codes

When an error JSON body is returned, it may include one of these `error.code` values (derived from the OpenAPI schemas for this operation; additional codes may exist at runtime):

- `bad_request`

## Error handling & retries

Interpret HTTP status codes using the descriptions below. Do not assume a JSON body unless the OpenAPI schema defines one for that status.

- **400**: Invalid query or bad request **Retry:** Fix the request; retrying the same invalid payload will not help.
- **401**: Missing or invalid API key **Retry:** Fix the API key first; retrying without changes will not help.
- **402**: Insufficient credits **Retry:** Do not retry without resolving billing/credits (retrying the same request will not help).
- **500**: Unexpected or billing error
- **502**: Lookup could not be completed from the response (unexpected or invalid data). **Retry:** May be transient; a few retries with backoff are reasonable.
- **503**: Service temporarily unavailable; safe to retry with backoff. **Retry:** Usually safe to retry with exponential backoff and jitter.

### Suggested client defaults

- Send the API key using the `x-api-key` header on every request.
- On `503` (and sometimes `502`), retry with backoff; cap retries and surface a clear error to the user.
- On `402`, surface an actionable billing message rather than blind retries.

## Examples

### TypeScript SDK

```typescript
import { SocialFetchClient } from "@socialfetch/sdk";

const client = new SocialFetchClient({
  apiKey: process.env.SOCIALFETCH_API_KEY!,
});

const result = await client.reddit.getSubreddit({
  subreddit: "AbsoluteUnits",
});

if (!result.ok) {
  console.error(result.error);
} else {
  console.log(result.value.data);
}
```

### Node.js

```javascript
const response = await fetch(
  "https://api.socialfetch.dev/v1/reddit/subreddits",
  {
    headers: {
      "x-api-key": "YOUR_API_KEY",
    }
  }
);

const data = await response.json();
console.log(data);
```

### cURL

```bash
curl "https://api.socialfetch.dev/v1/reddit/subreddits" \
  -H "x-api-key: YOUR_API_KEY"
```

### Python

```python
import requests

response = requests.get(
    "https://api.socialfetch.dev/v1/reddit/subreddits",
    headers={"x-api-key": "YOUR_API_KEY"},
)
data = response.json()
print(data)
```