> For the complete documentation index, see [llms.txt](https://docs.pullbay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pullbay.com/api-reference/endpoints/reddit.md).

# Reddit

Reddit: posts, comments, users, and subreddits. All endpoints are read-only `GET` requests and return public Reddit data — no Reddit account or OAuth app of your own is required.

**Base URL:** `https://api.pullbay.com/`

## Endpoints

| Endpoint                                             | Description                          | Pagination        |
| ---------------------------------------------------- | ------------------------------------ | ----------------- |
| `GET /reddit/search/post`                            | Search Reddit posts by keyword       | Cursor / maxItems |
| `GET /reddit/post/{id}`                              | Get a single post by ID              | —                 |
| `GET /reddit/post/{id}/comments`                     | Get the top-level comments on a post | —                 |
| `GET /reddit/post/{id}/comments/{commentId}/replies` | Get replies to a comment             | —                 |
| `GET /reddit/user/{username}`                        | Get a user profile by username       | —                 |
| `GET /reddit/user/{username}/posts`                  | Get posts submitted by a user        | Cursor / maxItems |
| `GET /reddit/user/{username}/comments`               | Get comments authored by a user      | Cursor / maxItems |
| `GET /reddit/subreddit/{name}`                       | Get a subreddit profile              | —                 |
| `GET /reddit/subreddit/{name}/posts`                 | Get posts from a subreddit           | Cursor / maxItems |

***

## Search Posts

Search Reddit posts by keyword.

**Request**

```bash
GET /reddit/search/post
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter  | Type    | Required | Description                                                                    |
| ---------- | ------- | -------- | ------------------------------------------------------------------------------ |
| `keyword`  | string  | Yes      | Search term, 1–100 characters                                                  |
| `sort`     | string  | No       | `relevance` (default), `hot`, `top`, `new`, or `comments`                      |
| `cursor`   | string  | No       | Pagination cursor from a previous response. Mutually exclusive with `maxItems` |
| `maxItems` | integer | No       | One-shot bulk pull, 1–200 results. Mutually exclusive with `cursor`            |

**Example**

```bash
curl -G "https://api.pullbay.com/reddit/search/post" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d keyword="javascript" \
  -d sort=new
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "type": "post",
      "id": "1qclvp3",
      "title": "Is learning JavaScript still a good decision in 2026?",
      "text": "",
      "textHTML": "",
      "url": "/r/learnprogramming/comments/1qclvp3/is_learning_javascript_still_a_good_decision_in/",
      "created": 1768393294,
      "editedAt": false,
      "score": 11,
      "upvotes": 11,
      "downvotes": 0,
      "upvoteRatio": 0.68,
      "numComments": 51,
      "viewCount": null,
      "goldCount": 0,
      "numCrossposts": 0,
      "isLocked": false,
      "isStickied": false,
      "isArchived": false,
      "isOriginalContent": false,
      "isCrosspostable": false,
      "isNSFW": false,
      "isSpoiler": false,
      "isMediaOnly": false,
      "isSponsored": false,
      "isMeta": false,
      "isGildable": false,
      "isScoreHidden": false,
      "contestMode": false,
      "hidden": false,
      "sendReplies": true,
      "author": {
        "id": "t2_1w72",
        "username": "spez",
        "isBlocked": false,
        "isDeleted": false
      },
      "subreddit": {
        "id": "t5_2fwo",
        "name": "learnprogramming",
        "prefixedName": "r/learnprogramming",
        "type": "public"
      },
      "flair": null,
      "thumbnail": {},
      "preview": {},
      "awards": [],
      "flairs": [],
      "gallery": [],
      "crosspostParents": []
    }
  ],
  "pagination": { "page": null, "hasNextPage": null, "cursor": null, "offset": null },
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. Using `maxItems` to pull more results in one call costs proportionally more than a single page.

***

## Get Post

Returns a single Reddit post by its ID.

**Request**

