RedditapisRedditapis
Listings & Search

Reddit Ads Library API, Search Promoted Posts as JSON

Search the ads brands run on Reddit by advertiser, landing domain, subreddit, campaign or title text, with first and last seen dates and the subreddits each ad ran in.

GET/api/reddit/ads/search$0.0015 / call

Search the promoted posts advertisers run on Reddit.

Reddit has no public library of the ads it runs outside political ads (those are on the Political Ads Feed). This endpoint answers the questions that library would: which brands advertise on Reddit, with what title and creative, linking where, and in which communities. Filter by advertiser, landing domain, subreddit, campaign or title text, newest first.

How the index grows

Every Reddit page we read while serving API calls carries the promoted posts Reddit placed on it. We record each one: the ad itself, the subreddit it appeared in, and when it was first and last seen. Results therefore reflect the promoted posts seen across the communities and searches read through the API, and the index grows every day as more pages are read. sightings counts how often an ad was seen, and subreddits lists every community it appeared in.

What is never stored: anything about the account that viewed the ad. Targeting and tracking data on the ad tag are dropped, and outbound_url keeps only the landing page's origin, path and utm_* parameters. Reddit's own house ads (Reddit promoting itself) are left out, so every result is a paying advertiser.

Query Parameters

ParameterTypeRequiredDescription
qstringNoText to find in the ad title or the advertiser name, up to 200 characters
advertiserstringNoAdvertiser username, without u/ (a u/ prefix is stripped)
domainstringNoLanding page hostname, such as shop.example.com
subredditstringNoA subreddit the ad was seen in, without r/
campaign_idstringNoReddit campaign id, as returned in campaign_id
sincestringNoISO 8601 date: only ads last seen on or after it
untilstringNoISO 8601 date: only ads first seen on or before it
limitnumberNoAds per page, 1-100 (default 25)
cursorstringNoThe after value from the previous page, passed back exactly

Every parameter is optional. With none, the newest ads in the library come first.

Example

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.redditapis.com/api/reddit/ads/search?subreddit=python&limit=50"
const response = await fetch(
  "https://api.redditapis.com/api/reddit/ads/search?subreddit=python&limit=50",
  { headers: { Authorization: "Bearer TOKEN" } }
);
const { ads, after, has_more } = await response.json();
import requests

response = requests.get(
    "https://api.redditapis.com/api/reddit/ads/search",
    params={"subreddit": "python", "limit": 50},
    headers={"Authorization": "Bearer TOKEN"},
)
data = response.json()

Response Shape

{
  "ads": [
    {
      "id": "t3_1abc23",
      "campaign_id": "2045178861231",
      "ad_type": "LINK",
      "advertiser": "ExampleShop",
      "advertiser_id": "t2_1x2y3z",
      "title": "Ship faster with Example: 20% off this week",
      "outbound_url": "https://shop.example.com/landing?utm_source=reddit",
      "domain": "shop.example.com",
      "call_to_action": "Shop Now",
      "post_type": "link",
      "language": "en",
      "placement": "feed",
      "permalink": "/user/ExampleShop/comments/1abc23/ship_faster_with_example/",
      "media_url": "https://i.redd.it/example.jpg",
      "thumbnail_url": null,
      "subreddits": ["python", "programming"],
      "created_at": "2026-10-30T12:00:00.000Z",
      "first_seen_at": "2026-11-01T09:14:02.000Z",
      "last_seen_at": "2026-11-04T17:40:51.000Z",
      "sightings": 37
    }
  ],
  "count": 1,
  "after": "eyJzIjoiOTgifQ",
  "has_more": true
}

Fields

FieldMeaning
idThe ad's post fullname (t3_...)
advertiser, advertiser_idThe account that runs the ad, by name and by t2_ id
outbound_urlThe landing page: origin, path and utm_* parameters only. null when the link is a click redirector; domain still names the site then
subredditsEvery subreddit the ad was seen in
first_seen_at, last_seen_atWhen the ad first and most recently appeared on a page we read
sightingsHow many times the ad was seen, counted once per subreddit per ten minutes. Not Reddit's impression count
created_atWhen the advertiser created the ad post, as Reddit states it

A field Reddit did not show for an ad is null; nothing is filled in from a default.

Paging

Pass after back as cursor for the next page. Paging follows the order ads were first added to the library, so an ad seen again between two pages is never skipped or repeated. When has_more is false there is no next page. A page can hold fewer ads than limit while has_more is still true; keep paging.

Errors

StatusWhen
400A parameter is malformed: limit out of range, a date that is not ISO 8601, a cursor this endpoint did not return, or a parameter given twice
500The ads library could not be read. You were not charged

Billed at the standard read price, $0.0015 per call, the same as a post search.

Independent third-party API for developers and researchers. Not affiliated with, endorsed by, or sponsored by Reddit, Inc.

On this page