Skip to main content
POST
Search Reddit Posts

Overview

This endpoint searches Reddit for posts matching a keyword query. It searches across all subreddits and returns posts with media content, perfect for finding specific types of content without knowing which subreddit to search.

Rate Limiting

This endpoint is protected by Reddit API rate limiting. The service handles rate limits with exponential backoff and retries.

Request Body

string
required
Search query string (1-200 characters)Examples:
  • "sunset photography"
  • "cute cats"
  • "nsfw joi"
number
default:"25"
Maximum number of posts to return (1-100)
string[]
default:"[]"
Array of media URLs to exclude from results. Useful for pagination and avoiding duplicates.URLs are normalized before comparison.

Response

Returns an array of Reddit posts matching the search query. The response structure is identical to the Fetch Reddit Posts endpoint.
string
Reddit post ID
string
Post title
string
Reddit username of the post author
string
Subreddit where the post was found
string
Reddit post URL
string
Direct URL to the media content
string | null
Thumbnail image URL
number
Post score (upvotes minus downvotes)
number
Number of comments
number
Unix timestamp of post creation
boolean
Whether the post contains video content
boolean
Whether the post is marked as NSFW
boolean
Whether the post is marked as a spoiler

Examples

Search with More Results

Search with URL Exclusion

Response Example

Error Responses

Invalid Query

Status: 400 Bad Request

Query Too Long

Status: 400 Bad Request

Reddit Service Not Configured

Status: 503 Service Unavailable

Search Error

Status: 500 Internal Server Error

Search Behavior

  • Searches across all subreddits (not limited to specific communities)
  • Returns posts sorted by relevance to the search query
  • Automatically filters for posts with media URLs
  • Excludes duplicate media URLs within results
  • Uses Reddit’s search API with appropriate rate limiting

Use Cases

  • Content Discovery: Find specific types of content without knowing subreddit names
  • Keyword-Based Sessions: Create sessions based on topics rather than subreddits
  • Media Exploration: Browse media matching specific themes or keywords
  • Cross-Community Search: Find content across multiple related subreddits

Notes

  • Search queries are limited to 200 characters
  • Results are filtered to only include posts with media URLs
  • The endpoint uses the centralized Reddit service for API calls
  • Rate limiting is handled automatically with retries
  • This endpoint does not require authentication
  • Search results may include NSFW content depending on the query