compsniper-com Summary API

openapi: 3.2.0
info:
  title: CompSniper Marketplace and Shipping Summary 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: Summary
paths:
  /v1/summary:
    get:
      summary: Get sold-price intelligence without listing rows
      description: Runs the same sold search and billing flow as /v1/scrape, but returns only the cleaned price summary, raw comparison evidence, result counts, and cache status.
      operationId: getPriceSummary
      parameters:
      - $ref: '#/components/parameters/CreditSource'
      - name: keyword
        in: query
        required: true
        schema:
          type: string
      - name: count
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 240
          default: 240
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 1
      - name: ebaySite
        in: query
        required: false
        schema:
          type: string
          enum:
          - ebay.com
          - ebay.co.uk
          - ebay.de
          - ebay.fr
          - ebay.it
          - ebay.es
          - ebay.ca
          - ebay.com.au
          default: ebay.com
      - name: categoryId
        in: query
        required: false
        schema:
          type: string
      - name: sortOrder
        in: query
        required: false
        schema:
          type: string
          enum:
          - endedRecently
          - timeNewlyListed
          - pricePlusPostageLowest
          - pricePlusPostageHighest
          - distanceNearest
      - name: minPrice
        in: query
        required: false
        schema:
          type: number
      - name: maxPrice
        in: query
        required: false
        schema:
          type: number
      - name: itemCondition
        in: query
        required: false
        schema:
          type: string
          enum:
          - any
          - new
          - used
      - name: conditionId
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
      - name: buyingFormat
        in: query
        required: false
        schema:
          type: string
          enum:
          - all
          - auction
          - buyItNow
          - acceptsOffers
      - name: sellerType
        in: query
        required: false
        schema:
          type: string
          enum:
          - private
          - business
      - name: soldAfter
        in: query
        required: false
        schema:
          type: string
          format: date
      - name: soldBefore
        in: query
        required: false
        schema:
          type: string
          format: date
      - name: aspectFilter
        in: query
        required: false
        schema:
          type: string
        description: JSON object of eBay facet names and values.
      - name: exactMatch
        in: query
        required: false
        schema:
          type: boolean
          default: false
      - name: relevance
        in: query
        required: false
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: Price summary and raw-versus-cleaned evidence.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SummaryResponse'
        '400':
          description: Invalid parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Credential lacks comps:read scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Rate limit or all available billing sources exhausted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '502':
          description: eBay temporarily blocked the upstream request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '503':
          description: Scraping service temporarily at capacity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      tags:
      - Summary
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.
  schemas:
    PriceSummary:
      type:
      - object
      - 'null'
      description: Deterministic price intelligence over the returned sold items.
      properties:
        count:
          type: integer
          description: Items with a usable sold price.
        currency:
          type:
          - string
          - 'null'
        median:
          type: number
        mean:
          type: number
        min:
          type: number
        max:
          type: number
        p25:
          type: number
          description: Lower bound of the realistic range.
        p75:
          type: number
          description: Upper bound of the realistic range.
        avgShipping:
          type:
          - number
          - 'null'
    SummaryResponse:
      type: object
      required:
      - keyword
      - totalItems
      - cached
      properties:
        keyword:
          type: string
        totalResults:
          type:
          - string
          - 'null'
        totalItems:
          type: integer
        rawMedian:
          type:
          - number
          - 'null'
        rawSampleCount:
          type:
          - integer
          - 'null'
        summary:
          $ref: '#/components/schemas/PriceSummary'
        cached:
          type: boolean
    ApiError:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
        retry_after:
          type: integer
          description: Seconds before a temporary rate_limited request may be retried.
        reset_at:
          type: string
          format: date-time
          description: Billing-cycle reset for quota_exceeded.
        plan:
          type: string
        quota:
          type: integer
        used:
          type: integer
        remaining:
          type: integer
        rollover_balance:
          type: integer
          description: Temporary carried-over requests remaining.
        upgrade_url:
          type: string
          format: uri
          description: Plan-management URL for quota_exceeded.
        credit_balance:
          type: integer
          description: Non-expiring purchased credits remaining.
        purchase_credits_url:
          type: string
          format: uri
          description: Credit purchase URL for quota_exceeded.
        subscription_url:
          type: string
          format: uri
          description: Shipping Rates plan URL for shipping_subscription_required or shipping_quota_exceeded.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Send your API key as ''Authorization: Bearer cs_live_...''.'