threadsnoop-com Comments API

openapi: 3.2.0
info:
  title: ThreadSnoop Reddit Read Comments API
  version: 1.0.0
  description: 'Read-only access to Reddit: posts, comments, comment trees, subreddit search, subreddit rules, and user profiles. Pay-as-you-go, 1 credit = 1 request, 100 free Reddit searches on signup. No writes, votes, DMs, or auth-ed Reddit actions — read-only, permanently. See https://threadsnoop.com/docs for the human-readable guide.'
  contact:
    email: hello@threadsnoop.com
servers:
- url: https://api.threadsnoop.com
security:
- ApiKeyHeader: []
- BearerAuth: []
tags:
- name: Comments
paths:
  /v1/comments:
    get:
      operationId: listComments
      summary: List or fetch Reddit comments
      description: 'Two modes on one endpoint, mirroring /v1/posts. Listing mode: pass `subreddit` and/or `author` (at least one required) to page through comments, newest-first by default. Batch mode: pass `ids` (comma-separated comment ids, capped at 100) to fetch specific comments by id in a single request — all other listing params (`after`, `before`, `sort`, `q`) are ignored in this mode, and the response has `cursor: null` / `has_more: false` since there is no next page for a fixed id list. 1 credit per request in either mode.'
      parameters:
      - $ref: '#/components/parameters/Subreddit'
      - $ref: '#/components/parameters/Author'
      - name: ids
        in: query
        description: Comma-separated comment ids to fetch directly (batch mode). Truncated to the first 100 if more are given. When present, `subreddit`/`author`/`after`/`before`/`sort`/`q` are ignored. If even one id in the list is invalid or malformed, the whole call returns a 400 (credit refunded) rather than silently skipping the bad id — verify ids came from a real search result first.
        schema:
          type: string
          example: kxyzabc,kdefghi
      - $ref: '#/components/parameters/After'
      - $ref: '#/components/parameters/Before'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Sort'
      - $ref: '#/components/parameters/Fields'
      - $ref: '#/components/parameters/Q'
      responses:
        '200':
          description: A page of comments.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentListEnvelope'
              example:
                data:
                - id: kxyzabc
                  body: I've been looking for exactly this, what did you end up using?
                  author: another_user
                  created_utc: 1753001200
                  subreddit: SaaS
                  link_id: t3_1abcxyz
                  parent_id: t3_1abcxyz
                  permalink: /r/SaaS/comments/1abcxyz/anyone_know_a_tool_that_watches_reddit_for_me/kxyzabc/
                _threadsnoop:
                  cursor: 1753001200
                  has_more: true
                  credits_used: 1
                  credits_remaining: 331
          headers:
            x-credits-used:
              $ref: '#/components/headers/CreditsUsed'
            x-credits-remaining:
              $ref: '#/components/headers/CreditsRemaining'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
      tags:
      - Comments
  /v1/comments/tree:
    get:
      operationId: getCommentTree
      summary: Get the full comment tree for a post
      description: Returns the complete nested comment tree for a post in one call, including a real comment count that is accurate even during Reddit's ~36-hour hide_score blackout window (when the post's own num_comments reads 0). Not paginated — cursor/has_more are always null/false since one call returns everything.
      parameters:
      - name: post_id
        in: query
        required: true
        description: Post id, with or without the `t3_` prefix. An invalid or malformed id returns a 400 (credit refunded) — retrying with the same bad id won't help.
        schema:
          type: string
          example: 1abcxyz
      - name: limit
        in: query
        description: Max comments to return.
        schema:
          type: integer
          minimum: 1
          maximum: 500
          default: 50
      responses:
        '200':
          description: The post's comment tree.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentTreeEnvelope'
              example:
                data:
                - kind: t1
                  data:
                    id: kxyzabc
                    body: I've been looking for exactly this
                    author: another_user
                    created_utc: 1753001200
                    subreddit: SaaS
                    link_id: t3_1abcxyz
                    parent_id: t3_1abcxyz
                    score: 3
                  replies: []
                _threadsnoop:
                  cursor: null
                  has_more: false
                  credits_used: 1
                  credits_remaining: 330
          headers:
            x-credits-used:
              $ref: '#/components/headers/CreditsUsed'
            x-credits-remaining:
              $ref: '#/components/headers/CreditsRemaining'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
      tags:
      - Comments
