search_posts
Find Reddit posts by searching with keywords, filtering by subreddit, sorting by relevance or time, and controlling result quantity.
Instructions
Search for Reddit posts using a search query.
Args:
query: The search query/term to search for
subreddit: Optional subreddit to limit search to (with or without 'r/' prefix). If None, searches all of Reddit
sort: Sort order for results - one of: "relevance", "hot", "top", "new", "comments"
time_filter: Time period to filter results (e.g. "hour", "day", "week", "month", "year", "all")
limit: Number of posts to return (1-100)
Returns:
Dictionary containing structured search results with the following structure:
{
'query': str, # The search query used
'subreddit': Optional[str], # Subreddit searched (None if searching all of Reddit)
'sort': str, # Sort method used
'time_filter': str, # Time filter used
'posts': [ # List of matching posts
{
'id': str, # Post ID
'title': str, # Post title
'author': str, # Author's username
'subreddit': str, # Subreddit name
'score': int, # Post score (upvotes - downvotes)
'upvote_ratio': float, # Ratio of upvotes to total votes
'num_comments': int, # Number of comments
'created_utc': float, # Post creation timestamp
'url': str, # URL to the post
'permalink': str, # Relative URL to the post
'is_self': bool, # Whether it's a self (text) post
'selftext': str, # Content of self post (if any)
'link_url': str, # URL for link posts (if any)
'over_18': bool, # Whether marked as NSFW
'spoiler': bool, # Whether marked as spoiler
'stickied': bool, # Whether stickied in the subreddit
'locked': bool, # Whether comments are locked
'distinguished': Optional[str], # Distinguishing type (e.g., 'moderator')
'flair': Optional[Dict], # Post flair information if any
},
...
],
'metadata': {
'fetched_at': float, # Timestamp when data was fetched
'result_count': int, # Number of results returned
'search_scope': str, # "all" or subreddit name
}
}
Raises:
ValueError: If query is empty, sort method is invalid, or time_filter is invalid
RuntimeError: For other errors during the operationInput Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| subreddit | No | ||
| sort | No | relevance | |
| time_filter | No | all | |
| limit | No |