> 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://dashboard.pullbay.com/api`
## 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://dashboard.pullbay.com/api/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://dashboard.pullbay.com/api/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://dashboard.pullbay.com/api/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://dashboard.pullbay.com/api/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://dashboard.pullbay.com/api/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://dashboard.pullbay.com/api/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://dashboard.pullbay.com/api/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://dashboard.pullbay.com/api/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://dashboard.pullbay.com/api/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://dashboard.pullbay.com/api"
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
Why does sort accept different values on different endpoints?
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.
Can I paginate the comment or comment-replies endpoints?
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.
How do I get more than 200 results from a list endpoint?
`maxItems` is capped at 200 per call. For more, use `cursor`-based pagination across multiple requests instead of `maxItems`.
Can I use cursor and maxItems together?
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.
What's the credit cost per request?
It's dynamic — every response includes `pricing.creditsCharged` with the exact amount for that call. There's no fixed published rate per endpoint.
Do I need a Reddit account or API credentials from Reddit?
No. All endpoints return public Reddit data through Pullbay — you only need your Pullbay API key.
## 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.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.pullbay.com/documentation/api-and-references/reddit.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.