> ## 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.

# Kohl’s Reviews

> Approved public English-US feedback from the retailer’s published display source. Independently verifies product identity, retains actual related-variant IDs through native product-family relationships, and supports bounded pagination with empty-result refunds.

Returns approved public English-US feedback from the review widget published by Kohl’s. Supply `product_id`, a matching regional product URL, or a continuation cursor. A separate product display lookup confirms identity; a source-confirmed missing product returns 404.

The source groups related variants into native product families. **Results are not necessarily for the exact requested variant.** Every row retains its actual `product` ID, name, URL when available, and `family_ids`. Related IDs must have a source-corroborated family relationship to the requested product. A retired related product can have a null URL; no replacement URL is invented. Tracking parameters are stripped from returned product links.

Each review retains its native rating/scale, title, text, public nickname, timestamp, recommendation flag when present, actual product ID and syndication metadata. Source rating-only records are excluded. No verified-purchase or reviewer-identity status is inferred.

`since` and `until` apply inclusive valid `YYYY-MM-DD` bounds to each fetched page by UTC publication date. They preserve candidate offsets and totals. An empty filtered page can still have a next cursor and costs zero. AI labels, reports, judgments, dry-run analysis and fit enrichment are unavailable; only `label=none` and `judgments=off` are accepted.

`page` is one-based and `limit` is 1–50, default 10. Results use native newest-first order. `total` is the source's family/locale candidate count, identified by `total_scope`; it is not an exact-SKU or all-locale count. Cursors bind product, limit and filters for one hour and corroborate the preceding record. Source changes can require restarting. Offsets stop at 10,000, with `pagination_capped` identifying a local ceiling.

The response selects public feedback fields only. It excludes IP addresses, internal author/submission IDs, contact details and raw provider objects. No customer account access or feedback submission is used. The source URL omits the public display configuration parameter.

A fresh nonempty page costs **5 credits**. Empty pages, failures, cache hits and successful idempotent replays cost zero. Use `X-Max-Credits: 5`. Each request uses two anonymous display reads, or three with a cursor. A shared 20-source-request/minute limit, 25-second total timeout and 2 MiB limit per response apply. Public-source availability has no contractual SLA.


## OpenAPI

