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

> Native public US product search with six sorts, source-confirmed dimension filters and bounded pagination. Source ranking can return unrelated popular items for unmatched queries. Prices preserve ranges and conditional coupon offers separately. Empty terminal pages are corroborated against the first-page total and cost zero.

Searches the public US Kohl’s catalog. Supply `query` and optionally `sort_by`: `featured`, `newest`, `price_low`, `price_high`, `rating`, or `percent_off`. These preserve the source’s ranking; an unmatched keyword can return unrelated popular products. No exact-keyword relevance or stock guarantee is implied.

Products retain native IDs, titles, canonical URLs, source images, displayed colors, rating/count when known and a sponsorship flag. Unrated values remain null. `price.current` is the minimum native sale or regular price, while `current_range` and `original_range` preserve variation ranges. Coupon-conditioned `conditional_offer` values remain separate and are not treated as the base price. Prices exclude tax/shipping; suppressed or in-store-only current prices remain null. No tracking IDs, wallet/account data or advertising callbacks are returned or followed.

Use `dimensions[].values[].filter` for native dimension IDs, joined with commas in `filters`. IDs can contain encoded spaces, plus signs or punctuation; keep the returned value intact. Filter application and active sort are checked against source metadata. A silently dropped native filter becomes an explicit error rather than an unfiltered success. Dimension counts are native facet counts, not independent inventory guarantees.

`limit` is 1–48, default 12. `page` is one-based; `data.next_cursor` is preferred and may be supplied without the original query. The source ignores page-size overrides and returns 120 candidates; the adapter returns only the requested logical page. `source_page_size` and `source_offset` identify that larger source window. Pagination stops at offset 10,000 and reports `pagination_capped` when that ceiling prevents continuation.

Cursors bind query, limit, sort and filters for one hour and recheck the preceding product. Source counts/ranking can change, requiring a restart. Later pages first corroborate the query’s current total because the native service can error for out-of-range offsets. A confirmed terminal result is empty and free; upstream errors are never converted into successful empty results.

Fresh nonempty pages cost **5 credits**. Empty pages, cache hits, failures and successful idempotent replays cost zero. Use `X-Max-Credits: 5`. Requests use one anonymous source read, or two for later native windows, with a shared 20-source-request/minute ceiling, 35-second transport timeout and 2 MiB limit per source response. Firecrawl retrieves the exact anonymous catalog JSON; direct access is a fallback with an 8-second total timeout. Both paths use identical validation. The existing Firecrawl credential is used; no new key is created. This public source has no contractual availability guarantee.


## OpenAPI