components:
  parameters:
    Fields:
      name: fields
      in: query
      description: 'Comma-separated field allowlist forwarded upstream. Confirmed-safe for posts: id,title,selftext,author,created_utc,subreddit,score,num_comments,url,over_18,link_flair_text,spoiler. Confirmed-safe for comments: id,body,author,created_utc,subreddit,link_id,parent_id,score. This is NOT the full Reddit object schema — many real fields are rejected upstream (e.g. permalink, hide_score, domain, ups, stickied) with a 400 naming exactly which field was invalid; if unsure, omit fields entirely and read the full untrimmed object instead of guessing names.'
      schema:
        type: string
    After:
      name: after
      in: query
      description: Lower bound on created_utc. Accepts an epoch-seconds integer or a relative form like `7d`, passed through as-is.
      schema:
        type: string
        example: 7d
    Q:
      name: q
      in: query
      description: 'Client-side exact-phrase filter (with basic plural flexibility), applied ONLY to the single page this call fetches (limit, default 25, max 100) — not a search across the whole after/before window. A page with zero matches does NOT mean no matches exist in your date range: cursor/has_more always reflect the RAW page, not the filtered subset, so check has_more and keep paginating with the returned cursor. For an active subreddit one page can span just minutes, so scanning several days for a specific phrase often takes many calls; every page costs 1 credit whether it matched or not. See the pagination guide.'
      schema:
        type: string
    Limit:
      name: limit
      in: query
      description: Page size.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
    Author:
      name: author
      in: query
      description: Reddit username (without u/). At least one of subreddit/author/ids is required.
      schema:
        type: string
    Before:
      name: before
      in: query
      description: Upper bound on created_utc. Same accepted forms as `after`.
      schema:
        type: string
    Subreddit:
      name: subreddit
      in: query
      description: Subreddit name (without r/). At least one of subreddit/author/ids is required.
      schema:
        type: string
        example: SaaS
    Sort:
      name: sort
      in: query
      description: Sort order by created_utc.
      schema:
        type: string
        enum:
        - asc
        - desc
        default: desc
  responses:
    Unauthorized:
      description: Missing, invalid, or revoked API key. Not charged (no key to attribute usage to).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: invalid or revoked api key
    PaymentRequired:
      description: Insufficient credit balance. Not charged (the debit is the balance check — it never went through).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: insufficient credits — top up at https://threadsnoop.com/api
    RateLimited:
      description: 'Rate limit exceeded — either your key''s own 2 req/s (burst 10) limit, or the shared global upstream ceiling (marked by the `x-ratelimit-scope: global` header, present only for the global case). Not charged.'
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
        x-ratelimit-scope:
          description: Present and set to `global` only when the shared upstream ceiling (not your per-key limit) was hit.
          schema:
            type: string
            enum:
            - global
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: rate limit exceeded
    BadRequest:
      description: Invalid or missing parameters. Not charged.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: at least one of subreddit, author, or ids is required
    UpstreamUnavailable:
      description: The upstream data source was unreachable or errored after the connector's retry policy was exhausted. Any credit debited for this request is automatically refunded. When the upstream is busy, a Retry-After header gives the number of seconds to wait before retrying.
      headers:
        Retry-After:
          description: Seconds to wait before retrying. Present when the upstream reported it was busy.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: upstream temporarily unavailable — credit refunded
  schemas:
    CommentListEnvelope:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Comment'
        _threadsnoop:
          $ref: '#/components/schemas/Envelope'
    CommentTreeEnvelope:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/CommentTreeNode'
        _threadsnoop:
          $ref: '#/components/schemas/Envelope'
    Comment:
      type: object
      description: Full Reddit comment object, untrimmed unless you pass `fields=`.
      properties:
        id:
          type: string
        body:
          type: string
        author:
          type: string
        created_utc:
          type: integer
        subreddit:
          type: string
        link_id:
          type: string
          description: Fullname (t3_...) of the parent post.
        parent_id:
          type: string
          description: Fullname of the immediate parent (post or comment).
        permalink:
          type: string
          description: Relative path on reddit.com. Prepend https://www.reddit.com for a clickable URL.
      additionalProperties: true
    CommentTreeNode:
      type: object
      properties:
        kind:
          type: string
        data:
          allOf:
          - $ref: '#/components/schemas/Comment'
          - type: object
            properties:
              score:
                type: integer
        replies:
          type: array
          items:
            $ref: '#/components/schemas/CommentTreeNode'
    Envelope:
      type: object
      properties:
        cursor:
          type:
          - integer
          - 'null'
          description: created_utc of the last row in this page (raw page, pre-filter if q= was used). Pass as `after` (sort=asc) or `before` (sort=desc) to fetch the next page. Null when the page was empty or the endpoint isn't paginated.
        has_more:
          type: boolean
        credits_used:
          type: integer
        credits_remaining:
          type: integer
      required:
      - credits_used
      - credits_remaining
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
  headers:
    CreditsUsed:
      description: Credits charged for this request (0 or 1).
      schema:
        type: integer
    CreditsRemaining:
      description: Balance remaining after this request.
      schema:
        type: integer
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Authorization: Bearer <your key>. Equivalent to x-api-key; either header works.'