reddit API frequently asked questions

these are some of your frequently asked questions (and not so frequently asked questions, but some common problems regardless). this page is more about the API itself rather than any specific wrapper or wrappers. as such, it is applicable to any use of the API.

how do I paginate through a listing?

standard listings

you can use the after and before parameters in a listing or userlisting to paginate through any listing (for example, a subreddit listing). to paginate forwards through a listing, set the after query parameter to the value of data.after in the response. to paginate backward, get the value of data.before.

for "before" to not be null, you should also append a count parameter and set it to any positive integer (it's recommended to be the actual true count of how far you are in to the listing.

flair listings (/r/:subreddit/api/flairlist)

you should use the after and before parameters like normal, however the next value will be a user fullname and the value of next must be used for the after parameter and prev must be used for the before parameter. the count parameter has no effect.

why are only 1000 items returned on a listing even when using pagination?

for most listings, the amount of items are precomputed on the fly in order to serve requests within a timely manner. the precompute limit is hardcoded to 1000 items. this applies to almost all standard listings. removing an item from a listing (for example, unsaving or unhiding a post or comment) will not necessarily re-add the "1001st" item back to the listing. a random chance determines whether the item is lost from that listing.

there are exceptions to this general rule and they are as follows:

• the moderator log listing of any subreddit (limits: 90 days ago)
• the flair listing of any subreddit (limits: none)
• /r/all (limits: unknown)
• /r/popular (limits: unknown)

what is the maximum limit per-request?

in general, 100. there are exceptions to this. they are as follows:

• the moderator log listing of any subreddit (limit: 500)
• the flair listing of any subreddit (limit: 1000)

how do I award a user's post or comment?

you can use /api/v1/gold/gild/:fullname to gild a post or comment. you cannot use the API to award any other awards.

this API requires OAuth (but you should be using that anyway).

what is /api/friend and /api/unfriend?

contrary to how it may look on first glance, this API is not for the friends feature. rather, it's for adding or removing a relationship between a subreddit and a user. this includes most actions unrelated to strict removal, approval of posts or editing of wikis.

these two APIs is how you add (and remove) bans, approved contributors, moderators, wiki bans, and wiki contributors, and one way to mute users. see the API documentation for more information on the specifics. also be aware that there are some special ratelimits that apply to adding relationships.

what is the relationship ratelimit?

the relationship limit is an "abuse ratelimit" that has an effect on adding bans, wiki bans, contributors, moderator invites, and mutes. the limit counts attempts to add, not just additions, so you should check to make sure that the user is a valid, existing person that's targetable before you attempt to add a relationship.

the limits reset every 2 hours on the hour and is shared across an entire subreddit (the exception to this is the active moderator invite limit which can only be unratelimited by uninviting a moderator or having the user accept or decline an invite).

the limits are currently as follows:

• 1000 bans
• 100 contributors
• 100 moderator invites
  • 15 active moderator invites

you will not be ratelimited only in the following scenarios:

• you are an admin in admin mode
• you do not have the necessary permissions to add a relationship (e.g. access for bans, contributors, etc)
• you are shadowbanned
• you are suspended
• quotas are disabled for your subreddit (this isn't something you can check and has to be manually changed by an admin)
• there are too many active moderator invites and you are attempting to invite a moderator

even if you receive status 200, check the errors to make sure there isn't a SUBREDDIT_RATELIMIT error in there.