Skip to main content
POST
/
api
/
fetch-reddit
Fetch Reddit Posts
curl --request POST \
  --url https://api.example.com/api/fetch-reddit \
  --header 'Content-Type: application/json' \
  --data '
{
  "subreddits": "<string>",
  "limit": 123,
  "excludeUrls": [
    "<string>"
  ],
  "sortBy": "<string>",
  "timeRange": "<string>",
  "includeText": true
}
'
{
  "[].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 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

​
subreddits
string
required
Comma-separated list of subreddit names. Can include r/ prefix or not.Examples:
  • "pics,aww,cats"
  • "r/pics,r/aww"
  • "pics"
​
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 deduplication.URLs are normalized before comparison to catch duplicates across different formats.
​
sortBy
string
default:"hot"
Reddit sorting method:
  • hot - Currently trending posts
  • new - Most recent posts
  • top - Highest scoring posts
​
timeRange
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
​
includeText
boolean
default:"false"
Whether to include text posts (posts without media URLs)

​
Response

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

​
Basic Fetch

curl -X POST "https://app.joip.io/api/fetch-reddit" \
  -H "Content-Type: application/json" \
  -d '{
    "subreddits": "pics,aww",
    "limit": 25
  }'

​
Fetch with Sorting and Time Range

curl -X POST "https://app.joip.io/api/fetch-reddit" \
  -H "Content-Type: application/json" \
  -d '{
    "subreddits": "earthporn,spaceporn",
    "limit": 50,
    "sortBy": "top",
    "timeRange": "week"
  }'

​
Fetch with URL Exclusion (Pagination)

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

​
Include Text Posts

curl -X POST "https://app.joip.io/api/fetch-reddit" \
  -H "Content-Type: application/json" \
  -d '{
    "subreddits": "askreddit",
    "limit": 10,
    "includeText": true
  }'

​
Response Example

[
  {
    "id": "abc123",
    "title": "Cute cat sleeping",
    "author": "redditor123",
    "subreddit": "cats",
    "url": "https://reddit.com/r/cats/comments/abc123",
    "media_url": "https://i.redd.it/abc123xyz.jpg",
    "thumbnail": "https://b.thumbs.redditmedia.com/abc.jpg",
    "score": 1234,
    "num_comments": 56,
    "created_utc": 1709280000,
    "is_video": false,
    "nsfw": false,
    "spoiler": false
  },
  {
    "id": "def456",
    "title": "Amazing sunset",
    "author": "photographer",
    "subreddit": "pics",
    "url": "https://reddit.com/r/pics/comments/def456",
    "media_url": "https://i.imgur.com/def456.png",
    "thumbnail": "https://i.imgur.com/def456s.png",
    "score": 5678,
    "num_comments": 123,
    "created_utc": 1709283600,
    "is_video": false,
    "nsfw": false,
    "spoiler": false
  }
]

​
Error Responses

​
No Valid Subreddits

Status: 400 Bad Request 
{
  "message": "No valid subreddits provided"
}

​
Reddit Service Not Configured

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

​
No Media Found

Status: 404 Not Found 
{
  "message": "No media found in the specified subreddits",
  "error": "NO_MEDIA_FOUND"
}

​
Rate Limited

Status: 429 Too Many Requests 
{
  "message": "Reddit API rate limit exceeded. Please try again later.",
  "error": "REDDIT_API_ERROR"
}

​
Reddit API Error

Status: 500 Internal Server Error 
{
  "message": "Failed to fetch posts from Reddit",
  "error": "REDDIT_API_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

Build docs developers (and LLMs) love

Get started for freeTalk to us