> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scraperize.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search

> Searches all of Reddit like reddit.com/search: posts (7 per page) or comments (10 per page), sorted by relevance, new, top or comment count (posts only), over a time range (posts only). Posts come with their title, link, subreddit (and its icon), author, time, score, comment count, matching snippet and spoiler flag; comments with their text, links, author, time, link and the post they were left on (its title, score and comment count). Reddit leaves NSFW results out for logged-out visitors. Pass the returned `cursor` back (with the same query) for the next page. Only publicly available data is returned.

> [!NOTE]
>
> **Cost: 1 credit** per successful request. Errors and cache hits (`cache_max_age`) are free.

> [accordion] Copy for AI assistant
>
> Paste this into ChatGPT, Claude or your coding assistant to generate working code for this endpoint (use the copy button).
>
> ```text Prompt
> I want to make an API call to /v1/reddit/search. Here are the details:
>
> Endpoint: GET https://api.scraperize.com/v1/reddit/search
> Description: Searches all of Reddit like reddit.com/search: posts (7 per page) or comments (10 per page), sorted by relevance, new, top or comment count (posts only), over a time range (posts only). Posts come with their title, link, subreddit (and its icon), author, time, score, comment count, matching snippet and spoiler flag; comments with their text, links, author, time, link and the post they were left on (its title, score and comment count). Reddit leaves NSFW results out for logged-out visitors. Pass the returned `cursor` back (with the same query) for the next page. Only publicly available data is returned.
>
> Required Headers:
> - x-api-key: Your API key
>
> Parameters:
> - query (string) [required]: What to search for.
> - filter (select): `posts` (default) or `comments`.
> - sort (select): `relevance` (default), `new`, `top` or `comment_count` (posts only). For comments: `relevance`, `new` or `top`.
> - timeframe (select): Posts only: `all` (default), `day`, `week`, `month` or `year`.
> - cursor (string): The `cursor` from the previous page (it keeps the filter, sort and time range). Omit for the first page.
> - cache_max_age (select): Optional. Return a cached result if one this age or newer exists — served for **0 credits** with `meta.cached=true` and `meta.cachedAt`. Otherwise a fresh scrape runs (**1 credit**) and refreshes the cache. Omit to always scrape fresh.
>
> Example Response:
> {
>   "data": {
>     "query": "rust programming",
>     "timeframe": null,
>     "results": [
>       {
>         "position": 1,
>         "id": "1xo113w",
>         "url": "https://www.reddit.com/r/linux_gaming/comments/1xo113w/discord_is_rewriting_its_entire_desktop_client_in/",
>         "title": "Discord is rewriting its entire desktop client in Rust with a native GPUI-based interface (dropping both Electron and React Native)",
>         "subreddit": "linux_gaming",
>         "subredditId": "t5_2r2u0",
>         "subredditIconUrl": "https://styles.redditmedia.com/t5_2r2u0/styles/communityIcon_nrhnuu07r3k21.png?width=64&frame=1&auto=webp&s=14cf83d5a8332153bd86d75a137423f569d17296",
>         "author": "mr_MADAFAKA",
>         "authorId": "t2_xplyssp",
>         "createdAt": "2026-11-04T21:50:25.996Z",
>         "score": 3137,
>         "commentCount": 545,
>         "snippet": "One less electron app constantly running in the backround",
>         "thumbnailUrl": null,
>         "thumbnailWidth": null,
>         "thumbnailHeight": null,
>         "isNsfw": false,
>         "isSpoiler": false
>       }
>     ],
>     "count": 7,
>     "cursor": "eyJrIjoiYWxsIiwicSI6InJ1c3QgcHJvZ3JhbW1pbmciLCJ5IjoicG9zdHMiLCJvIjpudWxsLCJ0IjpudWxsLCJjIjoiZXlKallXNWthV1JoZEdWelgzSmxkSFZ5Ym1Wa0lqb2llMXdpYzJWamRHbHZibDh4WDNC…",
>     "hasMore": true,
>     "fetchedAt": "2026-11-06T12:49:23.931Z",
>     "filter": "posts",
>     "sort": "relevance"
>   },
>   "meta": {
>     "requestId": "req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f",
>     "creditsCharged": 1,
>     "creditsRemaining": 4999,
>     "cached": false
>   }
> }
>
> Please help me write code in my preferred programming language to make this API call and handle the response appropriately. Include error handling and best practices.
> ```


