> 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/documentation/api-and-references/reddit.md).

# Reddit

The Pullbay Reddit API provides programmatic access to Reddit posts, comments, users, and subreddits. Search posts by keyword, pull a post's comment tree (and replies to any comment), look up a user's profile and their posts/comments, and look up a subreddit's profile and its posts — all without a Reddit account or OAuth app of your own.

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

## Overview

The Reddit service lets you:

* Search Reddit posts by keyword
* Look up a single post by its ID
* Fetch the comment tree on a post, and replies to any individual comment
* Look up a Reddit user's profile, plus the posts and comments they've authored
* Look up a subreddit's profile and the posts submitted to it

All endpoints are read-only `GET` requests against public Reddit data.

## Common Use Cases

**Topic Monitoring** — Use Search Posts on a schedule to track new discussion of a keyword, brand, or product across all of Reddit.

**Community Research** — Pull a subreddit's profile and recent posts to understand its size, rules, and the kind of content that performs well there.

**Sentiment & Discussion Analysis** — Fetch a post's comment tree (and drill into replies) to mine opinions, objections, and recurring questions around a topic.

**Influencer / Contributor Tracking** — Use Get User Posts and Get User Comments to see everything a specific Redditor has published, useful for vetting contributors or tracking a known voice in a community.

**Competitive & Market Intelligence** — Combine Search Posts with Get Subreddit Posts to see how a topic is discussed both broadly and within a specific community.

## 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 | Default | Description                                                                                      |
| ---------- | ------- | -------- | ------- | ------------------------------------------------------------------------------------------------ |
| `keyword`  | string  | Yes      | —       | Search term, 1–100 characters                                                                    |
| `sort`     | string  | No       | —       | `relevance`, `hot`, `top`, `new`, or `comments`                                                  |
| `maxItems` | integer | No       | —       | One-shot bulk pull, 1–200 results. Mutually exclusive with `cursor`                              |
| `cursor`   | string  | No       | —       | Pagination cursor from a previous response, 1–100 characters. Mutually exclusive with `maxItems` |

**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 }
}
```

**Response Schema**

| Field                    | Type   | Description                                                                                       |
| ------------------------ | ------ | ------------------------------------------------------------------------------------------------- |
| `data`                   | array  | Array of [Post objects](#post-object)                                                             |
| `pagination`             | object | Pagination info — see [Sort Values Reference](#sort-values-reference) note below for cursor usage |
| `pricing.creditsCharged` | number | Credits charged for this request                                                                  |

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. No published flat rate.

***

### 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 | Default | 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 }
}
```

**Response Schema**

| Field                    | Type   | Description                                           |
| ------------------------ | ------ | ----------------------------------------------------- |
| `data`                   | array  | Array containing a single [Post object](#post-object) |
| `pricing.creditsCharged` | number | Credits charged for this request                      |

Note: this endpoint's response has no `pagination` field and accepts no `sort` parameter.

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

***

### 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 | Default | 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 }
}
```

**Response Schema**

| Field                    | Type   | Description                                 |
| ------------------------ | ------ | ------------------------------------------- |
| `data`                   | array  | Array of [Comment objects](#comment-object) |
| `pricing.creditsCharged` | number | Credits charged for this request            |

Note: despite returning an array of comments, this endpoint's response has **no** `pagination` field — the full top-level comment tree is returned in one call.

**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 | Default | 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 }
}
```

**Response Schema**

| Field                    | Type   | Description                                 |
| ------------------------ | ------ | ------------------------------------------- |
| `data`                   | array  | Array of [Comment objects](#comment-object) |
| `pricing.creditsCharged` | number | Credits charged for this request            |

Note: this endpoint's response also has **no** `pagination` field.

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

***

### 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 | Default | 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 }
}
```

**Response Schema**

| Field                    | Type   | Description                                           |
| ------------------------ | ------ | ----------------------------------------------------- |
| `data`                   | array  | Array containing a single [User object](#user-object) |
| `pricing.creditsCharged` | number | Credits charged for this request                      |

Note: this endpoint's response has no `pagination` field and accepts no `sort` parameter.

**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 | Default | 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`                                                                           |
| `maxItems` | integer       | No       | —       | One-shot bulk pull, 1–200 results. Mutually exclusive with `cursor`                              |
| `cursor`   | string        | No       | —       | Pagination cursor from a previous response, 1–100 characters. Mutually exclusive with `maxItems` |

