threadsnoop-com Users API

openapi: 3.2.0
info:
  title: ThreadSnoop Reddit Read Users 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: Users
paths:
  /v1/users/{name}:
    get:
      operationId: getUserProfile
      summary: Get a Reddit user's profile aggregate
      description: 'Single-user karma/post/comment aggregate plus first/last activity timestamps, via an exact username match (not prefix/fuzzy search) — roughly Reddit''s own `/user/{name}/about`. A username with no matching Reddit account is still 1 credit (the lookup made a real upstream call either way) and comes back as a normal 200 with `data.user: null`, not a 404 — there is no null-data/404 branch in this API''s response pipeline, so a miss and a hit share the same envelope shape. Note: `data.user: null` also covers a second, distinct case with no way to tell them apart from the response alone — a real, active account that has enabled Reddit''s own profile privacy setting to hide its posts/comments. This endpoint only sees publicly visible Reddit content, so a fully-hidden profile has nothing to aggregate even though the account itself exists.'
      parameters:
      - name: name
        in: path
        required: true
        description: Reddit username, 3-64 characters, letters/digits/underscore/hyphen only (a generous charset guard, not Reddit's exact 3-20-char registration rule).
        schema:
          type: string
          pattern: ^[A-Za-z0-9_-]{3,64}$
          example: spez
      responses:
        '200':
          description: The user's profile aggregate, or null if no such user exists OR the account hides its posts/comments — see the operation description. Charged 1 credit either way.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfileEnvelope'
              example:
                data:
                  user:
                    author: spez
                    id: 1w72
                    _meta:
                      num_posts: 549
                      num_comments: 2568
                      post_karma: 832984
                      comment_karma: 666948
                      total_karma: 1499932
                      earliest_post_at: 1119552314
                      earliest_comment_at: 1134392748
                      last_post_at: 1751475161
                      last_comment_at: 1729645028
                _threadsnoop:
                  credits_used: 1
                  credits_remaining: 327
          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:
      - Users
components:
  schemas:
    UserProfile:
      type: object
      description: Single-user karma/post/comment aggregate, matched by exact username.
      properties:
        author:
          type: string
        id:
          type: string
        _meta:
          type: object
          properties:
            num_posts:
              type: integer
            num_comments:
              type: integer
            post_karma:
              type: integer
            comment_karma:
              type: integer
            total_karma:
              type: integer
            earliest_post_at:
              type: integer
            earliest_comment_at:
              type: integer
            last_post_at:
              type: integer
            last_comment_at:
              type: integer
      additionalProperties: true
    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
    UserProfileEnvelope:
      type: object
      properties:
        data:
          type: object
          properties:
            user:
              anyOf:
              - $ref: '#/components/schemas/UserProfile'
              - type: 'null'
              description: The user's profile, or null when no matching Reddit account exists.
        _threadsnoop:
          $ref: '#/components/schemas/Envelope'
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
  responses:
    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
    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
    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
    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
    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
  headers:
    CreditsRemaining:
      description: Balance remaining after this request.
      schema:
        type: integer
    CreditsUsed:
      description: Credits charged for this request (0 or 1).
      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.'