Search Reddit Posts

GET /v1/reddit/search

1 credit per page Permission: reddit:read

Searches Reddit posts, subreddits, or users matching a query string globally or within a specified subreddit.

Authorization

bearerAuth: optional HTTP

apiKeyAuth: optional API key in header

Query parameters

q: required string

Search query, 1 to 256 characters.

maxLength: 256
type: optional post|subreddit|user

Content type to search: post, subreddit, or user.

default: "post"
sub: optional string

Only search this subreddit.
sort: optional relevance|new|top|comments

default: "relevance"
t: optional hour|day|week|month|year|all

Time window when sorting by top or controversial.
limit: optional integer

Number of items per page.

range: 1–100 · default: 25
after: optional string

Pagination cursor from the previous page's after field.
nsfw: optional boolean

Include NSFW content (filtered out by default).

default: false

Returns

200

The search results.

JSON

One of the following:

Listing
- sort: required string
- count: required integer
- items: required array ofobject
  
  id: optional string
  
  name: optional string
  
  domain: optional string
  
  is_self: optional boolean
  
  flair: optional string
  
  spoiler: optional boolean
  
  stickied: optional boolean
  
  locked: optional boolean
  
  removed: optional boolean
  
  subreddit: optional string
  
  title: optional string
  
  author: optional string
  
  score: optional integer
  
  upvote_ratio: optional number
  
  num_comments: optional integer
  
  url: optional string
  
  permalink: optional string
  
  selftext: optional string
  
  created_at: optional string
  
  format: date-time
  
  is_video: optional boolean
  
  over_18: optional boolean
  
  media: optional array ofobject
  
  type: optional image|video|gallery
  
  url: optional string
  
  width: optional integer
  
  height: optional integer
  
  caption: optional string
  
  poll: optional object
  
  total_votes: optional integer
  
  is_closed: optional boolean
  
  options: optional array ofobject
  
  id: optional string
  
  text: optional string
  
  vote_count: optional integer
  
  crosspost_of: optional object
  
  id: optional string
  
  subreddit: optional string
  
  title: optional string
  
  author: optional string
  
  permalink: optional string
  
  comments: optional array ofobject
  
  id: optional string
  
  parent_id: optional string
  
  t3_<post id> for a top-level comment, t1_<comment id> for a reply.
  
  author: optional string
  
  score: optional integer
  
  body: optional string
  
  created_at: optional string
  
  format: date-time
  
  depth: optional integer
  
  is_submitter: optional boolean
  
  Written by the original poster.
  
  controversy: optional integer
  
  replies: optional array ofobject
  
  id: optional string
  
  parent_id: optional string
  
  t3_<post id> for a top-level comment, t1_<comment id> for a reply.
  
  author: optional string
  
  score: optional integer
  
  body: optional string
  
  created_at: optional string
  
  format: date-time
  
  depth: optional integer
  
  is_submitter: optional boolean
  
  Written by the original poster.
  
  controversy: optional integer
  
  replies: optional array ofobject
- filtered_nsfw: required integer
- subreddit: optional string | null
- query: optional string | null
- after: optional string | null
- degraded: optional boolean
SubredditListing
- sort: required string
- count: required integer
- items: required array ofobject
  
  name: optional string
  
  title: optional string
  
  public_description: optional string
  
  description: optional string
  
  subscribers: optional integer
  
  created_at: optional string
  
  format: date-time
  
  over_18: optional boolean
  
  type: optional string
  
  url: optional string
  
  icon: optional string
  
  rules: optional array ofobject
  
  kind: optional string
  
  short_name: optional string
  
  description: optional string
  
  violation_reason: optional string
  
  priority: optional integer
  
  created_at: optional string
  
  format: date-time
- filtered_nsfw: required integer
- query: optional string | null
- after: optional string | null
- degraded: optional boolean
UserListing
- sort: required string
- count: required integer
- items: required array ofobject
  
  name: optional string
  
  created_at: optional string
  
  format: date-time
  
  link_karma: optional integer
  
  comment_karma: optional integer
  
  total_karma: optional integer
  
  is_employee: optional boolean
  
  is_mod: optional boolean
  
  has_verified_email: optional boolean
  
  icon: optional string
  
  suspended: optional boolean
- filtered_nsfw: required integer
- query: optional string | null
- after: optional string | null
- degraded: optional boolean

400

Bad request (invalid parameter or unknown action)

JSON

One of the following:

ErrorResponse
- error: required string
  
  Human-readable error message
- error_code: optional forbidden_scope|rate_limited|daily_quota_exceeded|insufficient_credits|duplicate_transaction
  
  Machine-readable error code. Known values include: forbidden_scope, rate_limited, daily_quota_exceeded, insufficient_credits, duplicate_transaction. Additional codes may be introduced in future releases.
Error
- error: required object
  
  code: required string
  
  message: required string
  
  retryable: required boolean
  
  retry_after: optional integer
  
  Seconds to wait before retrying.

401

Missing or invalid API key or OAuth access token

JSON

One of the following:

ErrorResponse
- error: required string
  
  Human-readable error message
- error_code: optional forbidden_scope|rate_limited|daily_quota_exceeded|insufficient_credits|duplicate_transaction
  
  Machine-readable error code. Known values include: forbidden_scope, rate_limited, daily_quota_exceeded, insufficient_credits, duplicate_transaction. Additional codes may be introduced in future releases.
Error
- error: required object
  
  code: required string
  
  message: required string
  
  retryable: required boolean
  
  retry_after: optional integer
  
  Seconds to wait before retrying.

402

The account has no credits left (insufficient_credits).

JSON

error: required object
- code: required string
- message: required string
- retryable: required boolean
- retry_after: optional integer
  
  Seconds to wait before retrying.

429

Rate limit or daily request quota exceeded

JSON

One of the following:

ErrorResponse
- error: required string
  
  Human-readable error message
- error_code: optional forbidden_scope|rate_limited|daily_quota_exceeded|insufficient_credits|duplicate_transaction
  
  Machine-readable error code. Known values include: forbidden_scope, rate_limited, daily_quota_exceeded, insufficient_credits, duplicate_transaction. Additional codes may be introduced in future releases.
Error
- error: required object
  
  code: required string
  
  message: required string
  
  retryable: required boolean
  
  retry_after: optional integer
  
  Seconds to wait before retrying.

503

A temporary problem reaching Reddit (upstream_busy, upstream_timeout, upstream_error). Retry shortly; nothing was billed.

JSON

error: required object
- code: required string
- message: required string
- retryable: required boolean
- retry_after: optional integer
  
  Seconds to wait before retrying.