## OpenAPI

````yaml /api-reference/openapi.json get /v1/reddit/search
openapi: 3.0.3
info:
  title: Scraperize API
  version: 1.0.0
  description: >-
    Extract public data from social media platforms as clean JSON. Endpoints are
    split by platform and by what they return, e.g. `GET /v1/twitter/tweet`.


    ## Authentication

    Send your API key in the `x-api-key` header (or `Authorization: Bearer
    <key>`). Create keys in your dashboard.


    ## Credits

    Each successful live scrape costs **1 credit**. Credits are prepaid and
    never expire.


    ## Caching

    Every endpoint accepts an optional `cache_max_age`
    (`1d`|`3d`|`7d`|`14d`|`30d`). A cache hit within that window is returned for
    **0 credits**.


    ## Responses

    Success returns `{ "data": …, "meta": { "requestId", … } }`. Errors return
    `{ "error": { "code", "message", "requestId" } }` with a matching HTTP
    status. `meta` on a scrape carries `creditsCharged`, `creditsRemaining`,
    `cached`, and (on a hit) `cachedAt`.


    ## Rate limits

    Requests are limited per team per minute; over the limit returns `429` with
    a `Retry-After` header.
servers:
  - url: https://api.scraperize.com
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Twitter
    description: Twitter / X scraping endpoints
  - name: Facebook
    description: Facebook scraping endpoints
  - name: Linkme
    description: Linkme (link.me) scraping endpoints
  - name: Amazon
    description: Amazon (creator shop / storefront) scraping endpoints
  - name: Linkbio
    description: Linkbio (lnk.bio) scraping endpoints
  - name: Pillar
    description: Pillar (pillar.io) scraping endpoints
  - name: Komi
    description: Komi (komi.io) scraping endpoints
  - name: Linktree
    description: Linktree (linktr.ee) scraping endpoints
  - name: Kick
    description: Kick (kick.com) scraping endpoints
  - name: Snapchat
    description: Snapchat (snapchat.com) scraping endpoints
  - name: Telegram
    description: Telegram (t.me) scraping endpoints
  - name: LinkedIn
    description: LinkedIn scraping endpoints
  - name: Twitch
    description: Twitch scraping endpoints
  - name: TikTok
    description: TikTok (tiktok.com) scraping endpoints
  - name: Instagram
    description: Instagram scraping endpoints
  - name: Lagos Life
    description: Lagos Life scraping endpoints
  - name: Bluesky
    description: Bluesky (bsky.app) scraping endpoints
  - name: Threads
    description: Threads (threads.com) scraping endpoints
  - name: Reddit
    description: Reddit (reddit.com) scraping endpoints
  - name: Rumble
    description: Rumble (rumble.com) scraping endpoints
  - name: Truth Social
    description: Truth Social (truthsocial.com) scraping endpoints
  - name: YouTube
    description: YouTube (youtube.com) scraping endpoints
