Reddit Search
reddit_searchSearch Reddit by keyword with support for Posts, Comments, and Communities
Category: reddit•Timeout: 300s• Retryable
Input schema
POST this shape to /api/v1/tasks as the input field when creating a task in a group of type reddit_search.
{
"type": "object",
"properties": {
"keyword": {
"type": "string",
"description": "Search keyword",
"minLength": 1
},
"query": {
"type": "string",
"description": "Legacy alias for keyword — the executor accepts either. Prefer keyword in new clients.",
"minLength": 1
},
"type": {
"type": "string",
"description": "Search type",
"enum": [
"posts",
"comments",
"communities"
]
},
"sortBy": {
"type": "string",
"description": "Sort method (only for Posts and Comments)",
"enum": [
"relevance",
"top",
"new"
]
},
"limit": {
"type": "integer",
"description": "Number of results to fetch",
"minimum": 1,
"maximum": 200
}
},
"required": [
"type",
"limit"
],
"anyOf": [
{
"required": [
"keyword"
]
},
{
"required": [
"query"
]
}
]
}Output schema
Executors submit their output matching this shape to /api/v1/tasks/[taskId]/submit. Readers pull it back from task detail endpoints.
{
"type": "object",
"properties": {
"results": {
"type": "array",
"description": "Array of search results (structure varies by type)",
"items": {
"oneOf": [
{
"type": "object",
"description": "Post search result",
"properties": {
"post_id": {
"type": "string",
"description": "Post ID"
},
"post_title": {
"type": "string",
"description": "Post title"
},
"post_url": {
"type": "string",
"description": "Post URL (absolute since v1.1.0)"
},
"subreddit_name": {
"type": "string",
"description": "Subreddit name"
},
"subreddit_url": {
"type": "string",
"description": "Subreddit URL (absolute since v1.1.0)"
},
"subreddit_id": {
"type": "string",
"description": "Subreddit ID"
},
"post_time_iso": {
"type": "string",
"format": "date-time",
"description": "Post creation timestamp (ISO 8601)"
},
"post_time_relative": {
"type": "string",
"description": "Relative time since post creation"
},
"snippet_text": {
"type": "string",
"description": "Matched snippet text from the search result; empty string when the result carries none"
},
"snippet_id": {
"type": [
"string",
"null"
],
"description": "Deprecated in v1.1.0 for a public-JSON executor that could not supply it. That executor was replaced within days by the one that reads the rendered search page, and it does not return null here: it returns the result's snippet id, or an empty string when there is none.",
"deprecated": true
},
"vote_count": {
"type": "integer",
"description": "Number of votes"
},
"comment_count": {
"type": "integer",
"description": "Number of comments"
},
"is_nsfw": {
"type": "boolean",
"description": "Whether the post is NSFW"
},
"is_spoiler": {
"type": "boolean",
"description": "Whether the post is a spoiler"
},
"is_quarantined": {
"type": "boolean",
"description": "Whether the subreddit is quarantined"
},
"search_position": {
"type": "integer",
"description": "Position in search results (1-based, global across pages since v1.1.0)"
}
},
"required": [
"post_id",
"post_title",
"post_url",
"subreddit_name",
"subreddit_url",
"subreddit_id",
"post_time_iso",
"vote_count",
"comment_count",
"search_position"
]
},
{
"type": "object",
"description": "Comment search result",
"properties": {
"type": {
"type": "string",
"const": "comment",
"description": "Result type"
},
"comment_id": {
"type": "string",
"description": "Comment ID"
},
"comment_parent_id": {
"type": "string",
"description": "Parent comment or post ID"
},
"comment_content": {
"type": "string",
"description": "Comment content"
},
"comment_url": {
"type": "string",
"description": "Comment URL (absolute since v1.1.0)"
},
"comment_author": {
"type": "string",
"description": "Comment author username"
},
"comment_time_iso": {
"type": "string",
"format": "date-time",
"description": "Comment creation timestamp (ISO 8601)"
},
"comment_time_relative": {
"type": "string",
"description": "Relative time since comment creation"
},
"comment_vote_count": {
"type": "integer",
"description": "Comment vote count"
},
"post_id": {
"type": "string",
"description": "Parent post ID"
},
"post_title": {
"type": "string",
"description": "Parent post title"
},
"post_url": {
"type": "string",
"description": "Parent post URL (absolute since v1.1.0)"
},
"post_time_iso": {
"type": [
"string",
"null"
],
"description": "Deprecated in v1.1.0 for a public-JSON executor that could not supply it. That executor was replaced within days by the one that reads the rendered search page, and it does not return null here: it returns the parent post time as shown on the page, or an empty string when the page does not show it.",
"deprecated": true
},
"post_time_relative": {
"type": [
"string",
"null"
],
"description": "Deprecated in v1.1.0 for a public-JSON executor that could not supply it. That executor was replaced within days by the one that reads the rendered search page, and it does not return null here: it returns the parent post relative time as shown on the page, or an empty string when the page does not show it.",
"deprecated": true
},
"post_vote_count": {
"type": [
"integer",
"null"
],
"description": "Deprecated in v1.1.0 for a public-JSON executor that could not supply it. That executor was replaced within days by the one that reads the rendered search page, and it does not return null here: it returns the parent post vote count as shown on the page, or 0 when the page does not show it (indistinguishable from a real 0).",
"deprecated": true
},
"post_comment_count": {
"type": [
"integer",
"null"
],
"description": "Deprecated in v1.1.0 for a public-JSON executor that could not supply it. That executor was replaced within days by the one that reads the rendered search page, and it does not return null here: it returns the parent post comment count as shown on the page, or 0 when the page does not show it (indistinguishable from a real 0).",
"deprecated": true
},
"subreddit_name": {
"type": "string",
"description": "Subreddit name"
},
"subreddit_id": {
"type": "string",
"description": "Subreddit ID"
},
"subreddit_url": {
"type": "string",
"description": "Subreddit URL (absolute since v1.1.0)"
},
"subreddit_icon": {
"type": [
"string",
"null"
],
"description": "Deprecated: always null — neither the old public-JSON executor nor the page-reading executor returns it. Kept for backward-compatible output shape.",
"deprecated": true
},
"is_nsfw": {
"type": "boolean",
"description": "Whether the content is NSFW"
},
"is_spoiler": {
"type": "boolean",
"description": "Whether the content is a spoiler"
},
"is_quarantined": {
"type": "boolean",
"description": "Whether the subreddit is quarantined"
},
"search_position": {
"type": "integer",
"description": "Position in search results (1-based, global across pages since v1.1.0)"
}
},
"required": [
"type",
"comment_id",
"comment_content",
"comment_url",
"comment_author",
"comment_time_iso",
"comment_vote_count",
"post_id",
"post_title",
"post_url",
"subreddit_name",
"subreddit_id",
"search_position"
]
},
{
"type": "object",
"description": "Community/subreddit search result",
"properties": {
"type": {
"type": "string",
"const": "subreddit",
"description": "Result type"
},
"subreddit_id": {
"type": "string",
"description": "Subreddit ID"
},
"subreddit_name": {
"type": "string",
"description": "Subreddit name"
},
"subreddit_display_name": {
"type": "string",
"description": "Subreddit display name (e.g., r/WorkOnline)"
},
"subreddit_url": {
"type": "string",
"description": "Subreddit URL (absolute since v1.1.0)"
},
"subreddit_description": {
"type": "string",
"description": "Subreddit description (public description)"
},
"subreddit_icon": {
"type": [
"string",
"null"
],
"description": "Subreddit icon URL (query string stripped since v1.1.0; null when the subreddit has no icon)"
},
"weekly_visitors": {
"type": [
"integer",
"null"
],
"description": "Weekly visitors shown on the community card (exact integer). null when the card does not show it. Added in v1.2.0."
},
"weekly_contributions": {
"type": [
"integer",
"null"
],
"description": "Weekly contributions shown on the community card (exact integer). null when the card does not show it. Added in v1.2.0."
},
"member_count": {
"type": "integer",
"description": "Deprecated since v1.2.0 — misnamed: this is the card's weekly-visitors number, not a member count (Reddit's search cards no longer show members). Same value as weekly_visitors, 0 when the card shows none. For subscribers use reddit_subreddit_details or reddit_subreddit_info.",
"deprecated": true
},
"member_count_display": {
"type": "string",
"description": "Deprecated since v1.2.0 — misnamed: the weekly-visitors number as the card displays it (rounded and localized, e.g. \"80K\" or \"8万\").",
"deprecated": true
},
"online_count": {
"type": [
"integer",
"null"
],
"description": "Deprecated since v1.2.0 — misnamed: this is the card's weekly-contributions number, not an online count. Same value as weekly_contributions.",
"deprecated": true
},
"is_nsfw": {
"type": "boolean",
"description": "Whether the subreddit is NSFW"
},
"is_quarantined": {
"type": "boolean",
"description": "Whether the subreddit is quarantined"
},
"search_position": {
"type": "integer",
"description": "Position in search results (1-based, global across pages since v1.1.0)"
}
},
"required": [
"type",
"subreddit_id",
"subreddit_name",
"subreddit_display_name",
"subreddit_url",
"subreddit_description",
"member_count",
"search_position"
]
}
]
}
}
},
"required": [
"results"
]
}Ready to run Reddit Search?
Create a project, approve an executor, and push your first reddit_search task.