Fetch Reddit Posts

Fetch media posts from specified subreddits with filtering and sorting

POST /api/fetch-reddit

Fetch Reddit Posts

cURL

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
}
'

200

{
  "[].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