# Search



<MethodPage method="GET" path="/v1/reddit/search" credits={1}>
  <MethodSignature name="search" args={[{ name: "q" }, { name: "options", optional: true }]} returns="Listing<Post | Subreddit | User>" />

  Finds posts matching a query, or with `type`, subreddits or users. Posts come back as in [Subreddit](/reddit/subreddit), subreddits as in [Subreddits](/reddit/subreddits), users as in [User](/reddit/user). To search comments, use [Comment search](/reddit/search-comments). 1 credit per page of up to 100 results; see [Listings and pages](/listings).

  <Security permission="reddit:read" />

  <SchemaGroup title="Query parameters">
    <SchemaField name="q" type="string" location="query" required>
      The search query, 1 to 256 characters. Reddit's search syntax works for posts: `"exact phrase"`, `author:name`, `self:yes`.
    </SchemaField>

    <SchemaField name="type" type="string" optional location="query">
      `post` (default), `subreddit` or `user`.
    </SchemaField>

    <SchemaField name="sub" type="string" optional location="query">
      Only search posts in this subreddit.
    </SchemaField>

    <SchemaField name="sort" type="string" optional location="query">
      For posts: `relevance` (default), `new`, `top` or `comments`.
    </SchemaField>

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

    <SchemaField name="limit" type="integer" optional location="query">
      Results 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 results. Default `false`.
    </SchemaField>
  </SchemaGroup>

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

    ```jsonc
    // GET /v1/reddit/search?q=golang%20generics&limit=3
    {
      "subreddit": null,
      "query": "golang generics",
      "sort": "relevance",
      "count": 3,
      "items": [
        {
          "id": "lh7dkd",
          "name": "t3_lh7dkd",
          "subreddit": "programming",
          "title": "The Golang proposal to add generics has now been accepted.",
          "score": 713,
          "num_comments": 431,
          "url": "https://github.com/golang/go/issues/43651#issuecomment-776944155",
          "domain": "github.com",
          "created_at": "2021-02-10T23:42:03Z"
          // …the other post fields, as in Subreddit
        }
      ],
      "after": "t3_1wgu40p",
      "filtered_nsfw": 0
    }

    // GET /v1/reddit/search?q=golang&type=subreddit&limit=3
    {
      "query": "golang",
      "items": [
        {
          "name": "golang",
          "title": "The Go Programming Language",
          "public_description": "Ask questions and post articles about the Go programming language and related tools, events etc.",
          "subscribers": 380079,
          "created_at": "2009-11-11T00:54:28Z",
          "over_18": false,
          "type": "public",
          "url": "/r/golang/"
        }
      ],
      "after": "t5_3bzfq"
      // …
    }
    ```
  </div>

  <MethodSamples>
    <LanguageSample language="cURL">
      ```bash
      curl -G "https://api.threadapi.dev/v1/reddit/search" \
        --data-urlencode "q=self-hosted backup" \
        -d sub=selfhosted -d sort=top -d t=year \
        -H "Authorization: Bearer $THREADAPI_API_KEY"
      ```
    </LanguageSample>

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

      r = requests.get(
          "https://api.threadapi.dev/v1/reddit/search",
          params={"q": "self-hosted backup", "sub": "selfhosted", "sort": "top", "t": "year"},
          headers={"Authorization": f"Bearer {os.environ['THREADAPI_API_KEY']}"},
      )
      for post in r.json()["items"]:
          print(post["score"], post["title"])
      ```
    </LanguageSample>
  </MethodSamples>
</MethodPage>