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

# Reddit Profile Posts

> Read one public account-submission page, up to 25 posts. Supports new, hot and top sorting; timeframe applies only to top. Cursors bind the account, sorting and date filters. Source timestamps are corroborated against epoch values. since requires new sorting and stops only when an ordered non-pinned source window crosses the bound; until filters each fetched page. The live index can repeat records. Deleted/private history, structured media, author avatars and content language are unavailable. Reddit scores are not likes; shares remain null. Initial upstream verification shares a fixed 200-provider-credit allowance; exhaustion blocks new provider calls.

Read one public account-submission page, up to 25 posts. Supports new, hot and top sorting; timeframe applies only to top. Cursors bind the account, sorting and date filters. Source timestamps are corroborated against epoch values. since requires new sorting and stops only when an ordered non-pinned source window crosses the bound; until filters each fetched page. The live index can repeat records. Deleted/private history, structured media, author avatars and content language are unavailable. Reddit scores are not likes; shares remain null.

One uncached successful request costs **1 SocialQuery credits**. Cache hits and failed requests cost zero. Empty successful source windows currently use the same base price; SocialCrawl’s empty-result refund policy is not implemented as parity. Initial provider verification shares a fixed 200-credit allowance; no automatic refill is enabled.


## OpenAPI

````yaml GET /reddit/profile/posts
openapi: 3.1.0
info:
  title: SocialQuery API
  version: '2026-10-09'
  description: >-
    Documented requests for public-source records. Inspect accepted inputs and
    credit amounts, then verify the selected operation before integrating
    preview coverage.
servers:
  - url: https://socialquery.dev/v1
security:
  - apiKey: []
paths:
  /reddit/profile/posts:
    get:
      tags:
        - Reddit
      summary: Reddit Profile Posts
      description: >-
        Read one public account-submission page, up to 25 posts. Supports new,
        hot and top sorting; timeframe applies only to top. Cursors bind the
        account, sorting and date filters. Source timestamps are corroborated
        against epoch values. since requires new sorting and stops only when an
        ordered non-pinned source window crosses the bound; until filters each
        fetched page. The live index can repeat records. Deleted/private
        history, structured media, author avatars and content language are
        unavailable. Reddit scores are not likes; shares remain null. Initial
        upstream verification shares a fixed 200-provider-credit allowance;
        exhaustion blocks new provider calls.
      operationId: get_reddit_profile_posts
      parameters:
        - name: handle
          in: query
          required: true
          example: spez
          schema:
            type: string
            pattern: ^[A-Za-z0-9_-]{2,25}$
        - name: sort
          in: query
          required: false
          schema:
            type: string
            enum:
              - hot
              - new
              - top
        - name: timeframe
          in: query
          required: false
          schema:
            type: string
            enum:
              - all
              - year
              - month
              - week
              - day
              - hour
          description: Only accepted with sort=top; defaults to all.
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: >-
            Opaque source cursor; keep all request filters and limit unchanged.
            Maximum 100 source pages.
        - name: since
          in: query
          required: false
          schema:
            type: string
          description: >-
            Valid YYYY-MM-DD or UTC ISO timestamp. since requires sort=new;
            until includes the entire UTC day for a date-only input. Apply to
            fetched source rows, retaining unknown dates.
        - name: until
          in: query
          required: false
          schema:
            type: string
          description: >-
            Valid YYYY-MM-DD or UTC ISO timestamp. since requires sort=new;
            until includes the entire UTC day for a date-only input. Apply to
            fetched source rows, retaining unknown dates.
        - name: Cache-Control
          in: header
          required: false
          example: no-cache
          schema:
            type: string
        - name: Idempotency-Key
          in: header
          required: false
          example: 7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c
          schema:
            type: string
        - name: X-Max-Credits
          in: header
          required: false
          description: >-
            Optional nonnegative integer cap on the maximum request hold. A live
            request whose hold exceeds this cap returns 422
            CREDIT_BUDGET_EXCEEDED before spending. Metered holds use the
            requested limit; cache hits and successful idempotent replays cost
            zero.
          schema:
            type: integer
            minimum: 0
      responses:
        '200':
          description: >-
            Read one public account-submission page, up to 25 posts. Supports
            new, hot and top sorting; timeframe applies only to top. Cursors
            bind the account, sorting and date filters. Source timestamps are
            corroborated against epoch values. since requires new sorting and
            stops only when an ordered non-pinned source window crosses the
            bound; until filters each fetched page. The live index can repeat
            records. Deleted/private history, structured media, author avatars
            and content language are unavailable. Reddit scores are not likes;
            shares remain null.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SocialQueryResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          source:
                            type: string
                            const: scrapebadger
                          coverage_note:
                            type: string
                          returned_count:
                            type: integer
                          source_window_count:
                            type: integer
                          total:
                            type: 'null'
                          next_cursor:
                            type:
                              - string
                              - 'null'
                          items:
                            type: array
                            items:
                              type: object
                              properties:
                                post:
                                  type: object
                                  properties:
                                    id:
                                      type: string
                                    url:
                                      type: string
                                    content:
                                      type: object
                                      properties:
                                        text:
                                          type:
                                            - string
                                            - 'null'
                                        media_urls:
                                          type: 'null'
                                        thumbnail_url:
                                          type: 'null'
                                        duration_seconds:
                                          type: 'null'
                                    author:
                                      type: object
                                      properties:
                                        username:
                                          type: string
                                        display_name:
                                          type: string
                                        avatar_url:
                                          type: 'null'
                                        verified:
                                          type: 'null'
                                    engagement:
                                      type: object
                                      properties:
                                        views:
                                          type:
                                            - integer
                                            - 'null'
                                        likes:
                                          type: 'null'
                                        comments:
                                          type:
                                            - integer
                                            - 'null'
                                        shares:
                                          type: 'null'
                                        saves:
                                          type: 'null'
                                    flags:
                                      type: object
                                      properties:
                                        nsfw:
                                          type:
                                            - boolean
                                            - 'null'
                                        spoiler:
                                          type:
                                            - boolean
                                            - 'null'
                                        pinned:
                                          type:
                                            - boolean
                                            - 'null'
                                        deleted:
                                          type: 'null'
                                    published_at:
                                      type:
                                        - string
                                        - 'null'
                                    ext:
                                      type: object
                                      properties:
                                        title:
                                          type:
                                            - string
                                            - 'null'
                                        subreddit:
                                          type: string
                                        score:
                                          type:
                                            - integer
                                            - 'null'
                                        upvote_ratio:
                                          type:
                                            - number
                                            - 'null'
                                        selftext:
                                          type:
                                            - string
                                            - 'null'
                                        flair:
                                          type:
                                            - string
                                            - 'null'
                                        content_language:
                                          type: 'null'
                          stopped_at:
                            type:
                              - string
                              - 'null'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '402':
          $ref: '#/components/responses/Error402'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '405':
          $ref: '#/components/responses/Error405'
        '409':
          $ref: '#/components/responses/Error409'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '502':
          $ref: '#/components/responses/Error502'
        '503':
          $ref: '#/components/responses/Error503'
        '504':
          $ref: '#/components/responses/Error504'
