---
name: compsniper
description: Retrieve real completed-sale (sold) prices and active listings from eBay, Mercari, and Poshmark through the CompSniper REST API, with deterministic price summaries (median, mean, p25, p75). Use this whenever you need resale or market value, sold comps, price history, or listing data for a product, trading card, or collectible.
---

# CompSniper API

CompSniper is an independent REST API that returns real eBay, Mercari, and Poshmark listing evidence (up to 240 completed eBay sales per request) 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.
- `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.

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 directly (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`, `X-Cache` (`HIT` or `MISS`), 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