Skip to main content
POST
/
api
/
reddit-search
Search Reddit Posts
curl --request POST \
  --url https://api.example.com/api/reddit-search \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "<string>",
  "limit": 123,
  "excludeUrls": [
    "<string>"
  ]
}
'
{
  "[].id": "<string>",
  "[].title": "<string>",
  "[].author": "<string>",
  "[].subreddit": "<string>",
  "[].url": "<string>",
  "[].media_url": "<string>",
  "[].thumbnail": {},
  "[].score": 123,
  "[].num_comments": 123,
  "[].created_utc": 123,
  "[].is_video": true,
  "[].nsfw": true,
  "[].spoiler": true
}

​
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

​
query
string
required
Search query string (1-200 characters)Examples:
  • "sunset photography"
  • "cute cats"
  • "nsfw joi"
​
limit
number
default:"25"
Maximum number of posts to return (1-100)
​
excludeUrls
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.
​
[].id
string
Reddit post ID
​
[].title
string
Post title
​
[].author
string
Reddit username of the post author
​
[].subreddit
string
Subreddit where the post was found
​
[].url
string
Reddit post URL
​
[].media_url
string
Direct URL to the media content
​
[].thumbnail
string | null
Thumbnail image URL
​
[].score
number
Post score (upvotes minus downvotes)
​
[].num_comments
number
Number of comments
​
[].created_utc
number
Unix timestamp of post creation
​
[].is_video
boolean
Whether the post contains video content
​
[].nsfw
boolean
Whether the post is marked as NSFW
​
[].spoiler
boolean
Whether the post is marked as a spoiler

​
Examples

curl -X POST "https://app.joip.io/api/reddit-search" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "cute cats",
    "limit": 25
  }'

​
Search with More Results

curl -X POST "https://app.joip.io/api/reddit-search" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "sunset photography",
    "limit": 50
  }'

​
Search with URL Exclusion

curl -X POST "https://app.joip.io/api/reddit-search" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "nature",
    "limit": 25,
    "excludeUrls": [
      "https://i.redd.it/abc123.jpg",
      "https://i.imgur.com/xyz789.png"
    ]
  }'

​
Response Example

[
  {
    "id": "abc123",
    "title": "Beautiful sunset over the ocean",
    "author": "photographer123",
    "subreddit": "earthporn",
    "url": "https://reddit.com/r/earthporn/comments/abc123",
    "media_url": "https://i.redd.it/abc123xyz.jpg",
    "thumbnail": "https://b.thumbs.redditmedia.com/abc.jpg",
    "score": 5432,
    "num_comments": 234,
    "created_utc": 1709280000,
    "is_video": false,
    "nsfw": false,
    "spoiler": false
  },
  {
    "id": "def456",
    "title": "Golden hour photography",
    "author": "sunsetlover",
    "subreddit": "photography",
    "url": "https://reddit.com/r/photography/comments/def456",
    "media_url": "https://i.imgur.com/def456.png",
    "thumbnail": "https://i.imgur.com/def456s.png",
    "score": 3210,
    "num_comments": 145,
    "created_utc": 1709283600,
    "is_video": false,
    "nsfw": false,
    "spoiler": false
  }
]

​
Error Responses

​
Invalid Query

Status: 400 Bad Request 
{
  "message": "Validation error: String must contain at least 1 character(s) at query"
}

​
Query Too Long

Status: 400 Bad Request 
{
  "message": "Validation error: String must contain at most 200 character(s) at query"
}

​
Reddit Service Not Configured

Status: 503 Service Unavailable 
{
  "message": "Content integration is not configured. Please contact support.",
  "error": "MISSING_CREDENTIALS"
}

​
Search Error

Status: 500 Internal Server Error 
{
  "message": "Failed to search Reddit"
}

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us