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

# Amazon Best Sellers

> Read one Amazon BEST_SELLERS or NEW_RELEASES page for a department or department/node path. Pages 1 and 2 are supported. Oxylabs Best Sellers checks returned 50 rows on each US source page; the alternative source returned 30 rows from each 50-rank window. Exact coverage and rank availability depend on the source; do not infer a global rank from page-relative position. NEW_RELEASES uses the alternative source. A cursor appears only when the source confirms another page; cursors stay with their original provider. Other list types return 422 with no net charge. A nonempty live page costs 1 credit; a successful empty page refunds the hold. Missing stock, original prices and totals remain null. Other marketplaces require production verification.

Read one Amazon BEST\_SELLERS or NEW\_RELEASES page for a department or department/node path. Pages 1 and 2 are supported. Oxylabs Best Sellers checks returned 50 rows on each US source page; the alternative source returned 30 rows from each 50-rank window. Exact coverage and rank availability depend on the source; do not infer a global rank from page-relative position. NEW\_RELEASES uses the alternative source. A cursor appears only when the source confirms another page; cursors stay with their original provider. Other list types return 422 with no net charge. A nonempty live page costs 1 credit; a successful empty page refunds the hold. Missing stock, original prices and totals remain null. Other marketplaces require production verification.

Provider trials have finite allowances and fail closed when exhausted. The existing alternative provider remains available within its separate approved budget.


## OpenAPI

````yaml GET /amazon/best-sellers
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:
  /amazon/best-sellers:
    get:
      tags:
        - Amazon
      summary: Amazon Best Sellers
      description: >-
        Read one Amazon BEST_SELLERS or NEW_RELEASES page for a department or
        department/node path. Pages 1 and 2 are supported. Oxylabs Best Sellers
        checks returned 50 rows on each US source page; the alternative source
        returned 30 rows from each 50-rank window. Exact coverage and rank
        availability depend on the source; do not infer a global rank from
        page-relative position. NEW_RELEASES uses the alternative source. A
        cursor appears only when the source confirms another page; cursors stay
        with their original provider. Other list types return 422 with no net
        charge. A nonempty live page costs 1 credit; a successful empty page
        refunds the hold. Missing stock, original prices and totals remain null.
        Other marketplaces require production verification.
      operationId: get_amazon_best_sellers
      parameters:
        - name: category
          in: query
          required: true
          example: software
          schema:
            type: string
        - name: country
          in: query
          required: false
          example: US
          schema:
            type: string
            enum:
              - US
              - GB
              - CA
              - DE
              - FR
              - IT
              - ES
              - JP
              - IN
              - MX
              - BR
              - AU
              - NL
        - name: type
          in: query
          required: false
          example: BEST_SELLERS
          schema:
            type: string
            enum:
              - BEST_SELLERS
              - NEW_RELEASES
          description: >-
            Supported source list type. Other reference-product list types
            remain unavailable.
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 2
          description: >-
            Source page 1 or 2; use page=2 if the source provides no
            next_cursor.
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: >-
            Opaque next_cursor emitted only when the source confirms another
            page. Cannot be combined 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: >-
            Read one Amazon BEST_SELLERS or NEW_RELEASES page for a department
            or department/node path. Pages 1 and 2 are supported. Oxylabs Best
            Sellers checks returned 50 rows on each US source page; the
            alternative source returned 30 rows from each 50-rank window. Exact
            coverage and rank availability depend on the source; do not infer a
            global rank from page-relative position. NEW_RELEASES uses the
            alternative source. A cursor appears only when the source confirms
            another page; cursors stay with their original provider. Other list
            types return 422 with no net charge. A nonempty live page costs 1
            credit; a successful empty page refunds the hold. Missing stock,
            original prices and totals remain null. Other marketplaces require
            production verification.
          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: 'null'
                                    seller:
                                      type: 'null'
                                    brand:
                                      type: 'null'
                                    price:
                                      type: object
                                      properties:
                                        current:
                                          type:
                                            - number
                                            - 'null'
                                        original:
                                          type:
                                            - number
                                            - 'null'
                                        currency:
                                          type:
                                            - string
                                            - 'null'
                                    rating:
                                      type: object
                                      properties:
                                        average:
                                          type:
                                            - number
                                            - 'null'
                                        count:
                                          type:
                                            - integer
                                            - 'null'
                                    image_urls:
                                      type:
                                        - string
                                        - 'null'
                                    availability:
                                      type: 'null'
                                    reviews_count:
                                      type: 'null'
                                    features:
                                      type: 'null'
                                    specifications:
                                      type: 'null'
                                    variations:
                                      type: 'null'
                                    ext:
                                      type: object
                                      properties:
                                        rank:
                                          type:
                                            - integer
                                            - 'null'
                                        position:
                                          type: integer
                                        list_type:
                                          type:
                                            - string
                                            - 'null'
                                        promotion:
                                          type:
                                            - object
                                            - 'null'
                                          properties:
                                            label:
                                              type:
                                                - string
                                                - 'null'
                                            amount_off:
                                              type: 'null'
                                            percent_off:
                                              type:
                                                - number
                                                - 'null'
                                        price_text:
                                          type:
                                            - string
                                            - 'null'
                                        price_upper:
                                          type:
                                            - number
                                            - 'null'
                                          description: >-
                                            Source upper price of a range, not an
                                            original or list price.
                          returned_count:
                            type: integer
                          dropped:
                            type: integer
                            const: 0
                          total:
                            type:
                              - integer
                              - 'null'
                          next_cursor:
                            type:
                              - string
                              - 'null'
                          source_page:
                            type: integer
                          source:
                            type: string
                          coverage_note:
                            type: string
        '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.