components:
  schemas:
    SocialQueryResponse:
      type: object
      required:
        - success
        - platform
        - endpoint
        - credits_used
        - credits_remaining
        - request_id
        - cached
        - data
      properties:
        success:
          type: boolean
          const: true
        platform:
          type: string
        endpoint:
          type: string
        credits_used:
          type: integer
          minimum: 0
        credits_remaining:
          type:
            - integer
            - 'null'
        request_id:
          type: string
        cached:
          type: boolean
        data:
          type: object
          additionalProperties: true
          description: >-
            The selected operation determines the resource fields in this
            object. Source data can omit a metric or report it as null.
    SocialQueryError:
      type: object
      required:
        - success
        - platform
        - endpoint
        - credits_used
        - credits_remaining
        - request_id
        - cached
        - error
      properties:
        success:
          type: boolean
          const: false
        platform:
          type: string
        endpoint:
          type: string
        credits_used:
          type: integer
          minimum: 0
        credits_remaining:
          type:
            - integer
            - 'null'
        request_id:
          type: string
        cached:
          type: boolean
        error:
          type: object
          required:
            - code
            - type
            - message
            - status
            - doc_url
          properties:
            code:
              type: string
            type:
              type: string
            message:
              type: string
            status:
              type: integer
            doc_url:
              type: string
              format: uri
  responses:
    Error400:
      description: Upstream rejected the request.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error401:
      description: Missing, expired, invalid, or revoked API key.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error402:
      description: Insufficient SocialQuery credits.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error403:
      description: Key scope or provider policy denied access.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error404:
      description: Endpoint or upstream resource not found.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error405:
      description: HTTP method is not supported.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error409:
      description: Idempotency conflict or request in progress.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error422:
      description: Invalid parameters.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error429:
      description: Request limit reached.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error500:
      description: Request processing failed.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error502:
      description: Upstream service failed.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error503:
      description: Provider or required service is unavailable.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error504:
      description: Upstream service timed out.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key

````

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