````yaml GET /kohls/reviews
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:
  /kohls/reviews:
    get:
      tags:
        - Kohls
      summary: Kohls Reviews
      description: >-
        Approved public English-US feedback from the retailer’s published
        display source. Independently verifies product identity, retains actual
        related-variant IDs through native product-family relationships, and
        supports bounded pagination with empty-result refunds.
      operationId: get_kohls_reviews
      parameters:
        - name: product_id
          in: query
          required: false
          example: '1695762'
          schema:
            type: string
            pattern: ^[1-9][0-9]{0,17}$
          description: >-
            Native product ID. Supply product_id, a matching product URL, or a
            continuation cursor.
        - name: url
          in: query
          required: false
          schema:
            type: string
          description: >-
            Canonical HTTPS www.kohls.com/product/prd-ID/product.jsp URL, or its
            ID path. Parsed only; never followed. Must match any supplied
            product_id.
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
          description: >-
            One-based page. (page-1)*limit must not exceed 10,000. A supplied
            page must match the cursor offset.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 10
          description: Native feedback page size, 1–50; default 10.
        - name: label
          in: query
          required: false
          schema:
            type: string
          description: No AI enrichment is implemented; only label=none is accepted.
        - name: reports
          in: query
          required: false
          schema:
            type: string
          description: >-
            Unavailable from this adapter; specifying this option fails
            explicitly.
        - name: judgments
          in: query
          required: false
          schema:
            type: string
            enum:
              - 'on'
              - 'off'
          description: No AI enrichment is implemented; only judgments=off is accepted.
        - name: dry_run
          in: query
          required: false
          schema:
            type: string
            enum:
              - '1'
          description: >-
            Unavailable from this adapter; specifying this option fails
            explicitly.
        - name: label_evidence
          in: query
          required: false
          schema:
            type: string
            enum:
              - '1'
          description: >-
            Unavailable from this adapter; specifying this option fails
            explicitly.
        - name: fit
          in: query
          required: false
          schema:
            type: string
            enum:
              - goal
          description: >-
            Unavailable from this adapter; specifying this option fails
            explicitly.
        - name: goal
          in: query
          required: false
          schema:
            type: string
          description: >-
            Unavailable from this adapter; specifying this option fails
            explicitly.
        - name: fit_tokens
          in: query
          required: false
          schema:
            type: integer
          description: >-
            Unavailable from this adapter; specifying this option fails
            explicitly.
        - name: since
          in: query
          required: false
          schema:
            type: string
            pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
          description: >-
            Inclusive valid YYYY-MM-DD filter on each candidate page by UTC
            publication date; total remains the native unfiltered family/locale
            total. Empty filtered pages can continue and are free.
        - name: until
          in: query
          required: false
          schema:
            type: string
            pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
          description: >-
            Inclusive valid YYYY-MM-DD filter on each candidate page by UTC
            publication date; total remains the native unfiltered family/locale
            total. Empty filtered pages can continue and are free.
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: >-
            One-hour cursor retaining product, limit and date filters. Rechecks
            the preceding native record. May be supplied without product_id/url.
        - 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: >-
            Approved public English-US feedback from the retailer’s published
            display source. Independently verifies product identity, retains
            actual related-variant IDs through native product-family
            relationships, and supports bounded pagination with empty-result
            refunds.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SocialQueryResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          product:
                            type: object
                            properties:
                              id:
                                type: string
                              name:
                                type: string
                              url:
                                type:
                                  - string
                                  - 'null'
                              family_ids:
                                type: array
                                items:
                                  type: string
                            required:
                              - id
                              - name
                              - url
                              - family_ids
                          items:
                            type: array
                            items:
                              type: object
                              properties:
                                review:
                                  type: object
                                  properties:
                                    id:
                                      type: string
                                    published_at:
                                      type: string
                                      format: date-time
                                    author_name:
                                      type:
                                        - string
                                        - 'null'
                                    locale:
                                      type: string
                                    is_syndicated:
                                      type: boolean
                                    source_client:
                                      type:
                                        - string
                                        - 'null'
                                    product:
                                      type: object
                                      properties:
                                        id:
                                          type: string
                                        name:
                                          type: string
                                        url:
                                          type:
                                            - string
                                            - 'null'
                                        family_ids:
                                          type: array
                                          items:
                                            type: string
                                      required:
                                        - id
                                        - name
                                        - url
                                        - family_ids
                                    title:
                                      type:
                                        - string
                                        - 'null'
                                    text:
                                      type: string
                                    rating:
                                      type: number
                                      minimum: 0
                                    rating_scale:
                                      type: number
                                      exclusiveMinimum: 0
                                    recommended:
                                      type:
                                        - boolean
                                        - 'null'
                                  required:
                                    - id
                                    - published_at
                                    - author_name
                                    - locale
                                    - is_syndicated
                                    - source_client
                                    - product
                                    - title
                                    - text
                                    - rating
                                    - rating_scale
                                    - recommended
                              required:
                                - review
                          returned_count:
                            type: integer
                            minimum: 0
                          source_returned_count:
                            type: integer
                            minimum: 0
                          filtered_out:
                            type: integer
                            minimum: 0
                          total:
                            type: integer
                            minimum: 0
                          total_scope:
                            type: string
                            const: native_product_family_locale_candidates
                          page:
                            type: integer
                            minimum: 1
                          limit:
                            type: integer
                            minimum: 1
                            maximum: 50
                          offset:
                            type: integer
                            minimum: 0
                          locale:
                            type: string
                          next_cursor:
                            type:
                              - string
                              - 'null'
                          pagination_capped:
                            type: boolean
                          source:
                            type: string
                          coverage_note:
                            type: string
                        required:
                          - product
                          - items
                          - returned_count
                          - source_returned_count
                          - filtered_out
                          - total
                          - total_scope
                          - page
                          - limit
                          - offset
                          - locale
                          - next_cursor
                          - pagination_capped
                          - source
                          - coverage_note
        '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.