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 (since v1.1.0: first ~300 characters of the post selftext; empty string for link posts)"
},
"snippet_id": {
"type": [
"string",
"null"
],
"description": "Deprecated: always null since v1.1.0 — the data source moved to Reddit's public search JSON endpoint, which has no DOM snippet IDs. Kept for backward-compatible output shape.",
"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: always null since v1.1.0 — the data source moved to Reddit's public search JSON endpoint, whose comment results do not carry parent-post timestamps. Kept for backward-compatible output shape.",
"deprecated": true
},
"post_time_relative": {
"type": [
"string",
"null"
],
"description": "Deprecated: always null since v1.1.0 — the data source moved to Reddit's public search JSON endpoint, whose comment results do not carry parent-post timestamps. Kept for backward-compatible output shape.",
"deprecated": true
},
"post_vote_count": {
"type": [
"integer",
"null"
],
"description": "Deprecated: always null since v1.1.0 — the data source moved to Reddit's public search JSON endpoint, whose comment results do not carry parent-post engagement counts. Kept for backward-compatible output shape.",
"deprecated": true
},
"post_comment_count": {
"type": [
"integer",
"null"
],
"description": "Deprecated: always null since v1.1.0 — the data source moved to Reddit's public search JSON endpoint, whose comment results do not carry parent-post engagement counts. Kept for backward-compatible output shape.",
"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 since v1.1.0 — not exposed by the public search JSON endpoint (the DOM scraper also always returned null). 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)"
},
"member_count": {
"type": "integer",
"description": "Number of members"
},
"member_count_display": {
"type": "string",
"description": "Formatted member count (e.g., 1.2m, 45.3k)"
},
"online_count": {
"type": [
"integer",
"null"
],
"description": "Number of users currently online (nullable since v1.1.0 — the public search JSON endpoint frequently omits active_user_count)"
},
"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.