🧪 Compsniper

Retrieve real completed-sale (sold) prices and active listings from 18 marketplaces through the CompSniper REST API: 8 eBay sites (with 3 years, 1,095 days, of eBay sold history and the real accepted

Compsniper instructions

CompSniper API

CompSniper is an independent REST API that returns real listing evidence from 18 marketplaces (8 eBay sites plus TCGplayer, PSA, Grailed, Poshmark, Mercari, Depop and 4 card auction houses), up to 240 completed eBay sales per request, 3 years (1,095 days) of eBay sold history and the real accepted Best Offer price, plus a deterministic price summary. It replays authenticated sold-search access so you do not have to scrape HTML yourself.

  • Base URL: https://api.compsniper.com
  • Auth: every request needs Authorization: Bearer cs_... (create a key at https://compsniper.com/dashboard). A missing or invalid key returns 401 unauthorized.

Core endpoint: GET /v1/scrape

Keyword search of eBay sold listings (default) or active listings.

Query parameters:

  • keyword (string, required): the search term.
  • ebaySite (enum, default ebay.com): one of ebay.com, ebay.co.uk, ebay.de, ebay.fr, ebay.it, ebay.es, ebay.ca, ebay.com.au. Set it explicitly for a local marketplace; the API does not guess location.
  • sold (boolean, default true): true for completed sales, false for active listings.
  • count (integer, default 240, range 1 to 240): a ceiling. Fewer valid rows may remain after baseline validation, date filters, or relevance cleanup.
  • page (integer, default 1).
  • relevance (boolean, default true): query-aware cleanup that removes likely accessories, parts, broken units, empty boxes, and mismatched variants before the summary. Set false for broad valid matches without semantic cleanup.
  • exactMatch (boolean, default false): true removes eBay's explicit "Results matching fewer words" section before relevance cleanup.
  • sortOrder (enum, default endedRecently): endedRecently, timeNewlyListed, pricePlusPostageLowest, pricePlusPostageHighest, distanceNearest.
  • minPrice, maxPrice (number).
  • itemCondition (any, new, used), conditionId (integer).
  • buyingFormat (all, auction, buyItNow, acceptsOffers).
  • sellerType (private, business).
  • itemLocation (default, domestic, worldwide).
  • categoryId (string, default 0), aspectFilter (string).
  • soldAfter, soldBefore (date), includeCompleteListing (boolean).

Response (JSON): keyword, page, totalItems, totalResults, hasNextPage, autoSelectedCategory, items (array), and summary (count, currency, median, mean, min, max, p25, p75, avgShipping). With relevance on, rawMedian and rawSampleCount preserve the evidence before cleanup. Sold items include soldPrice, soldCurrency, endedAt, totalPrice, condition, shippingPrice, seller fields, and url. With sold=false, sold-only fields are replaced by currentPrice, currentPriceMax, currentCurrency, timeLeft, and watcherCount. Full field list: references/api-reference.md.

Minimal example:

curl -H "Authorization: Bearer cs_YOUR_KEY" \
  "https://api.compsniper.com/v1/scrape?keyword=nintendo+switch+oled&sold=true&ebaySite=ebay.com"

Tip for the fullest set of comps: search the base product name (brand plus product). Very narrow phrasings, such as multi-pack quantities or exact variants, match far fewer sold listings.

Other endpoints

  • GET /v1/scrape/category: browse sold listings by eBay categoryId.
  • GET /v1/mercari: public Mercari US sold or active listings, up to 100 per page. Dedicated response schema.
  • GET /v1/poshmark/sold: public Poshmark US sold listings, up to 48 per page. Dedicated response schema.
  • GET /v1/summary: cleaned price-intelligence summary for a keyword.
  • GET /v1/account/usage: plan, quota, and remaining usage.
  • POST /v1/bulk-search: stream up to 20 independent keyword searches in one run. GET /v1/bulk-search/:runId/download.csv exports one keyword or the combined run.
  • POST /v1/cards/batch: start an asynchronous batch that prices up to 100 trading or sports cards. GET /v1/cards/batch/:jobId polls, DELETE /v1/cards/batch/:jobId cancels. Results expire after 30 days.
  • POST /v1/scrape/max: start a deeper asynchronous Max Mode run. GET /v1/scrape/max/results/:jobId polls, DELETE /v1/scrape/max/:jobId cancels, GET /v1/scrape/max/:jobId/download.csv exports.
  • GET /v1/research/sold: up to 3 years of eBay sold history on every plan including free. Requires keyword, startDate, endDate (YYYY-MM-DD, no earlier than 3 years ago). Max 50 rows per page; follow nextPage while hasNextPage is true. Rows are listing-level, prices in USD, no AI cleanup. One page = one request; separate cap of 20 history searches per minute.
  • GET /v1/tcgplayer/sold and GET /v1/tcgplayer/listings: TCGplayer completed sales (full history, optional market price history) and active listings, by keyword or exact productId.
  • POST /v1/shipping/rates and GET /v1/shipping/usage: US shipping-rate estimates. These use a separate subscription and quota and are never funded by sold-comps requests or credits.

Keyword tips for history and TCGplayer (most empty answers come from the request):

  • History matches only listings whose title contains every word. Send brand plus model or set number (CyberPower PDU81001 returns 12, the longer CyberPower PDU81001G switched metered by outlet PDU 8 outlet 1U returns 0). Never pass a whole listing title; if a long keyword returns 0, retry it shorter before treating the item as unsold.
  • History: a window of a few days often holds few or no sales. Widen startDate (up to 3 years) for rare items.
  • TCGplayer matches TCGplayer product names, not eBay titles. Use card or product name, set and number (Pokemon Japanese 151 booster box), one product per call, then reuse the returned productId.

Poshmark and Mercari use dedicated field schemas that differ from eBay. See references/api-reference.md.

Error handling

Errors return JSON { error, code, hint?, retry_after?, ... } with these codes:

  • 401 unauthorized: missing or invalid API key.
  • 400 invalid_params: a parameter is invalid.
  • 429 rate_limited: per-minute limit reached. Respect the Retry-After header, back off with jitter, and retry a bounded number of times.
  • 429 quota_exceeded: monthly quota and purchased credits are exhausted. Do not retry. Fields include quota, used, remaining, reset_at, rollover_balance, credit_balance, upgrade_url, and purchase_credits_url.
  • 502 upstream_blocked: eBay challenged the request. Retry after a short delay; a re-query usually succeeds. Failed searches are not charged.
  • 503 server_busy: temporary capacity limit. Respect Retry-After, reduce parallel requests, and use a bounded retry count.
  • 502 upstream_unavailable and 500 server_error: transient. Use a bounded retry.

Billing and quota

A successful search consumes one request, drawn in order from eligible rollover, then the monthly plan allowance, then non-expiring purchased credits. Failed searches release the reservation and are not charged. Send the optional header X-Credit-Source: credits to use purchased credits first; when they run out the request falls back to the monthly allowance instead of failing (the only accepted value is credits; omit the header for automatic selection).

Responses expose X-Plan, X-Usage-Limit, X-Usage-Used, X-Usage-Remaining, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-Credit-Source, X-Rollover-Balance, X-Credit-Balance, and X-Request-ID. Paid subscriptions and accounts using purchased credits receive priority in the live-search queue during busy periods.

References

  • references/api-reference.md: full endpoint reference, complete response field list, Poshmark and Mercari schemas.
  • references/examples.md: worked examples in curl, JavaScript, and Python.
  • Hosted MCP connector (live calls without managing keys): https://compsniper.com/docs/mcp

Related Skills

Get the best new skills
in your inbox

Weekly roundup of top Claude Code skills, MCP servers, and AI coding tips.