Skip to content
ThreadAPI
Navigation

List Subreddit Posts

GET /v1/reddit/subreddit
1 credit per page Permission: reddit:read

Lists posts from a subreddit sorted by community filters (hot, new, top, rising, controversial). Returns up to 100 posts per page.

Authorization

  • bearerAuth: optional HTTP
  • apiKeyAuth: optional API key in header

Query parameters

  • sub: required string

    Subreddit name, with or without r/.

  • sort: optional hot|new|top|rising|controversial
    default: "hot"
  • 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 posts.

JSON
  • 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

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.

403

Reddit does not show this content to logged-out readers, e.g. a private or quarantined subreddit (reddit_refused).
JSON
  • error: required object
    • code: required string
    • message: required string
    • retryable: required boolean
    • retry_after: optional integer

      Seconds to wait before retrying.

404

Requested user or resource not found
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.

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.

Type to search…

↑↓ navigate ↵ select Esc close