```bash
GET /reddit/post/{id}
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter | Type          | Required | Description                                                     |
| --------- | ------------- | -------- | --------------------------------------------------------------- |
| `id`      | string (path) | Yes      | Post ID, 1–32 characters. Substitute directly into the URL path |

**Example**

```bash
curl -G "https://api.pullbay.com/reddit/post/1qclvp3" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "type": "post",
      "id": "1qclvp3",
      "title": "Is learning JavaScript still a good decision in 2026?",
      "text": "",
      "textHTML": "",
      "url": "/r/learnprogramming/comments/1qclvp3/is_learning_javascript_still_a_good_decision_in/",
      "created": 1768393294,
      "editedAt": false,
      "score": 11,
      "upvotes": 11,
      "downvotes": 0,
      "upvoteRatio": 0.68,
      "numComments": 51,
      "viewCount": null,
      "goldCount": 0,
      "numCrossposts": 0,
      "isLocked": false,
      "isStickied": false,
      "isArchived": false,
      "isOriginalContent": false,
      "isCrosspostable": false,
      "isNSFW": false,
      "isSpoiler": false,
      "isMediaOnly": false,
      "isSponsored": false,
      "isMeta": false,
      "isGildable": false,
      "isScoreHidden": false,
      "contestMode": false,
      "hidden": false,
      "sendReplies": true,
      "author": {
        "id": "t2_1w72",
        "username": "spez",
        "isBlocked": false,
        "isDeleted": false
      },
      "subreddit": {
        "id": "t5_2fwo",
        "name": "learnprogramming",
        "prefixedName": "r/learnprogramming",
        "type": "public"
      },
      "flair": null,
      "thumbnail": {},
      "preview": {},
      "awards": [],
      "flairs": [],
      "gallery": [],
      "crosspostParents": []
    }
  ],
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`.

***

## Comments

### Get Post Comments

Returns the top-level comment tree for a Reddit post.

**Request**

```bash
GET /reddit/post/{id}/comments
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter | Type          | Required | Description                                                     |
| --------- | ------------- | -------- | --------------------------------------------------------------- |
| `id`      | string (path) | Yes      | Post ID, 1–32 characters. Substitute directly into the URL path |
| `sort`    | string        | No       | `best`, `top`, `new`, `controversial`, `old`, or `qa`           |

**Example**

```bash
curl -G "https://api.pullbay.com/reddit/post/1t0jood/comments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d sort=top
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "type": "comment",
      "id": "ojb40kw",
      "postId": "t3_1t0jood",
      "parentId": "t3_1t0jood",
      "body": "That was Rich Greenfield from LightShed.",
      "bodyHTML": "",
      "url": "/r/redditstock/comments/1t0jood/.../ojb40kw/",
      "createdAt": 1777638722,
      "editedAt": false,
      "score": 24,
      "upvotes": 24,
      "downvotes": 0,
      "goldCount": 0,
      "totalAwardsReceived": 0,
      "controversiality": 0,
      "isLocked": false,
      "isStickied": false,
      "isArchived": false,
      "isSaved": false,
      "isScoreHidden": false,
      "isCollapsed": false,
      "noFollow": false,
      "sendReplies": true,
      "hasReplies": false,
      "author": {
        "id": "t2_1w72",
        "username": "spez",
        "isBlocked": false,
        "isDeleted": false
      },
      "subreddit": {
        "id": "t5_2fwo",
        "name": "redditstock",
        "prefixedName": "r/redditstock",
        "type": "public"
      },
      "awards": []
    }
  ],
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`.

***

### Get Comment Replies

Returns replies to a specific comment on a Reddit post.

**Request**

