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

# Sephora Search

> Find Sephora US products by keyword. Prices preserve ranges in USD. Up to 60 rows per page and three pages. Keyword matching and supported sorting follow the source. Exact totals are unavailable; continuation uses observed look-ahead rows, not an estimated total.

Find Sephora US products by keyword. Prices preserve ranges in USD. Up to 60 rows per page and three pages. Keyword matching and supported sorting follow the source. Exact totals are unavailable; continuation uses observed look-ahead rows, not an estimated total.

A successful uncached call costs **5 credits**. Failed requests and cache hits cost zero. Empty or failed upstream Actor output is treated as an unavailable response, not a billed successful search.

Pagination re-fetches the source prefix; updates can shift products or reviews between calls. Keep parameters identical with a returned cursor. `window_truncated=true` on page 3 means more rows were observed but this adapter’s bounded window ends. A null cursor does not prove the full catalog or review archive was retrieved.

Unknown values remain null. Source execution uses a pinned Actor build, restricted permissions and a hard per-run cost cap. No login cookies, private profile fields or reviewer demographic traits are returned.


## OpenAPI

````yaml GET /sephora/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:
  /sephora/search:
    get:
      tags:
        - Sephora
      summary: Sephora Search
      description: >-
        Find Sephora US products by keyword. Prices preserve ranges in USD. Up
        to 60 rows per page and three pages. Keyword matching and supported
        sorting follow the source. Exact totals are unavailable; continuation
        uses observed look-ahead rows, not an estimated total.
      operationId: get_sephora_search
      parameters:
        - name: query
          in: query
          required: true
          example: moisturizer
          schema:
            type: string
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 3
          description: Bounded source window; page 1–3. Do not combine with cursor.
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 60
        - name: sort_by
          in: query
          required: false
          schema:
            type: string
            enum:
              - best_selling
              - top_rated
              - price_low
              - price_high
              - new
          description: >-
            Supports best_selling, top_rated, price_low and price_high. new is
            unsupported and returns 422.
        - name: min_rating
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 5
          description: Integer minimum star rating from 1 to 4.
        - name: min_price
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
          description: >-
            Whole USD amounts from 0 to 100000; fractional values are
            unsupported.
        - name: max_price
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
          description: >-
            Whole USD amounts from 0 to 100000; fractional values are
            unsupported.
        - name: is_new
          in: query
          required: false
          schema:
            type: boolean
        - name: category_id
          in: query
          required: false
          schema:
            type: string
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: >-
            Opaque asp1_ cursor. Repeat identical query, identifiers, filters
            and page size. Do not combine with page.
        - 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: >-
            Find Sephora US products by keyword. Prices preserve ranges in USD.
            Up to 60 rows per page and three pages. Keyword matching and
            supported sorting follow the source. Exact totals are unavailable;
            continuation uses observed look-ahead rows, not an estimated total.
          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
                                    url:
                                      type: string
                                    title:
                                      type: string
                                    description:
                                      type:
                                        - string
                                        - 'null'
                                    seller:
                                      type: 'null'
                                    brand:
                                      type:
                                        - string
                                        - 'null'
                                    price:
                                      type: object
                                      properties:
                                        current:
                                          type:
                                            - number
                                            - 'null'
                                          minimum: 0
                                        original:
                                          type:
                                            - number
                                            - 'null'
                                          minimum: 0
                                        currency:
                                          type: string
                                          const: USD
                                    rating:
                                      type: object
                                      properties:
                                        average:
                                          type:
                                            - number
                                            - 'null'
                                          minimum: 0
                                        count:
                                          type:
                                            - number
                                            - 'null'
                                          minimum: 0
                                    image_urls:
                                      type: array
                                      items:
                                        type: string
                                    availability:
                                      type:
                                        - string
                                        - 'null'
                                    reviews_count:
                                      type:
                                        - number
                                        - 'null'
                                      minimum: 0
                                    features:
                                      type:
                                        - array
                                        - 'null'
                                      items:
                                        type: string
                                    specifications:
                                      type: object
                                      properties:
                                        ingredients:
                                          type:
                                            - string
                                            - 'null'
                                        how_to_use:
                                          type:
                                            - string
                                            - 'null'
                                    variations:
                                      type:
                                        - array
                                        - 'null'
                                      items:
                                        type: object
                                        properties:
                                          sku:
                                            type: string
                                          name:
                                            type:
                                              - string
                                              - 'null'
                                          size:
                                            type:
                                              - string
                                              - 'null'
                                          description:
                                            type:
                                              - string
                                              - 'null'
                                          price:
                                            type:
                                              - number
                                              - 'null'
                                            minimum: 0
                                          original_price:
                                            type:
                                              - number
                                              - 'null'
                                            minimum: 0
                                          in_stock:
                                            type:
                                              - boolean
                                              - 'null'
                                          image_url:
                                            type:
                                              - string
                                              - 'null'
                                          url:
                                            type:
                                              - string
                                              - 'null'
                                    ext:
                                      type: object
                                      properties:
                                        sku:
                                          type:
                                            - string
                                            - 'null'
                                        price_max:
                                          type:
                                            - number
                                            - 'null'
                                          minimum: 0
                                        price_display:
                                          type:
                                            - string
                                            - 'null'
                                        is_price_range:
                                          type: boolean
                                        brand_id:
                                          type:
                                            - string
                                            - 'null'
                                        category_id:
                                          type:
                                            - string
                                            - 'null'
                                        source_country:
                                          type: string
                                          const: US
                          returned_count:
                            type: integer
                            minimum: 0
                          total:
                            type: 'null'
                          next_cursor:
                            type:
                              - string
                              - 'null'
                          dropped:
                            type: integer
                            const: 0
                          coverage_note:
                            type: string
                          window_truncated:
                            type: boolean
        '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.