````yaml GET /kohls/search
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/search:
    get:
      tags:
        - Kohls
      summary: Kohls Search
      description: >-
        Native public US product search with six sorts, source-confirmed
        dimension filters and bounded pagination. Source ranking can return
        unrelated popular items for unmatched queries. Prices preserve ranges
        and conditional coupon offers separately. Empty terminal pages are
        corroborated against the first-page total and cost zero.
      operationId: get_kohls_search
      parameters:
        - name: query
          in: query
          required: false
          example: jeans
          schema:
            type: string
            minLength: 1
            maxLength: 200
          description: >-
            Search keyword, or omit when continuing with a cursor. Native
            relevance is not a strict keyword match.
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
          description: >-
            One-based logical page, with (page-1)*limit at most 10,000. Must
            agree with a supplied cursor.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 48
            default: 12
          description: >-
            Returned products per logical page: 1–48, default 12. Larger values
            fail. The native 120-row candidate window is not exposed as a
            product page.
        - name: sort_by
          in: query
          required: false
          schema:
            type: string
            enum:
              - featured
              - newest
              - price_low
              - price_high
              - rating
              - percent_off
        - name: filters
          in: query
          required: false
          schema:
            type: string
          description: >-
            Comma-separated filter values from dimensions[].values[].filter.
            Encoded spaces and plus signs are accepted. The adapter rejects
            filters the native source does not apply.
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: >-
            One-hour query/limit/sort/filter-bound continuation from
            data.next_cursor; may be supplied alone. Verifies the preceding
            product and requires restarting if source order changes.
        - 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: >-
            Native public US product search with six sorts, source-confirmed
            dimension filters and bounded pagination. Source ranking can return
            unrelated popular items for unmatched queries. Prices preserve
            ranges and conditional coupon offers separately. Empty terminal
            pages are corroborated against the first-page total and cost zero.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SocialQueryResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          items:
                            type: array
                            items:
                              type: object
                              properties:
                                product:
                                  type: object
                                  properties:
                                    id:
                                      type: string
                                    title:
                                      type: string
                                    url:
                                      type: string
                                    price:
                                      type: object
                                      properties:
                                        current:
                                          type:
                                            - number
                                            - 'null'
                                          minimum: 0
                                        original:
                                          type:
                                            - number
                                            - 'null'
                                          minimum: 0
                                        currency:
                                          type: string
                                          const: USD
                                        current_range:
                                          type:
                                            - object
                                            - 'null'
                                          properties:
                                            min:
                                              type: number
                                              minimum: 0
                                            max:
                                              type: number
                                              minimum: 0
                                          required:
                                            - min
                                            - max
                                        original_range:
                                          type:
                                            - object
                                            - 'null'
                                          properties:
                                            min:
                                              type: number
                                              minimum: 0
                                            max:
                                              type: number
                                              minimum: 0
                                          required:
                                            - min
                                            - max
                                        display_current:
                                          type:
                                            - string
                                            - 'null'
                                        display_original:
                                          type:
                                            - string
                                            - 'null'
                                        label:
                                          type:
                                            - string
                                            - 'null'
                                        suppressed:
                                          type: boolean
                                        in_store_only:
                                          type: boolean
                                        conditional_offer:
                                          type:
                                            - object
                                            - 'null'
                                          properties:
                                            display_price:
                                              type:
                                                - string
                                                - 'null'
                                            codes:
                                              type: array
                                              items:
                                                type: string
                                            wallet_offer:
                                              type: boolean
                                          required:
                                            - display_price
                                            - codes
                                            - wallet_offer
                                      required:
                                        - current
                                        - original
                                        - currency
                                        - current_range
                                        - original_range
                                        - display_current
                                        - display_original
                                        - label
                                        - suppressed
                                        - in_store_only
                                        - conditional_offer
                                    rating:
                                      type: object
                                      properties:
                                        average:
                                          type:
                                            - number
                                            - 'null'
                                          minimum: 0
                                        count:
                                          type:
                                            - integer
                                            - 'null'
                                          minimum: 0
                                      required:
                                        - average
                                        - count
                                    image_urls:
                                      type: array
                                      items:
                                        type: string
                                    colors:
                                      type: array
                                      items:
                                        type: string
                                    sponsored:
                                      type: boolean
                                    availability:
                                      type: 'null'
                                  required:
                                    - id
                                    - title
                                    - url
                                    - price
                                    - rating
                                    - image_urls
                                    - colors
                                    - sponsored
                                    - availability
                              required:
                                - product
                          returned_count:
                            type: integer
                            minimum: 0
                          total:
                            type: integer
                            minimum: 0
                          query:
                            type: string
                          corrected_query:
                            type:
                              - string
                              - 'null'
                          page:
                            type: integer
                            minimum: 1
                          limit:
                            type: integer
                            minimum: 1
                            maximum: 48
                          offset:
                            type: integer
                            minimum: 0
                          sort_by:
                            type: string
                          applied_filters:
                            type: array
                            items:
                              type: string
                          dimensions:
                            type: array
                            items:
                              type: object
                              properties:
                                id:
                                  type: string
                                label:
                                  type: string
                                values:
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      name:
                                        type: string
                                      filter:
                                        type: string
                                      count:
                                        type: integer
                                        minimum: 0
                                    required:
                                      - name
                                      - filter
                                      - count
                              required:
                                - id
                                - label
                                - values
                          next_cursor:
                            type:
                              - string
                              - 'null'
                          pagination_capped:
                            type: boolean
                          source_page_size:
                            type: integer
                            const: 120
                          source_offset:
                            type: integer
                            minimum: 0
                          source:
                            type: string
                          coverage_note:
                            type: string
                        required:
                          - items
                          - returned_count
                          - total
                          - query
                          - corrected_query
                          - page
                          - limit
                          - offset
                          - sort_by
                          - applied_filters
                          - dimensions
                          - next_cursor
                          - pagination_capped
                          - source_page_size
                          - source_offset
                          - 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.