# Subreddit



<MethodPage method="GET" path="/v1/reddit/subreddit" credits={1}>
  <MethodSignature name="listSubreddit" args={[{ name: "sub" }, { name: "options", optional: true }]} returns="Listing<Post>" />

  Lists a subreddit's posts with their scores, comment counts, links and text. Pass a post's `id` to [Post](/reddit/post) to read its comments. 1 credit per page of up to 100 posts; see [Listings and pages](/listings) for paging and NSFW filtering.

  <Security permission="reddit:read" />

  <SchemaGroup title="Query parameters">
    <SchemaField name="sub" type="string" location="query" required>
      Subreddit name, with or without `r/`: `golang` or `r/golang`.
    </SchemaField>

    <SchemaField name="sort" type="string" optional location="query">
      `hot` (default), `new`, `top`, `rising` or `controversial`.
    </SchemaField>

    <SchemaField name="t" type="string" optional location="query">
      Time window for `top` and `controversial`: `hour`, `day`, `week`, `month`, `year` or `all`.
    </SchemaField>

    <SchemaField name="limit" type="integer" optional location="query">
      Posts per page, 1 to 100. Default `25`.
    </SchemaField>

    <SchemaField name="after" type="string" optional location="query">
      The previous page's `after`, for the next page.
    </SchemaField>

    <SchemaField name="nsfw" type="boolean" optional location="query">
      Include NSFW posts. Default `false`. Required to read a subreddit marked NSFW.
    </SchemaField>
  </SchemaGroup>

  <div id="returns" className="mt-8">
    Response [#response]

    ```jsonc
    {
      "subreddit": "golang",
      "query": null,
      "sort": "top",
      "count": 3,
      "items": [
        {
          "id": "1wysilc",
          "name": "t3_1wysilc",
          "subreddit": "golang",
          "title": "Does our expertise still matter?",
          "author": "evelve211",
          "score": 242,
          "upvote_ratio": 0.94,
          "num_comments": 190,
          "url": "https://www.reddit.com/r/golang/comments/1wysilc/does_our_expertise_still_matter/",
          "permalink": "/r/golang/comments/1wysilc/does_our_expertise_still_matter/",
          "domain": "self.golang",
          "selftext": "Hello everyone, I'm writing this post in relation to AI and programming…",
          "created_at": "2026-10-06T03:34:41Z",
          "is_self": true,
          "is_video": false,
          "over_18": false,
          "spoiler": false,
          "stickied": false,
          "locked": false,
          "removed": false
        }
      ],
      "after": "t3_1x0vbyx",
      "filtered_nsfw": 0
    }
    ```

    `url` is where the post links: the post itself for a text post, or the shared page for a link post (`domain` tells them apart). `selftext` is the full text of a text post, empty for a link post. `removed` is true when the post was taken down by moderators or Reddit, or deleted by its author.
  </div>

  <MethodSamples>
    <LanguageSample language="cURL">
      ```bash
      curl "https://api.threadapi.dev/v1/reddit/subreddit?sub=golang&sort=top&t=week&limit=50" \
        -H "Authorization: Bearer $THREADAPI_API_KEY"
      ```
    </LanguageSample>

    <LanguageSample language="Python">
      ```python
      import os, requests

      params = {"sub": "golang", "sort": "new", "limit": 100}
      headers = {"Authorization": f"Bearer {os.environ['THREADAPI_API_KEY']}"}
      for _ in range(3):  # three pages, 3 credits
          page = requests.get("https://api.threadapi.dev/v1/reddit/subreddit",
                              params=params, headers=headers).json()
          for post in page["items"]:
              print(post["score"], post["title"])
          if not page["after"]:
              break
          params["after"] = page["after"]
      ```
    </LanguageSample>
  </MethodSamples>
</MethodPage>