```bash
GET /reddit/post/{id}/comments/{commentId}/replies
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter   | Type          | Required | Description                                                        |
| ----------- | ------------- | -------- | ------------------------------------------------------------------ |
| `id`        | string (path) | Yes      | Post ID, 1–32 characters. Substitute directly into the URL path    |
| `commentId` | string (path) | Yes      | Comment ID, 1–32 characters. Substitute directly into the URL path |
| `sort`      | string        | No       | `best`, `top`, `new`, `controversial`, `old`, or `qa`              |

**Example**

```bash
curl -G "https://api.pullbay.com/reddit/post/1t0jood/comments/ojb40kw/replies" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d sort=best
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "type": "comment",
      "id": "ojb4abc",
      "postId": "t3_1t0jood",
      "parentId": "t1_ojb40kw",
      "body": "Source on that?",
      "bodyHTML": "",
      "url": "/r/redditstock/comments/1t0jood/.../ojb4abc/",
      "createdAt": 1777639022,
      "editedAt": false,
      "score": 4,
      "upvotes": 4,
      "downvotes": 0,
      "goldCount": 0,
      "totalAwardsReceived": 0,
      "controversiality": 0,
      "isLocked": false,
      "isStickied": false,
      "isArchived": false,
      "isSaved": false,
      "isScoreHidden": false,
      "isCollapsed": false,
      "noFollow": false,
      "sendReplies": true,
      "hasReplies": false,
      "author": {
        "id": "t2_9f21",
        "username": "throwaway_invest",
        "isBlocked": false,
        "isDeleted": false
      },
      "subreddit": {
        "id": "t5_2fwo",
        "name": "redditstock",
        "prefixedName": "r/redditstock",
        "type": "public"
      },
      "awards": []
    }
  ],
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`.

***

## Users

### Get User

Returns a Reddit user profile by username (without `u/`).

**Request**

```bash
GET /reddit/user/{username}
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter  | Type          | Required | Description                                                                                      |
| ---------- | ------------- | -------- | ------------------------------------------------------------------------------------------------ |
| `username` | string (path) | Yes      | Reddit username without the `u/` prefix, 1–100 characters. Substitute directly into the URL path |

**Example**

```bash
curl -G "https://api.pullbay.com/reddit/user/spez" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "type": "user",
      "id": "1w72",
      "name": "spez",
      "title": "spez",
      "description": "Reddit CEO",
      "createdAt": 1118030400,
      "iconImage": "https://styles.redditmedia.com/t5_3k30p/styles/profileIcon_uj015iwx9s7g1.png",
      "snoovatarImage": "",
      "bannerImage": "https://b.thumbs.redditmedia.com/KWeEpVxXOGLoloMbM0IxGt9EiKPXizpwFgcSeWqtpZM.png",
      "awarderKarma": 0,
      "postKarma": 182496,
      "commentKarma": 755311,
      "totalKarma": 937807,
      "hasVerifiedEmail": true,
      "over18": false
    }
  ],
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`.

***

### Get User Posts

Returns posts submitted by a Reddit user.

**Request**

```bash
GET /reddit/user/{username}/posts
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter  | Type          | Required | Description                                                                                      |
| ---------- | ------------- | -------- | ------------------------------------------------------------------------------------------------ |
| `username` | string (path) | Yes      | Reddit username without the `u/` prefix, 1–100 characters. Substitute directly into the URL path |
| `sort`     | string        | No       | `hot`, `top`, or `new`                                                                           |
| `cursor`   | string        | No       | Pagination cursor from a previous response. Mutually exclusive with `maxItems`                   |
| `maxItems` | integer       | No       | One-shot bulk pull, 1–200 results. Mutually exclusive with `cursor`                              |

**Example**

```bash
curl -G "https://api.pullbay.com/reddit/user/spez/posts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d sort=new \
  -d maxItems=50
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    { "type": "post", "id": "1qclvp3", "title": "Is learning JavaScript still a good decision in 2026?", "...": "..." }
  ],
  "pagination": { "page": null, "hasNextPage": null, "cursor": null, "offset": null },
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. Using `maxItems` to pull more results in one call costs proportionally more than a single page.

***

### Get User Comments

Returns comments authored by a Reddit user.

**Request**