**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 }
}
```

**Response Schema**

| Field                    | Type   | Description                                                                                       |
| ------------------------ | ------ | ------------------------------------------------------------------------------------------------- |
| `data`                   | array  | Array of [Post objects](#post-object)                                                             |
| `pagination`             | object | Pagination info — see [Sort Values Reference](#sort-values-reference) note below for cursor usage |
| `pricing.creditsCharged` | number | Credits charged for this request                                                                  |

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

***

### 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 | Default | 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`                                                                           |
| `maxItems` | integer       | No       | —       | One-shot bulk pull, 1–200 results. Mutually exclusive with `cursor`                              |
| `cursor`   | string        | No       | —       | Pagination cursor from a previous response, 1–100 characters. Mutually exclusive with `maxItems` |

**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 }
}
```

**Response Schema**

| Field                    | Type   | Description                                                                                       |
| ------------------------ | ------ | ------------------------------------------------------------------------------------------------- |
| `data`                   | array  | Array of [Comment objects](#comment-object)                                                       |
| `pagination`             | object | Pagination info — see [Sort Values Reference](#sort-values-reference) note below for cursor usage |
| `pricing.creditsCharged` | number | Credits charged for this request                                                                  |

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

***

### 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 | Default | 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 }
}
```

**Response Schema**

