compsniper-com Sold history API

openapi: 3.2.0
info:
  title: CompSniper Marketplace and Shipping Sold history API
  version: 2.3.0
  description: Public eBay (including up to 3 years of sold history), Poshmark, Mercari, TCGplayer, Grailed, Depop and PSA graded card (prices by grade, population) data plus a separate quote-only US shipping-rates product. Shipping quotes separate applicable services from carrier-packaging and content-restricted options, use an independent subscription and quota, and do not consume sold-comps requests or purchased credits.
  contact:
    name: CompSniper
    url: https://compsniper.com
servers:
- url: https://api.compsniper.com
security:
- bearerAuth: []
tags:
- name: Sold history
paths:
  /v1/research/sold:
    get:
      tags:
      - Sold history
      summary: Search up to 3 years of eBay sold history
      description: Keyword search over eBay sold history going back up to 3 years (eBay's own limit), across eight eBay sites, on every plan including free. Each page of up to 50 listing-level rows uses one request; failed requests are free. Prices are USD. History has its own cap of 20 searches per minute per account (X-History-RateLimit-* headers, 429 history_rate_limited), on top of the plan limit.
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/CreditSource'
      - name: keyword
        in: query
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 200
          example: nintendo switch oled
          description: Search term
      - name: startDate
        in: query
        required: true
        schema:
          type: string
          format: date
          example: '2023-10-11'
          description: First day (YYYY-MM-DD), no earlier than 3 years before today
      - name: endDate
        in: query
        required: true
        schema:
          type: string
          format: date
          example: '2026-10-10'
          description: Last day (YYYY-MM-DD), no later than today (UTC)
      - name: ebaySite
        in: query
        required: false
        schema:
          type: string
          enum:
          - ebay.com
          - ebay.co.uk
          - ebay.com.au
          - ebay.ca
          - ebay.de
          - ebay.fr
          - ebay.it
          - ebay.es
          default: ebay.com
          description: eBay marketplace
      - name: sort
        in: query
        required: false
        schema:
          type: string
          enum:
          - quantityAscending
          - lastSoldDescending
          default: quantityAscending
          description: lastSoldDescending = newest sale first
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          enum:
          - 10
          - 20
          - 50
          default: 50
          description: Rows per page
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 1
          description: Page number
      - name: singleUnitOnly
        in: query
        required: false
        schema:
          type: boolean
          default: false
          description: Only listings that sold exactly one unit
      - name: allListingSites
        in: query
        required: false
        schema:
          type: boolean
          default: false
          description: Also include sales of listings made on another eBay site (for example a UK seller's ebay.co.uk listing bought on ebay.com). Use it for complete sales volume.
      - name: relevance
        in: query
        required: false
        schema:
          type: boolean
          default: false
          description: 'true removes rows that are not the searched product (accessories, lots, other models, other graders or grades) and far-off prices. The response then has relevanceApplied: true and rawResultCount.'
      responses:
        '200':
          description: Sold history page
          content:
            application/json:
              schema:
                type: object
                properties:
                  source:
                    type: string
                    example: ebay_product_research
                  ebaySite:
                    type: string
                  displayCurrency:
                    type: string
                    example: USD
                  startDate:
                    type: string
                  endDate:
                    type: string
                  page:
                    type: integer
                  limit:
                    type: integer
                  sourceResultCount:
                    type: integer
                  resultCount:
                    type: integer
                  hasNextPage:
                    type: boolean
                  nextPage:
                    type:
                    - integer
                    - 'null'
                  relevanceApplied:
                    type: boolean
                    example: false
                  totals:
                    type:
                    - object
                    - 'null'
                    description: Whole-search totals for the date range (same on every page, before relevance cleanup or singleUnitOnly). totalSold is an upper bound on the number of rows. Null when there are no sales.
                    properties:
                      totalSold:
                        type:
                        - integer
                        - 'null'
                      totalSellers:
                        type:
                        - integer
                        - 'null'
                      averageSoldPrice:
                        type:
                        - object
                        - 'null'
                        properties:
                          amount:
                            type: string
                          currency:
                            type: string
                          display:
                            type: string
                      minSoldPrice:
                        type:
                        - object
                        - 'null'
                        properties:
                          amount:
                            type: string
                          currency:
                            type: string
                          display:
                            type: string
                      maxSoldPrice:
                        type:
                        - object
                        - 'null'
                        properties:
                          amount:
                            type: string
                          currency:
                            type: string
                          display:
                            type: string
                      averageShipping:
                        type:
                        - object
                        - 'null'
                        properties:
                          amount:
                            type: string
                          currency:
                            type: string
                          display:
                            type: string
                      totalSales:
                        type:
                        - object
                        - 'null'
                        properties:
                          amount:
                            type: string
                          currency:
                            type: string
                          display:
                            type: string
                      freeShippingPercent:
                        type:
                        - string
                        - 'null'
                      sellThroughPercent:
                        type:
                        - string
                        - 'null'
                  warnings:
                    type: array
                    items:
                      type: string
                  requestId:
                    type: string
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        itemId:
                          type: string
                          example: '267809186741'
                        title:
                          type:
                          - string
                          - 'null'
                        extendedTitle:
                          type:
                          - string
                          - 'null'
                        itemUrl:
                          type:
                          - string
                          - 'null'
                        imageUrl:
                          type:
                          - string
                          - 'null'
                        recordType:
                          type: string
                          enum:
                          - single_unit_listing
                          - listing_aggregate
                        soldUnits:
                          type: integer
                          example: 1
                        averageSoldPrice:
                          type:
                          - object
                          - 'null'
                          properties:
                            amount:
                              type: string
                              example: '184.00'
                            currency:
                              type: string
                              example: USD
                            display:
                              type: string
                              example: $ 184.00
                        totalSales:
                          type:
                          - object
                          - 'null'
                          properties:
                            amount:
                              type: string
                              example: '184.00'
                            currency:
                              type: string
                              example: USD
                            display:
                              type: string
                              example: $ 184.00
                        averageShipping:
                          type:
                          - object
                          - 'null'
                          properties:
                            amount:
                              type: string
                              example: '184.00'
                            currency:
                              type: string
                              example: USD
                            display:
                              type: string
                              example: $ 184.00
                        soldPrice:
                          type:
                          - object
                          - 'null'
                          properties:
                            amount:
                              type: string
                              example: '184.00'
                            currency:
                              type: string
                              example: USD
                            display:
                              type: string
                              example: $ 184.00
                        soldDate:
                          type:
                          - string
                          - 'null'
                          example: '2026-10-09'
                        lastSoldDate:
                          type: string
                          example: '2026-10-09'
                        listingFormat:
                          type:
                          - string
                          - 'null'
                          example: Fixed price
                        bids:
                          type:
                          - integer
                          - 'null'
                        condition:
                          type:
                          - string
                          - 'null'
                        conditionId:
                          type:
                          - integer
                          - 'null'
        '400':
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  requestId:
                    type: string
        '401':
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  requestId:
                    type: string
        '429':
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  requestId:
                    type: string
        '502':
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  requestId:
                    type: string
        '503':
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  requestId:
                    type: string
      operationId: getV1ResearchSold
      x-operation-id-source: derived
components:
  parameters:
    CreditSource:
      name: X-Credit-Source
      in: header
      required: false
      schema:
        type: string
        enum:
        - credits
      description: Omit to use temporary carryover first, then monthly quota, then purchased credits. Set to credits to spend a purchased credit directly. Failed searches are not charged.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Send your API key as ''Authorization: Bearer cs_live_...''.'