threadsnoop-com Account API

openapi: 3.2.0
info:
  title: ThreadSnoop Reddit Read Account 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: Account
paths:
  /v1/account:
    get:
      operationId: getAccount
      summary: Check your credit balance and rate limit
      description: Free — does not consume a credit and does not make an upstream request. Still key-authed and rate-limited like every other endpoint. Reads the balance fresh from the database (not the ~30s auth cache other endpoints may use), so it's always current.
      responses:
        '200':
          description: Current balance and rate limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountEnvelope'
              example:
                data:
                  credits_balance: 328
                  rate_limit:
                    qps: 2
                    burst: 10
                _threadsnoop:
                  credits_used: 0
                  credits_remaining: 328
          headers:
            x-credits-used:
              $ref: '#/components/headers/CreditsUsed'
            x-credits-remaining:
              $ref: '#/components/headers/CreditsRemaining'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Account
components:
  schemas:
    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
    AccountEnvelope:
      type: object
      properties:
        data:
          type: object
          properties:
            credits_balance:
              type: integer
            unlimited:
              type: boolean
              description: true only for internal admin accounts, which are never charged or blocked. Always false for customer keys — clients should generally ignore this field.
            rate_limit:
              type: object
              properties:
                qps:
                  type: integer
                burst:
                  type: integer
        _threadsnoop:
          $ref: '#/components/schemas/Envelope'
  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
    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.'