Reddit Listings API
Endpoints for retrieving sorted listings of content from subreddits, including hot, new, rising, top, and controversial posts.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/reddit-listings-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Reddit Data Listings API
description: The Reddit Data API provides programmatic access to Reddit content including subreddits, posts, comments, user profiles, and voting data. Developers can use the API to read and submit content, manage subreddits, search across the platform, and interact with Reddit communities. All requests require OAuth 2.0 authentication via oauth.reddit.com, with rate limits of 60 requests per minute for authenticated clients.
version: '1.0'
contact:
name: Reddit Developer Support
url: https://support.reddithelp.com/hc/en-us/articles/16160319875092-Reddit-Data-API-Wiki
termsOfService: https://www.redditinc.com/policies/data-api-terms
servers:
- url: https://oauth.reddit.com
description: OAuth API Server
security:
- oauth2: []
tags:
- name: Listings
description: Endpoints for retrieving sorted listings of content from subreddits, including hot, new, rising, top, and controversial posts.
paths:
/r/{subreddit}/hot:
get:
operationId: getHotListings
summary: Get Hot Listings
description: Returns a listing of hot posts from the specified subreddit. Results are sorted by Reddit's hot ranking algorithm.
tags:
- Listings
parameters:
- $ref: '#/components/parameters/subreddit'
- $ref: '#/components/parameters/after'
- $ref: '#/components/parameters/before'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/count'
- name: g
in: query
description: Geolocation filter for location-specific hot listings.
schema:
type: string
enum:
- GLOBAL
- US
- AR
- AU
- BG
- CA
- CL
- CO
- HR
- CZ
- FI
- FR
- DE
- GR
- HU
- IS
- IN
- IE
- IT
- JP
- MY
- MX
- NZ
- PH
- PL
- PT
- PR
- RO
- RS
- SG
- ES
- SE
- TW
- TH
- TR
- GB
- US_WA
- US_DE
- US_DC
- US_WI
- US_WV
- US_HI
- US_FL
- US_NH
- US_NJ
- US_NM
- US_TX
- US_LA
- US_NC
- US_ND
- US_NE
- US_TN
- US_NY
- US_PA
- US_CA
- US_NV
- US_VA
- US_CO
- US_AK
- US_AL
- US_AR
- US_VT
- US_IL
- US_GA
- US_IN
- US_IA
- US_OK
- US_AZ
- US_ID
- US_CT
- US_ME
- US_MD
- US_MA
- US_OH
- US_UT
- US_MO
- US_MN
- US_MI
- US_RI
- US_KS
- US_MT
- US_MS
- US_SC
- US_KY
- US_OR
- US_SD
responses:
'200':
description: Listing of hot posts
content:
application/json:
schema:
$ref: '#/components/schemas/Listing'
/r/{subreddit}/new:
get:
operationId: getNewListings
summary: Get New Listings
description: Returns a listing of new posts from the specified subreddit, sorted by submission time with newest first.
tags:
- Listings
parameters:
- $ref: '#/components/parameters/subreddit'
- $ref: '#/components/parameters/after'
- $ref: '#/components/parameters/before'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/count'
responses:
'200':
description: Listing of new posts
content:
application/json:
schema:
$ref: '#/components/schemas/Listing'
/r/{subreddit}/rising:
get:
operationId: getRisingListings
summary: Get Rising Listings
description: Returns a listing of rising posts from the specified subreddit. Rising posts are those gaining upvotes at a rapid rate.
tags:
- Listings
parameters:
- $ref: '#/components/parameters/subreddit'
- $ref: '#/components/parameters/after'
- $ref: '#/components/parameters/before'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/count'
responses:
'200':
description: Listing of rising posts
content:
application/json:
schema:
$ref: '#/components/schemas/Listing'
/r/{subreddit}/top:
get:
operationId: getTopListings
summary: Get Top Listings
description: Returns a listing of top-scoring posts from the specified subreddit, filterable by time period.
tags:
- Listings
parameters:
- $ref: '#/components/parameters/subreddit'
- $ref: '#/components/parameters/after'
- $ref: '#/components/parameters/before'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/t'
responses:
'200':
description: Listing of top posts
content:
application/json:
schema:
$ref: '#/components/schemas/Listing'
/r/{subreddit}/controversial:
get:
operationId: getControversialListings
summary: Get Controversial Listings
description: Returns a listing of controversial posts from the specified subreddit, which are posts with a roughly even mix of upvotes and downvotes.
tags:
- Listings
parameters:
- $ref: '#/components/parameters/subreddit'
- $ref: '#/components/parameters/after'
- $ref: '#/components/parameters/before'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/t'
responses:
'200':
description: Listing of controversial posts
content:
application/json:
schema:
$ref: '#/components/schemas/Listing'
components:
parameters:
t:
name: t
in: query
description: The time period for filtering results.
schema:
type: string
enum:
- hour
- day
- week
- month
- year
- all
count:
name: count
in: query
description: A positive integer indicating the number of items already seen in this listing, used for pagination numbering.
schema:
type: integer
minimum: 0
before:
name: before
in: query
description: The fullname of a thing used as an anchor for pagination. Returns results before this item.
schema:
type: string
limit:
name: limit
in: query
description: The maximum number of items to return (default 25, max 100).
schema:
type: integer
default: 25
minimum: 1
maximum: 100
after:
name: after
in: query
description: The fullname of a thing used as an anchor for pagination. Returns results after this item.
schema:
type: string
subreddit:
name: subreddit
in: path
required: true
description: The name of the subreddit.
schema:
type: string
schemas:
Listing:
type: object
description: A Reddit listing is a paginated collection of things. Listings contain a data object with children and pagination information.
properties:
kind:
type: string
description: The kind identifier, always "Listing".
enum:
- Listing
data:
type: object
properties:
after:
type: string
nullable: true
description: The fullname of the next item for forward pagination.
before:
type: string
nullable: true
description: The fullname of the previous item for backward pagination.
dist:
type: integer
description: The number of items in this listing.
modhash:
type: string
description: A modhash for CSRF protection.
children:
type: array
description: The list of things in this listing.
items:
$ref: '#/components/schemas/Thing'
Thing:
type: object
description: A Reddit thing is the base object type. All Reddit objects (comments, links, subreddits, etc.) are things with a kind and data payload.
properties:
kind:
type: string
description: The kind identifier (t1 for comment, t2 for account, t3 for link, t4 for message, t5 for subreddit, t6 for award).
enum:
- t1
- t2
- t3
- t4
- t5
- t6
data:
type: object
description: The thing's data payload, varying by kind.
securitySchemes:
oauth2:
type: oauth2
description: Reddit uses OAuth 2.0 for authentication. All API requests must include a valid access token obtained through one of the supported OAuth grant types.
flows:
authorizationCode:
authorizationUrl: https://www.reddit.com/api/v1/authorize
tokenUrl: https://www.reddit.com/api/v1/access_token
scopes:
identity: Access user identity
edit: Edit and delete content
flair: Set user and link flair
history: Access voting history
modconfig: Manage subreddit configuration
modflair: Manage subreddit flair
modlog: Access moderation log
modposts: Approve and remove content
modwiki: Manage wiki pages
mysubreddits: Access subscribed subreddits
privatemessages: Access private messages
read: Read content
report: Report content
save: Save and unsave content
submit: Submit content
subscribe: Manage subscriptions
vote: Vote on content
wikiedit: Edit wiki pages
wikiread: Read wiki pages
externalDocs:
description: Reddit API Documentation
url: https://www.reddit.com/dev/api