| Field                    | Type   | Description                                                     |
| ------------------------ | ------ | --------------------------------------------------------------- |
| `data`                   | array  | Array containing a single [Subreddit object](#subreddit-object) |
| `pricing.creditsCharged` | number | Credits charged for this request                                |

Note: this endpoint's response has no `pagination` field and accepts no `sort` parameter.

**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 | Default | 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`                                                                           |
| `maxItems` | integer       | No       | —       | One-shot bulk pull, 1–200 results. Mutually exclusive with `cursor`                              |
| `cursor`   | string        | No       | —       | Pagination cursor from a previous response, 1–100 characters. Mutually exclusive with `maxItems` |

**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 }
}
```

**Response Schema**

| Field                    | Type   | Description                                                                                       |
| ------------------------ | ------ | ------------------------------------------------------------------------------------------------- |
| `data`                   | array  | Array of [Post objects](#post-object)                                                             |
| `pagination`             | object | Pagination info — see [Sort Values Reference](#sort-values-reference) note below for cursor usage |
| `pricing.creditsCharged` | number | Credits charged for this request                                                                  |

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

***

## 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 |

## Object Schema

### 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](#author-object)                           |
| `subreddit`                                                                                                                   | object                 | See [Subreddit Reference object](#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](#author-object)                           |
| `subreddit`                                                                            | object                 | See [Subreddit Reference object](#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`) |

## Finding Post and Comment 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 Posts endpoint is the fastest way to discover post IDs for a topic without already knowing a permalink.

## Sort Values Reference

The `sort` parameter is **not** a single global enum — it has three different, non-overlapping value sets depending on which endpoint you're calling. Using a value from the wrong scope (e.g. passing `qa` to Search Posts, or `relevance` to Get Subreddit Posts) is invalid.

**Scope A — Search Posts only**

Endpoint: `GET /reddit/search/post`

Values: `relevance`, `hot`, `top`, `new`, `comments`

This scope is unique to the search endpoint and is not valid anywhere else.

**Scope B — Comment-fetching endpoints**

Endpoints: `GET /reddit/post/{id}/comments` and `GET /reddit/post/{id}/comments/{commentId}/replies`

Values: `best`, `top`, `new`, `controversial`, `old`, `qa`

This scope applies only to the two endpoints that return comments. It is not valid for post-search or for the "list by user/subreddit" endpoints below.

**Scope C — "List by user/subreddit" endpoints**

Endpoints: `GET /reddit/user/{username}/posts`, `GET /reddit/user/{username}/comments`, `GET /reddit/subreddit/{name}/posts`

Values: `hot`, `top`, `new`

This scope is shared by the three endpoints that list a user's or subreddit's posts/comments. Note that `top` and `new` happen to overlap in name with values from Scope A and Scope B, but each endpoint only accepts the values listed in its own scope above — overlap in spelling does not mean the scopes are interchangeable.

| Endpoint                                             | Sort scope | Accepted values                                    |
| ---------------------------------------------------- | ---------- | -------------------------------------------------- |
| `GET /reddit/search/post`                            | A          | `relevance`, `hot`, `top`, `new`, `comments`       |
| `GET /reddit/post/{id}/comments`                     | B          | `best`, `top`, `new`, `controversial`, `old`, `qa` |
| `GET /reddit/post/{id}/comments/{commentId}/replies` | B          | `best`, `top`, `new`, `controversial`, `old`, `qa` |
| `GET /reddit/user/{username}/posts`                  | C          | `hot`, `top`, `new`                                |
| `GET /reddit/user/{username}/comments`               | C          | `hot`, `top`, `new`                                |
| `GET /reddit/subreddit/{name}/posts`                 | C          | `hot`, `top`, `new`                                |

The remaining three endpoints (`GET /reddit/post/{id}`, `GET /reddit/user/{username}`, `GET /reddit/subreddit/{name}`) take no `sort` parameter at all — each returns a single resource, not a list.

## Python Example

This example searches for posts matching a keyword and pages through results using `cursor`, stopping when no further cursor is returned:

```python
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.pullbay.com"

def search_all_posts(keyword, sort="new", max_pages=10):
    all_posts = []
    cursor = None
    page = 0
    while page < max_pages:
        params = {"keyword": keyword, "sort": sort}
        if cursor:
            params["cursor"] = cursor
        resp = requests.get(
            f"{BASE_URL}/reddit/search/post",
            headers={"Authorization": f"Bearer {API_KEY}"},
            params=params,
        )
        resp.raise_for_status()
        body = resp.json()
        all_posts.extend(body["data"])
        cursor = body.get("pagination", {}).get("cursor")
        if not cursor:
            break
        page += 1
    return all_posts

posts = search_all_posts("javascript")
print(f"Fetched {len(posts)} posts")
```

Each request is billed independently, with the charged amount reported in that response's `pricing.creditsCharged`.

## FAQ

<details>

<summary>Why does <code>sort</code> accept different values on different endpoints?</summary>

Reddit itself exposes different sort orders for search results, comment threads, and post/comment listings — Pullbay passes these through as-is rather than normalizing them into one shared list. See [Sort Values Reference](#sort-values-reference) for the exact values per endpoint.

</details>

<details>

<summary>Can I paginate the comment or comment-replies endpoints?</summary>

No. `GET /reddit/post/{id}/comments` and `GET /reddit/post/{id}/comments/{commentId}/replies` return their full result in a single response with no `pagination` field — there's nothing to page through.

</details>

<details>

<summary>How do I get more than 200 results from a list endpoint?</summary>

`maxItems` is capped at 200 per call. For more, use `cursor`-based pagination across multiple requests instead of `maxItems`.

</details>

<details>

<summary>Can I use <code>cursor</code> and <code>maxItems</code> together?</summary>

No, they're mutually exclusive on every endpoint that supports them. Use `cursor` to page manually or `maxItems` for a single bulk pull, not both in the same request.

</details>

<details>

<summary>What's the credit cost per request?</summary>

It's dynamic — every response includes `pricing.creditsCharged` with the exact amount for that call. There's no fixed published rate per endpoint.

</details>

<details>

<summary>Do I need a Reddit account or API credentials from Reddit?</summary>

No. All endpoints return public Reddit data through Pullbay — you only need your Pullbay API key.

</details>

## Next Steps

* [**API Integration Guide**](broken://pages/68e75ab1a73d266350bd68301be87ff97cad563e) — integrate the Pullbay API into your backend application.
* [**n8n Integration Guide**](broken://pages/4308164455b56bbc694cf74c9768ea689c2fe719) — set up automated workflows using n8n with no coding required.
* [**Services Overview**](broken://pages/0d55376cbcca70097a683a71a593d3077825dbf1) — explore all available Pullbay services.