```bash
GET /reddit/user/{username}/comments
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter  | Type          | Required | Description                                                                                      |
| ---------- | ------------- | -------- | ------------------------------------------------------------------------------------------------ |
| `username` | string (path) | Yes      | Reddit username without the `u/` prefix, 1–100 characters. Substitute directly into the URL path |
| `sort`     | string        | No       | `hot`, `top`, or `new`                                                                           |
| `cursor`   | string        | No       | Pagination cursor from a previous response. Mutually exclusive with `maxItems`                   |
| `maxItems` | integer       | No       | One-shot bulk pull, 1–200 results. Mutually exclusive with `cursor`                              |

**Example**

```bash
curl -G "https://api.pullbay.com/reddit/user/spez/comments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d sort=top \
  -d cursor=eyJhZnRlciI6InQxX29qYjQwa3cifQ
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    { "type": "comment", "id": "ojb40kw", "body": "That was Rich Greenfield from LightShed.", "...": "..." }
  ],
  "pagination": { "page": null, "hasNextPage": null, "cursor": null, "offset": null },
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. Using `maxItems` to pull more results in one call costs proportionally more than a single page.

***

## Subreddits

### Get Subreddit

Returns a subreddit profile by its name (without `r/`).

**Request**

```bash
GET /reddit/subreddit/{name}
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter | Type          | Required | Description                                                                                     |
| --------- | ------------- | -------- | ----------------------------------------------------------------------------------------------- |
| `name`    | string (path) | Yes      | Subreddit name without the `r/` prefix, 1–100 characters. Substitute directly into the URL path |

**Example**

```bash
curl -G "https://api.pullbay.com/reddit/subreddit/programming" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "type": "subreddit",
      "id": "2fwo",
      "name": "programming",
      "prefixedName": "r/programming",
      "title": "programming",
      "subType": "public",
      "description": "/r/programming is a reddit for discussion and news about computer programming.",
      "descriptionHtml": "",
      "publicDescription": "Computer Programming",
      "publicDescriptionHtml": "",
      "submitText": "",
      "submitTextHtml": null,
      "submissionType": "link",
      "advertiserCategory": "Technology",
      "language": "en",
      "url": "/r/programming/",
      "headerTitle": "",
      "iconImage": "",
      "iconSize": null,
      "bannerImage": "",
      "bannerBackgroundImage": "",
      "bannerSize": null,
      "headerImage": "https://b.thumbs.redditmedia.com/2rTE46grzsr-Ll3Q.png",
      "headerSize": [120, 40],
      "primaryColor": "#002b36",
      "keyColor": "",
      "createdAt": 1141150769,
      "subscribers": 6873180,
      "commentScoreHideMins": 0,
      "notificationLevel": null,
      "suggestedCommentSort": null,
      "userFlairEnabled": true,
      "linkFlairEnabled": true,
      "wikiEnabled": true,
      "emojisEnabled": false,
      "spoilersEnabled": true,
      "allowImages": false,
      "allowVideos": false,
      "allowGalleries": false,
      "allowPolls": false,
      "allowPredictions": false,
      "allowTalks": false,
      "allowDiscovery": true,
      "isCrosspostable": false,
      "publicTraffic": false,
      "showMediaPreview": true,
      "showMedia": false,
      "collapseDeletedComments": false,
      "shouldArchivePosts": false,
      "canAssignUserFlair": false,
      "canAssignLinkFlair": false,
      "restrictCommenting": false,
      "restrictPosting": true,
      "communityReviewed": true,
      "flairPosition": "right",
      "linkFlairPosition": "right"
    }
  ],
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`.

***

### Get Subreddit Posts

Returns posts from a subreddit.

**Request**

```bash
GET /reddit/subreddit/{name}/posts
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter  | Type          | Required | Description                                                                                     |
| ---------- | ------------- | -------- | ----------------------------------------------------------------------------------------------- |
| `name`     | string (path) | Yes      | Subreddit name without the `r/` prefix, 1–100 characters. Substitute directly into the URL path |
| `sort`     | string        | No       | `hot`, `top`, or `new`                                                                          |
| `cursor`   | string        | No       | Pagination cursor from a previous response. Mutually exclusive with `maxItems`                  |
| `maxItems` | integer       | No       | One-shot bulk pull, 1–200 results. Mutually exclusive with `cursor`                             |

**Example**