paths:
  /v1/reddit/search:
    get:
      tags:
        - Reddit
      summary: Search
      description: >-
        Searches all of Reddit like reddit.com/search: posts (7 per page) or
        comments (10 per page), sorted by relevance, new, top or comment count
        (posts only), over a time range (posts only). Posts come with their
        title, link, subreddit (and its icon), author, time, score, comment
        count, matching snippet and spoiler flag; comments with their text,
        links, author, time, link and the post they were left on (its title,
        score and comment count). Reddit leaves NSFW results out for logged-out
        visitors. Pass the returned `cursor` back (with the same query) for the
        next page. Only publicly available data is returned.
      parameters:
        - name: query
          in: query
          required: true
          description: What to search for.
          schema:
            type: string
          example: rust programming
        - name: filter
          in: query
          required: false
          description: '`posts` (default) or `comments`.'
          schema:
            type: string
            enum:
              - posts
              - comments
            default: posts
        - name: sort
          in: query
          required: false
          description: >-
            `relevance` (default), `new`, `top` or `comment_count` (posts only).
            For comments: `relevance`, `new` or `top`.
          schema:
            type: string
            enum:
              - relevance
              - new
              - top
              - comment_count
            default: relevance
        - name: timeframe
          in: query
          required: false
          description: 'Posts only: `all` (default), `day`, `week`, `month` or `year`.'
          schema:
            type: string
            enum:
              - all
              - day
              - week
              - month
              - year
        - name: cursor
          in: query
          required: false
          description: >-
            The `cursor` from the previous page (it keeps the filter, sort and
            time range). Omit for the first page.
          schema:
            type: string
        - name: cache_max_age
          in: query
          required: false
          description: >-
            Optional. Return a cached result if one this age or newer exists —
            served for **0 credits** with `meta.cached=true` and
            `meta.cachedAt`. Otherwise a fresh scrape runs (**1 credit**) and
            refreshes the cache. Omit to always scrape fresh.
          schema:
            type: string
            enum:
              - 1d
              - 3d
              - 7d
              - 14d
              - 30d
          example: 7d
      responses:
        '200':
          description: One page of results (empty when nothing matches).
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      query:
                        type: string
                      filter:
                        type: string
                      sort:
                        type: string
                      timeframe:
                        type: string
                        nullable: true
                      results:
                        type: array
                        items:
                          type: object
                      count:
                        type: integer
                      cursor:
                        type: string
                        nullable: true
                      hasMore:
                        type: boolean
                      fetchedAt:
                        type: string
                        format: date-time
                  meta:
                    type: object
                    description: >-
                      requestId + credit/caching metadata (creditsCharged,
                      creditsRemaining, cached, cachedAt).
                required:
                  - data
                  - meta
              example:
                data:
                  query: rust programming
                  timeframe: null
                  results:
                    - position: 1
                      id: 1xo113w
                      url: >-
                        https://www.reddit.com/r/linux_gaming/comments/1xo113w/discord_is_rewriting_its_entire_desktop_client_in/
                      title: >-
                        Discord is rewriting its entire desktop client in Rust
                        with a native GPUI-based interface (dropping both
                        Electron and React Native)
                      subreddit: linux_gaming
                      subredditId: t5_2r2u0
                      subredditIconUrl: >-
                        https://styles.redditmedia.com/t5_2r2u0/styles/communityIcon_nrhnuu07r3k21.png?width=64&frame=1&auto=webp&s=14cf83d5a8332153bd86d75a137423f569d17296
                      author: mr_MADAFAKA
                      authorId: t2_xplyssp
                      createdAt: '2026-11-04T21:50:25.996Z'
                      score: 3137
                      commentCount: 545
                      snippet: >-
                        One less electron app constantly running in the
                        backround
                      thumbnailUrl: null
                      thumbnailWidth: null
                      thumbnailHeight: null
                      isNsfw: false
                      isSpoiler: false
                    - position: 2
                      id: 1xlwg4h
                      url: >-
                        https://www.reddit.com/r/rust/comments/1xlwg4h/cleanest_best_written_rust_codebases/
                      title: Cleanest, best written rust codebases?
                      subreddit: rust
                      subredditId: t5_2s7lj
                      subredditIconUrl: >-
                        https://styles.redditmedia.com/t5_2s7lj/styles/communityIcon_pjg3ktzyju771.png?width=64&frame=1&auto=webp&s=5671c7524b4e747cb1cb2d48f9fda80f3ceaefce
                      author: FractalFir
                      authorId: t2_rsgb6w3y
                      createdAt: '2026-11-02T12:56:49.047Z'
                      score: 189
                      commentCount: 39
                      snippet: ripgrep, fd, niri, awww, gifski, dua-cli
                      thumbnailUrl: null
                      thumbnailWidth: null
                      thumbnailHeight: null
                      isNsfw: false
                      isSpoiler: false
                    - position: 3
                      id: 1xoulve
                      url: >-
                        https://www.reddit.com/r/rust/comments/1xoulve/the_best_regression_test_we_added_this_year/
                      title: >-
                        The best regression test we added this year checks that
                        some Rust code does NOT compile
                      subreddit: rust
                      subredditId: t5_2s7lj
                      subredditIconUrl: >-
                        https://styles.redditmedia.com/t5_2s7lj/styles/communityIcon_pjg3ktzyju771.png?width=64&frame=1&auto=webp&s=5671c7524b4e747cb1cb2d48f9fda80f3ceaefce
                      author: TroutWindlass
                      authorId: t2_2psn91k694
                      createdAt: '2026-11-05T21:18:43.377Z'
                      score: 54
                      commentCount: 12
                      snippet: null
                      thumbnailUrl: null
                      thumbnailWidth: null
                      thumbnailHeight: null
                      isNsfw: false
                      isSpoiler: false
                  count: 7
                  cursor: >-
                    eyJrIjoiYWxsIiwicSI6InJ1c3QgcHJvZ3JhbW1pbmciLCJ5IjoicG9zdHMiLCJvIjpudWxsLCJ0IjpudWxsLCJjIjoiZXlKallXNWthV1JoZEdWelgzSmxkSFZ5Ym1Wa0lqb2llMXdpYzJWamRHbHZibDh4WDNCcGNHVnNhVzVsWHpCZloyeHZZbUZzWDIxdlpHbG1hV1Z5YzF3aU9sd2lNVndpTEZ3aWMyVmpkR2x2Ymw4eFgzQnBjR1ZzYVc1bFh6RmZiRzlqWVd4ZmJXOWthV1pwWlhKelhDSTZYQ0l5WENJc1hDSnpaV04wYVc5dVh6SmZjR2x3Wld4cGJtVmZNVEZmY1hWbGNubGZjM1ZuWjJWemRHbHZibk5jSWpwY0lqWmNJaXhjSW5ObFkzUnBiMjVmTWw5d2FYQmxiR2x1WlY4NFgyUjVibUZ0YVdOZk1GOXdiM04wWDNObFlYSmphRndpT2x3aU4xd2lMRndpYzJWamRHbHZibDh6WDNCcGNHVnNhVzVsWHpCZlpIbHVZVzFwWTE4d1gzTjFZbkpsWkdScGRGOXpaV0Z5WTJoY0lqcGNJalZjSW4waUxDSmxlSEJsY21sbGJtTmxYM05sYkdWamRHbHZiaUk2SW5CdmMzUnpYM1l5SWl3aVpYaHdaWEpwWlc1alpWOTJaWEp6YVc5dUlqb2laR1Z6YTNSdmNDSXNJbk5sWTNScGIyNWZNbDl3YVhCbGJHbHVaVjg0WDJSNWJtRnRhV05mTUY5d2IzTjBYM05sWVhKamFDSTZJamNpZlE9PSJ9
                  hasMore: true
                  fetchedAt: '2026-11-06T12:49:23.931Z'
                  filter: posts
                  sort: relevance
                meta:
                  requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
                  creditsCharged: 1
                  creditsRemaining: 4999
                  cached: false
        '400':
          description: Invalid or expired cursor (or one for another query).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: BAD_REQUEST
                  message: The request was invalid.
                  requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
        '401':
          description: Missing, invalid, or revoked API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: UNAUTHORIZED
                  message: API key required — pass it in the `x-api-key` header.
                  requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
        '402':
          description: Not enough credits for this request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: INSUFFICIENT_CREDITS
                  message: >-
                    This request costs 1 credit, but your balance is 0. Top up
                    to continue.
                  requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
        '422':
          description: >-
            Invalid query parameters (`comment_count` and `timeframe` are for
            posts only).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: VALIDATION_ERROR
                  message: Request validation failed
                  requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
                  details:
                    - path: url
                      message: url is required
        '429':
          description: Over the per-minute rate limit — honour `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: RATE_LIMITED
                  message: >-
                    Rate limit exceeded — max 100 requests per 60s. Retry in
                    ~30s.
                  requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
        '503':
          description: >-
            Temporarily unavailable — retry after `Retry-After`. `error.code`
            tells you why: `UPSTREAM_BLOCKED` (the source blocked this request),
            `EXTRACTION_FAILED` (the source returned unexpected data),
            `PLATFORM_UNAVAILABLE` (the source is down), or
            `SERVICE_UNAVAILABLE` (we are at capacity).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: UPSTREAM_BLOCKED
                  message: >-
                    The source is temporarily unavailable. Please try again
                    shortly.
                  requestId: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: NOT_FOUND
            message:
              type: string
              example: The requested content was not found.
            requestId:
              type: string
              example: req_8f0c2b7e-1a2b-4c3d-9e8f-0a1b2c3d4e5f
            details:
              type: array
              items:
                type: object
              description: Present on validation errors.
          required:
            - code
            - message
            - requestId
      required:
        - error
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Your API key. Send it in the `x-api-key` header (or `Authorization:
        Bearer <key>`). Create and manage keys from your dashboard.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.