← Back to Reddit (Unofficial) docs
Reddit (Unofficial) — Tool Reference
Read Reddit via RedditAPI (redditapis.com), an unofficial pay-per-call proxy: search posts and communities, browse subreddits, fetch posts with comment trees, and user profiles.
Your AI assistant discovers and invokes these tools through the
MCP Server's meta tools —
it calls execute_tool with the tool name and arguments below.
# get_account_balance read
Check the remaining RedditAPI credit balance (free call).
Full description
Check the RedditAPI account's remaining credit and usage. Free (does not consume credit), rate-limited to 30 requests/minute. Useful before large multi-page fetches: reads cost $0.002 per call.
No parameters.
Parameter schema (JSON)
{
"description": "No parameters.",
"properties": {},
"title": "Empty",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"properties": {
"success": {
"default": true,
"title": "Success",
"type": "boolean"
},
"credits_remaining_usd": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Remaining RedditAPI credit in USD",
"title": "Credits Remaining Usd"
},
"credits_used_usd": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Lifetime credit spent in USD",
"title": "Credits Used Usd"
},
"total_requests": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Lifetime billed API calls",
"title": "Total Requests"
},
"reads_remaining_estimate": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Approximate GET reads left at $0.002 per call",
"title": "Reads Remaining Estimate"
}
},
"title": "AccountBalanceResult",
"type": "object"
} # get_post read
Get one Reddit post by ID with its full text ($0.002).
Full description
Fetch a single Reddit post by ID with full, untruncated text. One billed RedditAPI call ($0.002). For the post's comments, call get_post_comments with the same post_id or the returned permalink.
| Parameter | Type | Required | Description |
|---|---|---|---|
post_id | string | Yes | Reddit post ID, with or without the t3_ prefix |
Parameter schema (JSON)
{
"properties": {
"post_id": {
"description": "Reddit post ID, with or without the t3_ prefix",
"minLength": 1,
"title": "Post Id",
"type": "string"
}
},
"required": [
"post_id"
],
"title": "GetPostParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"Post": {
"properties": {
"id": {
"description": "Post ID without prefix (e.g. '1sgjld3')",
"title": "Id",
"type": "string"
},
"fullname": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Full ID with t3_ prefix; use as the after cursor",
"title": "Fullname"
},
"title": {
"default": "",
"description": "Post title",
"title": "Title",
"type": "string"
},
"author": {
"default": "",
"description": "Author username (no u/ prefix)",
"title": "Author",
"type": "string"
},
"author_flair": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Author's flair text in this subreddit",
"title": "Author Flair"
},
"subreddit": {
"default": "",
"description": "Subreddit name (no r/ prefix)",
"title": "Subreddit",
"type": "string"
},
"score": {
"default": 0,
"description": "Net votes (upvotes minus downvotes)",
"title": "Score",
"type": "integer"
},
"num_comments": {
"default": 0,
"description": "Comment count",
"title": "Num Comments",
"type": "integer"
},
"upvote_ratio": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Approximate upvote ratio",
"title": "Upvote Ratio"
},
"permalink": {
"default": "",
"description": "Path on reddit.com; pass to get_post_comments",
"title": "Permalink",
"type": "string"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Full reddit.com URL",
"title": "Url"
},
"link_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "External link or media URL; null for self/text posts",
"title": "Link Url"
},
"is_self": {
"default": false,
"description": "True for text/self posts",
"title": "Is Self",
"type": "boolean"
},
"over_18": {
"default": false,
"description": "NSFW flag",
"title": "Over 18",
"type": "boolean"
},
"stickied": {
"default": false,
"title": "Stickied",
"type": "boolean"
},
"locked": {
"default": false,
"title": "Locked",
"type": "boolean"
},
"spoiler": {
"default": false,
"title": "Spoiler",
"type": "boolean"
},
"is_crosspost": {
"default": false,
"title": "Is Crosspost",
"type": "boolean"
},
"crosspost_from": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Subreddit the post was crossposted from, if any",
"title": "Crosspost From"
},
"created": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Creation time, ISO 8601",
"title": "Created"
},
"text": {
"default": "",
"description": "Self-post body (empty for link/image posts)",
"title": "Text",
"type": "string"
},
"text_truncated": {
"default": false,
"description": "True if text was truncated; use get_post for the full body",
"title": "Text Truncated",
"type": "boolean"
}
},
"required": [
"id"
],
"title": "Post",
"type": "object"
}
},
"properties": {
"success": {
"default": true,
"title": "Success",
"type": "boolean"
},
"post": {
"$ref": "#/$defs/Post"
}
},
"required": [
"post"
],
"title": "PostResult",
"type": "object"
} # get_post_comments read
Fetch a Reddit post's comment tree, flattened with depth and parent links ($0.002).
Full description
Fetch a post plus its comment tree, flattened depth-first. Provide the post's permalink or its post_id (either is one billed call at $0.002; a post_id is resolved via Reddit's /comments/<id>/ shortlink form, verified live). Each comment carries depth and parent_id so the thread structure survives flattening; is_submitter marks the post author (OP). Reddit returns roughly the first 100 comments of a thread and the provider cannot page deeper: replies it left unloaded are counted in more_comments_hidden, and comments excluded by max_comments/max_depth are counted in comments_omitted.
| Parameter | Type | Required | Description |
|---|---|---|---|
permalink | string | null | No | Post permalink (e.g. /r/Python/comments/abc123/title/); full reddit.com URLs are accepted |
post_id | string | null | No | Post ID as an alternative to permalink |
max_comments | integer | No | Maximum comments to return after flattening Default: 100 |
max_depth | integer | null | No | Deepest reply level to include (0 = top-level only); default all |
body_max_chars | integer | No | Truncate each comment's body to this many characters Default: 500 |
Parameter schema (JSON)
{
"properties": {
"permalink": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Post permalink (e.g. /r/Python/comments/abc123/title/); full reddit.com URLs are accepted",
"title": "Permalink"
},
"post_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Post ID as an alternative to permalink",
"title": "Post Id"
},
"max_comments": {
"default": 100,
"description": "Maximum comments to return after flattening",
"maximum": 500,
"minimum": 1,
"title": "Max Comments",
"type": "integer"
},
"max_depth": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Deepest reply level to include (0 = top-level only); default all",
"title": "Max Depth"
},
"body_max_chars": {
"default": 500,
"description": "Truncate each comment's body to this many characters",
"maximum": 10000,
"minimum": 50,
"title": "Body Max Chars",
"type": "integer"
}
},
"title": "GetPostCommentsParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"FlatComment": {
"properties": {
"id": {
"description": "Comment ID",
"title": "Id",
"type": "string"
},
"parent_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Parent comment ID; null when the parent is the post itself. For comment-anchored permalinks the root comment may reference a parent outside this response.",
"title": "Parent Id"
},
"depth": {
"default": 0,
"description": "Nesting depth (0 = top-level)",
"title": "Depth",
"type": "integer"
},
"author": {
"default": "",
"title": "Author",
"type": "string"
},
"body": {
"default": "",
"description": "Comment text",
"title": "Body",
"type": "string"
},
"body_truncated": {
"default": false,
"title": "Body Truncated",
"type": "boolean"
},
"score": {
"default": 0,
"description": "Net votes",
"title": "Score",
"type": "integer"
},
"created": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Creation time, ISO 8601",
"title": "Created"
},
"is_submitter": {
"default": false,
"description": "True if the commenter is the post author (OP)",
"title": "Is Submitter",
"type": "boolean"
}
},
"required": [
"id"
],
"title": "FlatComment",
"type": "object"
},
"Post": {
"properties": {
"id": {
"description": "Post ID without prefix (e.g. '1sgjld3')",
"title": "Id",
"type": "string"
},
"fullname": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Full ID with t3_ prefix; use as the after cursor",
"title": "Fullname"
},
"title": {
"default": "",
"description": "Post title",
"title": "Title",
"type": "string"
},
"author": {
"default": "",
"description": "Author username (no u/ prefix)",
"title": "Author",
"type": "string"
},
"author_flair": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Author's flair text in this subreddit",
"title": "Author Flair"
},
"subreddit": {
"default": "",
"description": "Subreddit name (no r/ prefix)",
"title": "Subreddit",
"type": "string"
},
"score": {
"default": 0,
"description": "Net votes (upvotes minus downvotes)",
"title": "Score",
"type": "integer"
},
"num_comments": {
"default": 0,
"description": "Comment count",
"title": "Num Comments",
"type": "integer"
},
"upvote_ratio": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Approximate upvote ratio",
"title": "Upvote Ratio"
},
"permalink": {
"default": "",
"description": "Path on reddit.com; pass to get_post_comments",
"title": "Permalink",
"type": "string"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Full reddit.com URL",
"title": "Url"
},
"link_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "External link or media URL; null for self/text posts",
"title": "Link Url"
},
"is_self": {
"default": false,
"description": "True for text/self posts",
"title": "Is Self",
"type": "boolean"
},
"over_18": {
"default": false,
"description": "NSFW flag",
"title": "Over 18",
"type": "boolean"
},
"stickied": {
"default": false,
"title": "Stickied",
"type": "boolean"
},
"locked": {
"default": false,
"title": "Locked",
"type": "boolean"
},
"spoiler": {
"default": false,
"title": "Spoiler",
"type": "boolean"
},
"is_crosspost": {
"default": false,
"title": "Is Crosspost",
"type": "boolean"
},
"crosspost_from": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Subreddit the post was crossposted from, if any",
"title": "Crosspost From"
},
"created": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Creation time, ISO 8601",
"title": "Created"
},
"text": {
"default": "",
"description": "Self-post body (empty for link/image posts)",
"title": "Text",
"type": "string"
},
"text_truncated": {
"default": false,
"description": "True if text was truncated; use get_post for the full body",
"title": "Text Truncated",
"type": "boolean"
}
},
"required": [
"id"
],
"title": "Post",
"type": "object"
}
},
"properties": {
"success": {
"default": true,
"title": "Success",
"type": "boolean"
},
"post": {
"$ref": "#/$defs/Post"
},
"comments": {
"description": "Comment tree flattened depth-first; depth/parent_id preserve structure",
"items": {
"$ref": "#/$defs/FlatComment"
},
"title": "Comments",
"type": "array"
},
"total_returned": {
"default": 0,
"title": "Total Returned",
"type": "integer"
},
"comments_omitted": {
"default": 0,
"description": "Comments present in the response but excluded by max_comments or max_depth",
"title": "Comments Omitted",
"type": "integer"
},
"more_comments_hidden": {
"default": 0,
"description": "Replies Reddit left unloaded. The provider cannot fetch them (no comment-tree pagination).",
"title": "More Comments Hidden",
"type": "integer"
},
"truncated": {
"default": false,
"description": "True if max_comments or max_depth excluded comments",
"title": "Truncated",
"type": "boolean"
}
},
"required": [
"post"
],
"title": "PostCommentsResult",
"type": "object"
} # get_subreddit_posts read
Browse a subreddit's posts by sort tab: hot, new, top, rising, controversial, best ($0.002 per page).
Full description
Browse posts from one subreddit by Reddit sort tab. Each page is one billed RedditAPI call ($0.002); max_pages defaults to 1 and the after cursor lets you continue in a later call. The time filter only applies to sort=top and sort=controversial (default day). Post text is truncated to text_max_chars; use get_post for a full body.
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | integer | No | Results per page (1-100) Default: 25 |
after | string | null | No | Pagination cursor from a previous call |
max_pages | integer | No | Pages to fetch (1-4); each page is one billed call ($0.002) Default: 1 |
subreddit | string | Yes | Subreddit name (r/ prefix accepted) |
sort | "hot" | "new" | "top" | "rising" | "controversial" | "best" | No | Reddit sort tab Default: "hot" |
time | "hour" | "day" | "week" | "month" | "year" | "all" | null | No | Timeframe; only valid with sort=top or sort=controversial (default day for those) |
text_max_chars | integer | No | Truncate each post's text to this many characters Default: 500 |
Parameter schema (JSON)
{
"properties": {
"limit": {
"default": 25,
"description": "Results per page (1-100)",
"maximum": 100,
"minimum": 1,
"title": "Limit",
"type": "integer"
},
"after": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Pagination cursor from a previous call",
"title": "After"
},
"max_pages": {
"default": 1,
"description": "Pages to fetch (1-4); each page is one billed call ($0.002)",
"maximum": 4,
"minimum": 1,
"title": "Max Pages",
"type": "integer"
},
"subreddit": {
"description": "Subreddit name (r/ prefix accepted)",
"minLength": 1,
"title": "Subreddit",
"type": "string"
},
"sort": {
"default": "hot",
"description": "Reddit sort tab",
"enum": [
"hot",
"new",
"top",
"rising",
"controversial",
"best"
],
"title": "Sort",
"type": "string"
},
"time": {
"anyOf": [
{
"enum": [
"hour",
"day",
"week",
"month",
"year",
"all"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Timeframe; only valid with sort=top or sort=controversial (default day for those)",
"title": "Time"
},
"text_max_chars": {
"default": 500,
"description": "Truncate each post's text to this many characters",
"maximum": 10000,
"minimum": 50,
"title": "Text Max Chars",
"type": "integer"
}
},
"required": [
"subreddit"
],
"title": "GetSubredditPostsParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"Post": {
"properties": {
"id": {
"description": "Post ID without prefix (e.g. '1sgjld3')",
"title": "Id",
"type": "string"
},
"fullname": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Full ID with t3_ prefix; use as the after cursor",
"title": "Fullname"
},
"title": {
"default": "",
"description": "Post title",
"title": "Title",
"type": "string"
},
"author": {
"default": "",
"description": "Author username (no u/ prefix)",
"title": "Author",
"type": "string"
},
"author_flair": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Author's flair text in this subreddit",
"title": "Author Flair"
},
"subreddit": {
"default": "",
"description": "Subreddit name (no r/ prefix)",
"title": "Subreddit",
"type": "string"
},
"score": {
"default": 0,
"description": "Net votes (upvotes minus downvotes)",
"title": "Score",
"type": "integer"
},
"num_comments": {
"default": 0,
"description": "Comment count",
"title": "Num Comments",
"type": "integer"
},
"upvote_ratio": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Approximate upvote ratio",
"title": "Upvote Ratio"
},
"permalink": {
"default": "",
"description": "Path on reddit.com; pass to get_post_comments",
"title": "Permalink",
"type": "string"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Full reddit.com URL",
"title": "Url"
},
"link_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "External link or media URL; null for self/text posts",
"title": "Link Url"
},
"is_self": {
"default": false,
"description": "True for text/self posts",
"title": "Is Self",
"type": "boolean"
},
"over_18": {
"default": false,
"description": "NSFW flag",
"title": "Over 18",
"type": "boolean"
},
"stickied": {
"default": false,
"title": "Stickied",
"type": "boolean"
},
"locked": {
"default": false,
"title": "Locked",
"type": "boolean"
},
"spoiler": {
"default": false,
"title": "Spoiler",
"type": "boolean"
},
"is_crosspost": {
"default": false,
"title": "Is Crosspost",
"type": "boolean"
},
"crosspost_from": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Subreddit the post was crossposted from, if any",
"title": "Crosspost From"
},
"created": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Creation time, ISO 8601",
"title": "Created"
},
"text": {
"default": "",
"description": "Self-post body (empty for link/image posts)",
"title": "Text",
"type": "string"
},
"text_truncated": {
"default": false,
"description": "True if text was truncated; use get_post for the full body",
"title": "Text Truncated",
"type": "boolean"
}
},
"required": [
"id"
],
"title": "Post",
"type": "object"
}
},
"properties": {
"success": {
"default": true,
"title": "Success",
"type": "boolean"
},
"after": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Cursor for the next page; pass back via the after param. Non-null means more results are available; null means the end was reached.",
"title": "After"
},
"pages_fetched": {
"default": 1,
"description": "Billed RedditAPI calls made ($0.002 each)",
"title": "Pages Fetched",
"type": "integer"
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Set when the fetch stopped early (time budget or a failed later page); the returned results are partial.",
"title": "Note"
},
"posts": {
"items": {
"$ref": "#/$defs/Post"
},
"title": "Posts",
"type": "array"
}
},
"title": "PostListResult",
"type": "object"
} # get_user read
Get a Reddit user's profile: karma, account age, flags, bio ($0.002).
Full description
Fetch a Reddit user's public profile. One billed RedditAPI call ($0.002). Includes karma buckets, account age, premium/mod/employee/verified flags, and the profile bio.
| Parameter | Type | Required | Description |
|---|---|---|---|
username | string | Yes | Reddit username (u/ prefix accepted) |
Parameter schema (JSON)
{
"properties": {
"username": {
"description": "Reddit username (u/ prefix accepted)",
"minLength": 1,
"title": "Username",
"type": "string"
}
},
"required": [
"username"
],
"title": "GetUserParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"UserProfile": {
"properties": {
"username": {
"default": "",
"title": "Username",
"type": "string"
},
"fullname": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "t2_ prefixed account ID",
"title": "Fullname"
},
"created": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Account creation time, ISO 8601",
"title": "Created"
},
"account_age_days": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Account age in days",
"title": "Account Age Days"
},
"link_karma": {
"default": 0,
"title": "Link Karma",
"type": "integer"
},
"comment_karma": {
"default": 0,
"title": "Comment Karma",
"type": "integer"
},
"total_karma": {
"default": 0,
"title": "Total Karma",
"type": "integer"
},
"premium": {
"default": false,
"description": "Reddit Premium subscriber",
"title": "Premium",
"type": "boolean"
},
"is_mod": {
"default": false,
"description": "Moderates at least one subreddit",
"title": "Is Mod",
"type": "boolean"
},
"is_employee": {
"default": false,
"description": "Reddit admin/staff",
"title": "Is Employee",
"type": "boolean"
},
"verified": {
"default": false,
"description": "Verified account badge",
"title": "Verified",
"type": "boolean"
},
"bio": {
"default": "",
"description": "Profile bio",
"title": "Bio",
"type": "string"
},
"bio_truncated": {
"default": false,
"title": "Bio Truncated",
"type": "boolean"
}
},
"title": "UserProfile",
"type": "object"
}
},
"properties": {
"success": {
"default": true,
"title": "Success",
"type": "boolean"
},
"user": {
"$ref": "#/$defs/UserProfile"
}
},
"required": [
"user"
],
"title": "UserProfileResult",
"type": "object"
} # get_user_comments read
Get a Reddit user's recent comments ($0.002 per page).
Full description
Fetch a user's recent comments across Reddit. Each page is one billed RedditAPI call ($0.002); max_pages defaults to 1 and the after cursor lets you continue in a later call. url is the comment's own URL; post_title names the post the comment was made on.
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | integer | No | Results per page (1-100) Default: 25 |
after | string | null | No | Pagination cursor from a previous call |
max_pages | integer | No | Pages to fetch (1-4); each page is one billed call ($0.002) Default: 1 |
username | string | Yes | Reddit username (u/ prefix accepted) |
sort | "new" | "top" | "controversial" | No | Result order Default: "new" |
body_max_chars | integer | No | Truncate each comment's body to this many characters Default: 500 |
Parameter schema (JSON)
{
"properties": {
"limit": {
"default": 25,
"description": "Results per page (1-100)",
"maximum": 100,
"minimum": 1,
"title": "Limit",
"type": "integer"
},
"after": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Pagination cursor from a previous call",
"title": "After"
},
"max_pages": {
"default": 1,
"description": "Pages to fetch (1-4); each page is one billed call ($0.002)",
"maximum": 4,
"minimum": 1,
"title": "Max Pages",
"type": "integer"
},
"username": {
"description": "Reddit username (u/ prefix accepted)",
"minLength": 1,
"title": "Username",
"type": "string"
},
"sort": {
"default": "new",
"description": "Result order",
"enum": [
"new",
"top",
"controversial"
],
"title": "Sort",
"type": "string"
},
"body_max_chars": {
"default": 500,
"description": "Truncate each comment's body to this many characters",
"maximum": 10000,
"minimum": 50,
"title": "Body Max Chars",
"type": "integer"
}
},
"required": [
"username"
],
"title": "GetUserCommentsParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"UserComment": {
"properties": {
"id": {
"description": "Comment ID",
"title": "Id",
"type": "string"
},
"author": {
"default": "",
"title": "Author",
"type": "string"
},
"body": {
"default": "",
"description": "Comment text",
"title": "Body",
"type": "string"
},
"body_truncated": {
"default": false,
"title": "Body Truncated",
"type": "boolean"
},
"subreddit": {
"default": "",
"description": "Subreddit the comment was posted in",
"title": "Subreddit",
"type": "string"
},
"score": {
"default": 0,
"description": "Net votes",
"title": "Score",
"type": "integer"
},
"created": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Creation time, ISO 8601",
"title": "Created"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Full reddit.com URL of the comment",
"title": "Url"
},
"post_title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Title of the post the comment is on",
"title": "Post Title"
}
},
"required": [
"id"
],
"title": "UserComment",
"type": "object"
}
},
"properties": {
"success": {
"default": true,
"title": "Success",
"type": "boolean"
},
"after": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Cursor for the next page; pass back via the after param. Non-null means more results are available; null means the end was reached.",
"title": "After"
},
"pages_fetched": {
"default": 1,
"description": "Billed RedditAPI calls made ($0.002 each)",
"title": "Pages Fetched",
"type": "integer"
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Set when the fetch stopped early (time budget or a failed later page); the returned results are partial.",
"title": "Note"
},
"comments": {
"items": {
"$ref": "#/$defs/UserComment"
},
"title": "Comments",
"type": "array"
}
},
"title": "UserCommentListResult",
"type": "object"
} # search_communities read
Search Reddit communities (subreddits) by keyword ($0.002 per page).
Full description
Search subreddits by keyword, mirroring reddit.com's Communities tab. Each page is one billed RedditAPI call ($0.002); max_pages defaults to 1 and the after cursor lets you continue in a later call.
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | integer | No | Results per page (1-100) Default: 25 |
after | string | null | No | Pagination cursor from a previous call |
max_pages | integer | No | Pages to fetch (1-4); each page is one billed call ($0.002) Default: 1 |
query | string | Yes | Search query |
include_nsfw | boolean | No | Include NSFW communities Default: false |
Parameter schema (JSON)
{
"properties": {
"limit": {
"default": 25,
"description": "Results per page (1-100)",
"maximum": 100,
"minimum": 1,
"title": "Limit",
"type": "integer"
},
"after": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Pagination cursor from a previous call",
"title": "After"
},
"max_pages": {
"default": 1,
"description": "Pages to fetch (1-4); each page is one billed call ($0.002)",
"maximum": 4,
"minimum": 1,
"title": "Max Pages",
"type": "integer"
},
"query": {
"description": "Search query",
"minLength": 1,
"title": "Query",
"type": "string"
},
"include_nsfw": {
"default": false,
"description": "Include NSFW communities",
"title": "Include Nsfw",
"type": "boolean"
}
},
"required": [
"query"
],
"title": "SearchCommunitiesParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"Community": {
"properties": {
"name": {
"description": "Subreddit name (no r/ prefix)",
"title": "Name",
"type": "string"
},
"title": {
"default": "",
"description": "Display title",
"title": "Title",
"type": "string"
},
"description": {
"default": "",
"description": "Short community blurb",
"title": "Description",
"type": "string"
},
"description_truncated": {
"default": false,
"title": "Description Truncated",
"type": "boolean"
},
"subscribers": {
"default": 0,
"description": "Member count",
"title": "Subscribers",
"type": "integer"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Full reddit.com URL",
"title": "Url"
},
"subreddit_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "public, private, restricted, ...",
"title": "Subreddit Type"
},
"over_18": {
"default": false,
"description": "NSFW flag",
"title": "Over 18",
"type": "boolean"
},
"quarantine": {
"default": false,
"description": "True if Reddit has quarantined the sub",
"title": "Quarantine",
"type": "boolean"
},
"created": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Creation time, ISO 8601",
"title": "Created"
}
},
"required": [
"name"
],
"title": "Community",
"type": "object"
}
},
"properties": {
"success": {
"default": true,
"title": "Success",
"type": "boolean"
},
"after": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Cursor for the next page; pass back via the after param. Non-null means more results are available; null means the end was reached.",
"title": "After"
},
"pages_fetched": {
"default": 1,
"description": "Billed RedditAPI calls made ($0.002 each)",
"title": "Pages Fetched",
"type": "integer"
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Set when the fetch stopped early (time budget or a failed later page); the returned results are partial.",
"title": "Note"
},
"communities": {
"items": {
"$ref": "#/$defs/Community"
},
"title": "Communities",
"type": "array"
}
},
"title": "CommunityListResult",
"type": "object"
} # search_posts read
Search Reddit posts globally or within one subreddit ($0.002 per page).
Full description
Search Reddit posts by keyword, globally or within one subreddit. Mirrors the Posts tab of reddit.com search. Each page is one billed RedditAPI call ($0.002); max_pages defaults to 1 and the after cursor lets you continue in a later call. NSFW results are filtered unless include_nsfw is true. Post text is truncated to text_max_chars; use get_post for a full body.
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | integer | No | Results per page (1-100) Default: 25 |
after | string | null | No | Pagination cursor from a previous call |
max_pages | integer | No | Pages to fetch (1-4); each page is one billed call ($0.002) Default: 1 |
query | string | Yes | Search query |
subreddit | string | null | No | Restrict to one subreddit (no r/ prefix) |
sort | "relevance" | "new" | "hot" | "top" | "comments" | No | Result order Default: "relevance" |
time | "hour" | "day" | "week" | "month" | "year" | "all" | null | No | Timeframe filter |
include_nsfw | boolean | No | Include NSFW results (Safe Search off) Default: false |
text_max_chars | integer | No | Truncate each post's text to this many characters Default: 500 |
Parameter schema (JSON)
{
"properties": {
"limit": {
"default": 25,
"description": "Results per page (1-100)",
"maximum": 100,
"minimum": 1,
"title": "Limit",
"type": "integer"
},
"after": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Pagination cursor from a previous call",
"title": "After"
},
"max_pages": {
"default": 1,
"description": "Pages to fetch (1-4); each page is one billed call ($0.002)",
"maximum": 4,
"minimum": 1,
"title": "Max Pages",
"type": "integer"
},
"query": {
"description": "Search query",
"minLength": 1,
"title": "Query",
"type": "string"
},
"subreddit": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Restrict to one subreddit (no r/ prefix)",
"title": "Subreddit"
},
"sort": {
"default": "relevance",
"description": "Result order",
"enum": [
"relevance",
"new",
"hot",
"top",
"comments"
],
"title": "Sort",
"type": "string"
},
"time": {
"anyOf": [
{
"enum": [
"hour",
"day",
"week",
"month",
"year",
"all"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Timeframe filter",
"title": "Time"
},
"include_nsfw": {
"default": false,
"description": "Include NSFW results (Safe Search off)",
"title": "Include Nsfw",
"type": "boolean"
},
"text_max_chars": {
"default": 500,
"description": "Truncate each post's text to this many characters",
"maximum": 10000,
"minimum": 50,
"title": "Text Max Chars",
"type": "integer"
}
},
"required": [
"query"
],
"title": "SearchPostsParams",
"type": "object",
"additionalProperties": false
}Result schema (JSON)
{
"$defs": {
"Post": {
"properties": {
"id": {
"description": "Post ID without prefix (e.g. '1sgjld3')",
"title": "Id",
"type": "string"
},
"fullname": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Full ID with t3_ prefix; use as the after cursor",
"title": "Fullname"
},
"title": {
"default": "",
"description": "Post title",
"title": "Title",
"type": "string"
},
"author": {
"default": "",
"description": "Author username (no u/ prefix)",
"title": "Author",
"type": "string"
},
"author_flair": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Author's flair text in this subreddit",
"title": "Author Flair"
},
"subreddit": {
"default": "",
"description": "Subreddit name (no r/ prefix)",
"title": "Subreddit",
"type": "string"
},
"score": {
"default": 0,
"description": "Net votes (upvotes minus downvotes)",
"title": "Score",
"type": "integer"
},
"num_comments": {
"default": 0,
"description": "Comment count",
"title": "Num Comments",
"type": "integer"
},
"upvote_ratio": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Approximate upvote ratio",
"title": "Upvote Ratio"
},
"permalink": {
"default": "",
"description": "Path on reddit.com; pass to get_post_comments",
"title": "Permalink",
"type": "string"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Full reddit.com URL",
"title": "Url"
},
"link_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "External link or media URL; null for self/text posts",
"title": "Link Url"
},
"is_self": {
"default": false,
"description": "True for text/self posts",
"title": "Is Self",
"type": "boolean"
},
"over_18": {
"default": false,
"description": "NSFW flag",
"title": "Over 18",
"type": "boolean"
},
"stickied": {
"default": false,
"title": "Stickied",
"type": "boolean"
},
"locked": {
"default": false,
"title": "Locked",
"type": "boolean"
},
"spoiler": {
"default": false,
"title": "Spoiler",
"type": "boolean"
},
"is_crosspost": {
"default": false,
"title": "Is Crosspost",
"type": "boolean"
},
"crosspost_from": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Subreddit the post was crossposted from, if any",
"title": "Crosspost From"
},
"created": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Creation time, ISO 8601",
"title": "Created"
},
"text": {
"default": "",
"description": "Self-post body (empty for link/image posts)",
"title": "Text",
"type": "string"
},
"text_truncated": {
"default": false,
"description": "True if text was truncated; use get_post for the full body",
"title": "Text Truncated",
"type": "boolean"
}
},
"required": [
"id"
],
"title": "Post",
"type": "object"
}
},
"properties": {
"success": {
"default": true,
"title": "Success",
"type": "boolean"
},
"after": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Cursor for the next page; pass back via the after param. Non-null means more results are available; null means the end was reached.",
"title": "After"
},
"pages_fetched": {
"default": 1,
"description": "Billed RedditAPI calls made ($0.002 each)",
"title": "Pages Fetched",
"type": "integer"
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Set when the fetch stopped early (time budget or a failed later page); the returned results are partial.",
"title": "Note"
},
"posts": {
"items": {
"$ref": "#/$defs/Post"
},
"title": "Posts",
"type": "array"
}
},
"title": "PostListResult",
"type": "object"
}