Search Reddit Image, Video, and Gallery Posts

Search posts that carry media, and get the media URL back with each result.

Reach for this instead of Search Posts when you only want posts with an image, video, or gallery attached, and you want the direct media_url without re-deriving it per post. It is the same underlying Reddit search, narrowed to media and reshaped for it.

Query Parameters

kind is the parameter that distinguishes this endpoint from its siblings. It maps to Reddit's own post classification: image is post_hint=image, video covers both Reddit-hosted and embedded third-party video, and gallery is a multi-image album post.

limit is how many matching posts you get

Read this before you build pagination on top of the endpoint.

The media filter runs on our side, after Reddit's page, so we ask Reddit for a larger page than your limit (at least 25, up to four times your limit, never more than 100), keep the posts that match kind, and return up to limit of them. When more matched than fit, the next cursor resumes right after the last post you were given, so paging never skips a match. Two counts come back with every page: fetched is how many raw results Reddit served, and filtered_from is how many of those were consumed to produce this page (the whole page, or up to the last post returned when the trim left matches for the next page).

Before this change q=aurora borealis, kind=image, limit=2 asked Reddit for 2 results and returned 0 images (measured 2026-10-14); the same call now asks for 25 and returns up to 2 images from that page.

A short page is normal and does not mean the results are exhausted. Keep paging on after until it comes back null, and count what you have kept rather than counting pages.

Be careful how you read that final null. It means there is no next page to ask for, not that you have seen every matching post. Check listing_status on that last response, as described below.

Paging past Reddit's cap

Reddit closes a single listing near 1000 items and then stops issuing a cursor, so listing_status: truncated is Reddit's limit rather than the end of the data. Every distinct combination of parameters you send is a separate listing with its own budget, so widen across listings rather than paging deeper into one.

What you can vary here:

• sort takes relevance, new, hot, top, comments, each with its own cursor.
• t takes hour, day, week, month, year, all. We forward it on every sort.

How far these actually widen has not been measured on this endpoint. On /api/reddit/posts two sorts ranged from 0 to 99 shared items out of 100 depending on how busy the subreddit was, so read a page of each before assuming a second sort doubles your coverage.

Example

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.redditapis.com/api/reddit/search/media?q=golden+retriever&kind=image"

const response = await fetch(
  "https://api.redditapis.com/api/reddit/search/media?q=golden+retriever&kind=image",
  { headers: { Authorization: "Bearer TOKEN" } }
);

import requests

response = requests.get(
    "https://api.redditapis.com/api/reddit/search/media",
    params={"q": "golden retriever", "kind": "image"},
    headers={"Authorization": "Bearer TOKEN"},
)

Response Shape

{
  "posts": [
    {
      "id": "1nv8cae",
      "title": "Some advice and cautions for those thinking about getting a golden retriever.",
      "author": "rowsdowers_mustache",
      "subreddit": "goldenretrievers",
      "upvotes": 6064,
      "comments": 305,
      "url": "https://reddit.com/r/goldenretrievers/comments/1nv8cae/some_advice_and_cautions_for_those_thinking_about/",
      "kind": "gallery",
      "media_url": "https://www.reddit.com/gallery/1nv8cae",
      "thumbnail": "https://b.thumbs.redditmedia.com/ElL5U5oScVGf0WgCWhPEgqf8H-e9sUzgaA3ayyXPIrY.jpg",
      "is_video": false,
      "is_gallery": true,
      "link_flair_text": null,
      "link_flair_template_id": null,
      "created": "2025-10-01T13:33:40.000Z"
    }
  ],
  "after": "t3_1idundv",
  "fetched": 25,
  "filtered_from": 25
}

Response Fields

When after comes back empty

An empty cursor means there is no next page to ask for. It does not always mean you have every post: Reddit often stops serving a busy listing long before it runs out. Paging r/all on 2026-08-14 stopped after 400 posts covering about a minute of a feed that plainly holds more.

The response tells you which happened. When after is null it also carries listing_status, which reads complete, truncated or unknown. Only complete means you have everything; treat the other two as a partial answer and widen your search rather than stopping. The full field list and what to do about each answer is in Pagination depth.

Reaching media past the listing cap

A subreddit listing stops at roughly 1000 posts, which is the cap described in Pagination depth. Search is a separate listing with its own budget, so a media search reaches media posts that paging /api/reddit/posts will not. Narrowing with t splits the range further, since each timeframe is its own listing.

This endpoint has no subreddit parameter, so it always searches site-wide. To confine it to one subreddit, put Reddit's subreddit: operator in the query:

q=subreddit:goldenretrievers puppy

That returns media posts from r/goldenretrievers only. If you want a subreddit-restricted search over all posts rather than media, use /api/reddit/search, which does take a subreddit parameter.