Skip to main content
POST
Fetch Reddit Posts

Overview

This endpoint fetches posts with media content from Reddit using the centralized Reddit service. It supports multiple subreddits, sorting options, time ranges, and URL exclusion for deduplication.

Rate Limiting

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

Request Body

string
required
Comma-separated list of subreddit names. Can include r/ prefix or not.Examples:
  • "pics,aww,cats"
  • "r/pics,r/aww"
  • "pics"
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 deduplication.URLs are normalized before comparison to catch duplicates across different formats.
string
default:"hot"
Reddit sorting method:
  • hot - Currently trending posts
  • new - Most recent posts
  • top - Highest scoring posts
string
default:"week"
Time range for top sorting:
  • hour - Past hour
  • day - Past 24 hours
  • week - Past week
  • month - Past month
  • year - Past year
  • all - All time
This parameter is primarily used with sortBy=top
boolean
default:"false"
Whether to include text posts (posts without media URLs)

Response

Returns an array of Reddit posts with media content.
string
Reddit post ID
string
Post title
string
Reddit username of the post author
string
Subreddit name (without r/ prefix)
string
Reddit post URL
string
Direct URL to the media content (image, GIF, or video)
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

Basic Fetch

Fetch with Sorting and Time Range

Fetch with URL Exclusion (Pagination)

Include Text Posts

Response Example

Error Responses

No Valid Subreddits

Status: 400 Bad Request

Reddit Service Not Configured

Status: 503 Service Unavailable

No Media Found

Status: 404 Not Found

Rate Limited

Status: 429 Too Many Requests

Reddit API Error

Status: 500 Internal Server Error

Notes

  • The service automatically filters posts to only return those with media URLs
  • Duplicate media URLs are automatically removed within a single response
  • The endpoint fetches more posts than requested (typically 50+) to allow for filtering and exclusions
  • Results are randomly sampled to provide variety
  • Subreddit names are case-insensitive and normalized (strips r/ prefix, URLs, etc.)
  • The service caches Reddit API tokens and handles authentication automatically
  • Jittered retry logic helps reduce transient Reddit API errors