```bash
curl -G "https://api.pullbay.com/reddit/subreddit/programming/posts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d sort=hot
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    { "type": "post", "id": "1qclvp3", "title": "Is learning JavaScript still a good decision in 2026?", "...": "..." }
  ],
  "pagination": { "page": null, "hasNextPage": null, "cursor": null, "offset": null },
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. Using `maxItems` to pull more results in one call costs proportionally more than a single page.

***

## Object schemas

### Post object

| Field                                                                                                                         | Type                   | Description                                   |
| ----------------------------------------------------------------------------------------------------------------------------- | ---------------------- | --------------------------------------------- |
| `type`                                                                                                                        | string                 | Always `post`                                 |
| `id`                                                                                                                          | string                 | Post ID                                       |
| `title`                                                                                                                       | string                 | Post title                                    |
| `text`                                                                                                                        | string                 | Self-text body (empty for link posts)         |
| `textHTML`                                                                                                                    | string                 | Rendered HTML of the self-text body           |
| `url`                                                                                                                         | string                 | Relative permalink to the post                |
| `created`                                                                                                                     | integer (unix seconds) | Submission timestamp                          |
| `editedAt`                                                                                                                    | integer or boolean     | Edit timestamp, or `false` if never edited    |
| `score`                                                                                                                       | integer                | Net score (upvotes minus downvotes)           |
| `upvotes` / `downvotes`                                                                                                       | integer                | Vote counts                                   |
| `upvoteRatio`                                                                                                                 | number                 | Fraction of votes that are upvotes            |
| `numComments`                                                                                                                 | integer                | Total comment count                           |
| `viewCount`                                                                                                                   | integer, nullable      | View count, when available                    |
| `goldCount`                                                                                                                   | integer                | Number of Reddit Gold awards                  |
| `numCrossposts`                                                                                                               | integer                | Number of crossposts of this post             |
| `isLocked` / `isStickied` / `isArchived`                                                                                      | boolean                | Moderation/state flags                        |
| `isOriginalContent` / `isCrosspostable`                                                                                       | boolean                | Content flags                                 |
| `isNSFW` / `isSpoiler` / `isMediaOnly` / `isSponsored` / `isMeta` / `isGildable` / `isScoreHidden` / `contestMode` / `hidden` | boolean                | Additional content/state flags                |
| `sendReplies`                                                                                                                 | boolean                | Whether the author allows reply notifications |
| `author`                                                                                                                      | object                 | See Author object                             |
| `subreddit`                                                                                                                   | object                 | See Subreddit Reference object                |
| `flair`                                                                                                                       | object, nullable       | Link flair, when set                          |
| `thumbnail`                                                                                                                   | object                 | Thumbnail image metadata                      |
| `preview`                                                                                                                     | object                 | Preview image/media metadata                  |
| `awards`                                                                                                                      | array                  | Awards given to the post                      |
| `flairs`                                                                                                                      | array                  | Available flair templates                     |
| `gallery`                                                                                                                     | array                  | Gallery media items, for gallery posts        |
| `crosspostParents`                                                                                                            | array                  | Parent post(s), for crossposts                |

### Comment object

| Field                                                                                  | Type                   | Description                                   |
| -------------------------------------------------------------------------------------- | ---------------------- | --------------------------------------------- |
| `type`                                                                                 | string                 | Always `comment`                              |
| `id`                                                                                   | string                 | Comment ID                                    |
| `postId`                                                                               | string                 | Fullname of the post the comment belongs to   |
| `parentId`                                                                             | string                 | Fullname of the parent (post or comment)      |
| `body`                                                                                 | string                 | Comment text                                  |
| `bodyHTML`                                                                             | string                 | Rendered HTML of the comment text             |
| `url`                                                                                  | string                 | Relative permalink to the comment             |
| `createdAt`                                                                            | integer (unix seconds) | When the comment was posted                   |
| `editedAt`                                                                             | integer or boolean     | Edit timestamp, or `false` if never edited    |
| `score`                                                                                | integer                | Net score (upvotes minus downvotes)           |
| `upvotes` / `downvotes`                                                                | integer                | Vote counts                                   |
| `goldCount`                                                                            | integer                | Number of Reddit Gold awards                  |
| `totalAwardsReceived`                                                                  | integer                | Total awards received                         |
| `controversiality`                                                                     | integer                | Reddit's controversiality flag (0 or 1)       |
| `isLocked` / `isStickied` / `isArchived` / `isSaved` / `isScoreHidden` / `isCollapsed` | boolean                | Moderation/state flags                        |
| `noFollow`                                                                             | boolean                | Whether links in the comment are `nofollow`   |
| `sendReplies`                                                                          | boolean                | Whether the author allows reply notifications |
| `hasReplies`                                                                           | boolean                | Whether this comment has reply comments       |
| `author`                                                                               | object                 | See Author object                             |
| `subreddit`                                                                            | object                 | See Subreddit Reference object                |
| `awards`                                                                               | array                  | Awards given to the comment                   |

### User object

| Field              | Type                   | Description                              |
| ------------------ | ---------------------- | ---------------------------------------- |
| `type`             | string                 | Always `user`                            |
| `id`               | string                 | User ID (without `t2_` prefix)           |
| `name`             | string                 | Username                                 |
| `title`            | string                 | Profile title (often same as username)   |
| `description`      | string                 | Profile bio/description                  |
| `createdAt`        | integer (unix seconds) | Account creation timestamp               |
| `iconImage`        | string                 | Avatar image URL                         |
| `snoovatarImage`   | string                 | Snoovatar image URL, if set              |
| `bannerImage`      | string                 | Profile banner image URL                 |
| `awarderKarma`     | integer                | Karma earned from giving awards          |
| `postKarma`        | integer                | Karma earned from posts                  |
| `commentKarma`     | integer                | Karma earned from comments               |
| `totalKarma`       | integer                | Combined karma total                     |
| `hasVerifiedEmail` | boolean                | Whether the account has a verified email |
| `over18`           | boolean                | Whether the account is marked NSFW       |

### Subreddit object

| Field                                                                                               | Type                     | Description                                           |
| --------------------------------------------------------------------------------------------------- | ------------------------ | ----------------------------------------------------- |
| `type`                                                                                              | string                   | Always `subreddit`                                    |
| `id`                                                                                                | string                   | Subreddit ID (without `t5_` prefix)                   |
| `name`                                                                                              | string                   | Subreddit name (without `r/`)                         |
| `prefixedName`                                                                                      | string                   | Subreddit name with `r/` prefix                       |
| `title`                                                                                             | string                   | Subreddit title                                       |
| `subType`                                                                                           | string                   | Subreddit visibility type (e.g. `public`)             |
| `description` / `descriptionHtml`                                                                   | string                   | Sidebar description, plain and HTML                   |
| `publicDescription` / `publicDescriptionHtml`                                                       | string                   | Short public description, plain and HTML              |
| `submitText` / `submitTextHtml`                                                                     | string, nullable         | Text shown on the submit page                         |
| `submissionType`                                                                                    | string                   | Allowed submission type (e.g. `link`, `self`, `any`)  |
| `advertiserCategory`                                                                                | string                   | Ad category classification                            |
| `language`                                                                                          | string                   | Subreddit's primary language code                     |
| `url`                                                                                               | string                   | Relative URL to the subreddit                         |
| `headerTitle`                                                                                       | string                   | Header link title                                     |
| `iconImage` / `iconSize`                                                                            | string / array, nullable | Icon image URL and dimensions                         |
| `bannerImage` / `bannerBackgroundImage` / `bannerSize`                                              | string / array, nullable | Banner images and dimensions                          |
| `headerImage` / `headerSize`                                                                        | string / array           | Header image URL and dimensions                       |
| `primaryColor` / `keyColor`                                                                         | string                   | Theme colors                                          |
| `createdAt`                                                                                         | integer (unix seconds)   | Subreddit creation timestamp                          |
| `subscribers`                                                                                       | integer                  | Subscriber count                                      |
| `commentScoreHideMins`                                                                              | integer                  | Minutes comment scores are hidden after posting       |
| `notificationLevel` / `suggestedCommentSort`                                                        | string, nullable         | User-specific notification setting and suggested sort |
| `userFlairEnabled` / `linkFlairEnabled`                                                             | boolean                  | Flair feature flags                                   |
| `wikiEnabled` / `emojisEnabled` / `spoilersEnabled`                                                 | boolean                  | Feature flags                                         |
| `allowImages` / `allowVideos` / `allowGalleries` / `allowPolls` / `allowPredictions` / `allowTalks` | boolean                  | Allowed content type flags                            |
| `allowDiscovery` / `isCrosspostable` / `publicTraffic`                                              | boolean                  | Discovery and traffic flags                           |
| `showMediaPreview` / `showMedia`                                                                    | boolean                  | Media display settings                                |
| `collapseDeletedComments` / `shouldArchivePosts`                                                    | boolean                  | Moderation settings                                   |
| `canAssignUserFlair` / `canAssignLinkFlair`                                                         | boolean                  | Flair assignment permissions                          |
| `restrictCommenting` / `restrictPosting`                                                            | boolean                  | Posting/commenting restrictions                       |
| `communityReviewed`                                                                                 | boolean                  | Whether the subreddit has passed community review     |
| `flairPosition` / `linkFlairPosition`                                                               | string                   | Flair display position (e.g. `right`)                 |

### Author object

Embedded in `Post` and `Comment` objects as the `author` field.

| Field       | Type    | Description                                             |
| ----------- | ------- | ------------------------------------------------------- |
| `id`        | string  | Author's user ID (fullname, e.g. `t2_1w72`)             |
| `username`  | string  | Author's username                                       |
| `isBlocked` | boolean | Whether the author is blocked by the requesting context |
| `isDeleted` | boolean | Whether the author's account has been deleted           |

### Subreddit Reference object

Embedded in `Post` and `Comment` objects as the `subreddit` field.

| Field          | Type   | Description                               |
| -------------- | ------ | ----------------------------------------- |
| `id`           | string | Subreddit ID (fullname, e.g. `t5_2fwo`)   |
| `name`         | string | Subreddit name (without `r/`)             |
| `prefixedName` | string | Subreddit name with `r/` prefix           |
| `type`         | string | Subreddit visibility type (e.g. `public`) |

***

## Errors

All non-2xx responses share the same envelope:

```json
{
  "status": 400,
  "message": "Bad request",
  "success": false,
  "error": { "code": "BAD_REQUEST" }
}
```

| Status | Meaning                                     |
| ------ | ------------------------------------------- |
| `400`  | Bad request — missing/invalid parameters    |
| `402`  | Insufficient credits                        |
| `404`  | Post, comment, user, or subreddit not found |

## Finding Post, Comment, User, and Subreddit IDs

* **Post ID**: the alphanumeric segment in a Reddit URL, e.g. `https://reddit.com/r/learnprogramming/comments/1qclvp3/...` → `1qclvp3`.
* **Comment ID**: the alphanumeric segment after the post ID in a comment permalink, e.g. `.../comments/1t0jood/some_title/ojb40kw/` → `ojb40kw`.
* **Username**: the part after `u/` in a profile URL, e.g. `https://reddit.com/u/spez` → `spez`. Pass it without the `u/` prefix.
* **Subreddit name**: the part after `r/` in a subreddit URL, e.g. `https://reddit.com/r/programming` → `programming`. Pass it without the `r/` prefix.
* The `search/post` endpoint is the fastest way to discover post IDs for a topic without already knowing a permalink.

## Pagination Notes

* List endpoints (`search/post`, `user/{username}/posts`, `user/{username}/comments`, `subreddit/{name}/posts`) use cursor-based pagination: pass the `cursor` value from a previous response's `pagination` object to fetch the next page.
* `maxItems` is a one-shot bulk-pull alternative to `cursor` — it returns up to the requested count of results in a single call (capped at 200) instead of paging manually. `cursor` and `maxItems` are mutually exclusive on every endpoint that supports them.
* Single-resource endpoints (`post/{id}`, `post/{id}/comments`, `post/{id}/comments/{commentId}/replies`, `user/{username}`, `subreddit/{name}`) return the full result in one call and have no pagination.