Complete API reference

Searchable endpoint index

Keyword search parameters

keyword, page, count, ebaySite, categoryId, sortOrder, minPrice, maxPrice, itemLocation, itemCondition, conditionId, buyingFormat, sellerType, includeCompleteListing, sold, soldAfter, soldBefore, aspectFilter, exactMatch, relevance, and bestOfferPrice (true adds the real accepted price on Best Offer sales, see Accepted Best Offer prices).

Marketplace selection

Set ebaySite explicitly when you need sold listings from a local marketplace. If it is omitted, the API searches ebay.com. CompSniper does not guess location for API traffic because server locations, VPNs, and hosted applications may not match the customer being served.

eBay's own marketplace IDs are accepted as aliases, so EBAY_US, EBAY_GB (or EBAY_UK), EBAY_DE, EBAY_FR, EBAY_IT, EBAY_ES, EBAY_CA and EBAY_AU work, as do country codes such as US or UK.

Only the marketplace changes. Authentication, quota usage, response fields, and parsing remain the same.

Poshmark and Mercari use dedicated response schemas because their native fields differ from eBay. See Poshmark and Mercari APIs for filters, response fields, pagination, examples, and limitations.

Request billing

After a full-price plan upgrade, any unused monthly requests become temporary carryover and are used first. Successful searches then use the new monthly allowance and automatically fall back to non-expiring purchased credits. Send the optional X-Credit-Source: credits header to use credits first; when they run out, the request falls back to your monthly allowance. Responses expose X-Credit-Source, X-Rollover-Balance, and X-Credit-Balance; quota errors include rollover_balance, credit_balance, and purchase_credits_url. Failed searches release the reservation and are not charged.

Shipping-rate quotes use a separate subscription and quota. They never use sold-comps monthly requests, carryover, or purchased credits. See Shipping Rates API for the POST body, response fields, idempotency behavior, and quote-specific errors.

Performance timing

Successful API responses can include a standard Server-Timing header. When present, it separates queue wait, account lease, pacing, eBay fetch, parsing, baseline cleanup, relevance processing, and total engine time. The response body and result fields are unchanged.

exactMatch parser option

exactMatch is an optional boolean with a default of false. When eBay does not find enough listings that contain every word of your keyword, it adds a Results matching fewer words section. exactMatch=true removes that section and everything after it, before any other cleanup.

Long, precise searches often have no exact matches on eBay, because sellers rarely write the full card number and set name the way a database does. With exactMatch=true those searches can return an empty items array even when the item sold many times. For example, Blind Obedience 303/466 Ravnica Remastered MTG returned 0 sales with exactMatch=true and 13 sales of that exact card and set without it. If many of your searches come back empty, remove exactMatch first. See also narrow searches and graded cards.

When the section is removed, hasNextPage becomes false because eBay has no more exact matches. The default and explicit exactMatch=false keep the existing parser behavior: eBay's full results, with the standard cleanup deciding what matches.

Facets, seller type, and condition IDs

aspectFilter accepts JSON keyed by the human-readable facets shown in the selected eBay marketplace, for example {"Model":"Apple iPhone 15 Pro","Storage Capacity":["256 GB","512 GB"]}. A value can be a string, pipe-delimited string, or string array. CompSniper validates and canonicalizes the object before encoding the exact eBay facet parameters. Unknown facets are passed through and may be ignored by eBay.

sellerType=private and sellerType=business filter labeled rows on ebay.de, ebay.fr, ebay.it, and ebay.es. The four other marketplaces do not expose this classification, so the filter is ignored there. On EU sites, rows without a recognizable seller label are excluded when the filter is active.

Returned rows preserve eBay's localized condition text and add a best-effort numeric conditionId for known labels such as New, Open box, Used, localized refurbished tiers, and For parts. Unknown or category-specific labels remain null; callers should use condition as the authoritative value.

Baseline listing hygiene

All keyword and category responses remove malformed non-listing rows and duplicate item IDs before optional relevance cleanup. A sold item must have a real item ID, a matching /itm/ URL, a positive sold price, and a sold date. An active item must have the same ID and URL checks plus a positive current price.

relevance=false disables query-aware pricing checks and semantic cleanup. Baseline listing hygiene still applies. The count parameter is therefore a ceiling, and valid responses can contain fewer rows after baseline validation, date filters, or relevance cleanup.

With relevance enabled, deterministic title checks first reject explicit pricing mismatches such as unrequested lots, multipacks, bundles, selection listings, modified or non-original items, prototypes, damaged or parts-only units, standalone accessories, and conflicting years, capacities, sizes, quantities, grading details, or catalog numbers. Explicit query intent takes priority, so a keyword that requests a lot, bundle, damaged unit, prototype, modification, or other special case keeps that type of listing. A single bounded semantic classification stage then handles less explicit product and model mismatches.

These checks do not change API keys, authentication headers, parameter names, quotas, response fields, or the top-level response envelope used by existing integrations.

Narrow searches and graded cards

count sets how many eBay sold results are checked, and cleanup then removes the ones that do not match your search. For broad searches you get close to count results. For narrow searches, such as a specific card and grade (1979 Topps Ozzie Smith PSA 8) or an exact model, eBay mixes in many other grades and models, so only some of the checked results are matches. A request for 20 results can return 2 matching sales.

• Use count=240, the maximum, so one request checks as many sales as possible.
• When hasNextPage is true, request page=2 to check the next 240 results.
• To receive eBay's results exactly as listed, with no filtering, add relevance=false.
• Leave exactMatch off for long, specific keywords like these. It can remove every result. See exactMatch.

curl -H "Authorization: Bearer cs_live_REPLACEWITHYOURKEY" \
  "https://api.compsniper.com/v1/scrape?keyword=1979+topps+ozzie+smith+psa+8&count=240&page=1"

Sold item fields

itemId, url, thumbnailUrl, fullResThumbnailUrl, epid, title, condition, conditionId, sellerType, buyingFormat, bestOfferAccepted, bidCount, categoryId, listingType, shippingPrice, shippingCurrency, shippingType, totalPrice, sellerUsername, sellerPositivePercent, sellerFeedbackScore, productRating, productReviewCount, itemLocation, scrapedAt, endedAt, soldPrice, and soldCurrency.

With bestOfferPrice=true, rows where bestOfferAccepted is true also carry acceptedOfferPrice (the price the buyer actually paid) and acceptedOfferPriceStatus (found, pending or not_available). soldPrice is never changed. See Accepted Best Offer prices.

epid is usually null: eBay rarely shows a catalog product ID on sold results.

productRating and productReviewCount describe the shared eBay catalog product, not the individual seller. Both are null when eBay does not show catalog review data on that result card.

Active listing fields

With sold=false, sold-only fields are replaced by currentPrice, currentPriceMax, currentCurrency, watcherCount, unitsSold, acceptsOffers, and timeLeft.

Active searches omit eBay's completed and sold flags. currentPrice is required after baseline listing validation. The other demand fields are best-effort values from the visible search card and remain null when eBay does not display them. summary is null for active searches because sold-price statistics do not apply to asking prices.

The detailed reference below preserves all examples, tables, response envelopes, MCP instructions, and batch documentation from the original single-page reference.

curl --fail-with-body -H "Authorization: Bearer cs_live_REPLACEWITHYOURKEY" "https://api.compsniper.com/v1/scrape?keyword=iphone+15+pro&count=10"

curl --fail-with-body "https://api.compsniper.com/v1/status"

curl --fail-with-body -H "Authorization: Bearer cs_live_REPLACEWITHYOURKEY" "https://api.compsniper.com/v1/summary?keyword=shure+sm7b&count=240"

curl --fail-with-body -H "Authorization: Bearer cs_live_REPLACEWITHYOURKEY" "https://api.compsniper.com/v1/scrape?keyword=shure+sm7b+-stand+-cable&itemCondition=used&minPrice=150&maxPrice=350&count=50"

curl --fail-with-body -H "Authorization: Bearer cs_live_REPLACEWITHYOURKEY" "https://api.compsniper.com/v1/scrape?keyword=iphone+15+pro&ebaySite=ebay.co.uk&itemCondition=used&count=50"

curl --fail-with-body -H "Authorization: Bearer cs_live_REPLACEWITHYOURKEY" "https://api.compsniper.com/v1/scrape?keyword=iphone+15+pro&relevance=false&count=240"

curl --fail-with-body -H "Authorization: Bearer cs_live_REPLACEWITHYOURKEY" "https://api.compsniper.com/v1/scrape?keyword=garmin+8612xsv&exactMatch=true&count=240"

curl --get --fail-with-body -H "Authorization: Bearer cs_live_REPLACEWITHYOURKEY" --data-urlencode "keyword=iphone 15 pro" --data-urlencode 'aspectFilter={"Model":"Apple iPhone 15 Pro","Storage Capacity":"256 GB"}' "https://api.compsniper.com/v1/scrape"

curl --fail-with-body -H "Authorization: Bearer cs_live_REPLACEWITHYOURKEY" "https://api.compsniper.com/v1/account/usage"

curl --fail-with-body -H "Authorization: Bearer cs_live_REPLACEWITHYOURKEY" "https://api.compsniper.com/v1/scrape?keyword=stanley+tumbler"

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1765843200
X-Usage-Limit: 10000
X-Usage-Remaining: 8412

import random
import time
import requests

API_KEY = "cs_live_REPLACEWITHYOURKEY"

def search_sold(keyword: str):
    for attempt in range(5):
        response = requests.get(
            "https://api.compsniper.com/v1/scrape",
            headers={"Authorization": f"Bearer {API_KEY}"},
            params={"keyword": keyword, "count": 240},
            timeout=60,
        )
        body = response.json()

        if response.ok:
            print("Requests remaining:", response.headers.get("X-Usage-Remaining"))
            return body

        if response.status_code == 429 and body.get("code") == "quota_exceeded":
            raise RuntimeError(
                f"Monthly quota exhausted. Reset: {body.get('reset_at')}. "
                f"Upgrade: {body.get('upgrade_url')}"
            )  # Do not retry this request.

        if response.status_code == 429 and body.get("code") == "rate_limited":
            delay = float(
                response.headers.get("Retry-After")
                or body.get("retry_after")
                or min(2 ** attempt, 30)
            )
            time.sleep(delay + random.uniform(0, 0.5))
            continue

        if response.status_code in (500, 502, 503):
            delay = float(
                response.headers.get("Retry-After")
                or body.get("retry_after")
                or min(2 ** attempt, 30)
            )
            time.sleep(delay + random.uniform(0, 0.5))
            continue

        response.raise_for_status()

    raise RuntimeError("CompSniper request failed after 5 bounded retries")

data = search_sold("9780399145636")
print(data["totalItems"], "sold listings")

{
  "error": "Per-minute rate limit exceeded.",
  "code": "rate_limited",
  "retry_after": 12
}

{
  "error": "Free plan quota exhausted. Upgrade your CompSniper plan to continue now, or wait for your monthly reset.",
  "code": "quota_exceeded",
  "plan": "basic",
  "quota": 100,
  "used": 100,
  "remaining": 0,
  "reset_at": "2026-09-18T05: 30: 36.000Z",
  "upgrade_url": "https://compsniper.com/dashboard/subscription"
}

{
  "keyword": "iphone 15 pro",
  "page": 2,
  "totalItems": 240,
  "totalResults": "14,000+",
  "hasNextPage": true,
  "autoSelectedCategory": { "id": "9355", "name": "Cell Phones & Smartphones" },
  "items": [ /* ... */ ]
}

{
  "keyword": "iphone 17 pro max",
  "page": 1,
  "totalItems": 240,
  "totalResults": "14,000+",
  "hasNextPage": true,
  "autoSelectedCategory": {
    "id": "9355",
    "name": "Cell Phones & Smartphones"
  },
  "items": [
    {
      "itemId": "256123456789",
      "url": "https://www.ebay.com/itm/256123456789?nordt=true",
      "thumbnailUrl": "https://i.ebayimg.com/images/g/3nkAAeSw/s-l500.webp",
      "epid": "20049285656",
      "title": "Apple iPhone 17 Pro Max 256GB Black Titanium - Unlocked",
      "condition": "Pre-Owned",
      "conditionId": 3000,
      "buyingFormat": "buyItNow",
      "bestOfferAccepted": false,
      "bidCount": null,
      "categoryId": "9355",
      "listingType": "sold",
      "endedAt": "2026-03-10",
      "soldPrice": "1245.00",
      "soldCurrency": "USD",
      "shippingPrice": "0.00",
      "shippingCurrency": "USD",
      "shippingType": "free",
      "totalPrice": "899.99",
      "sellerUsername": "top-deals-store",
      "sellerPositivePercent": 99.8,
      "sellerFeedbackScore": 14200,
      "itemLocation": "United States",
      "scrapedAt": "2026-03-14T21: 00: 00.000Z"
    }
    // ... 239 more items
  ]
}

curl -H "Authorization: Bearer cs_live_REPLACEWITHYOURKEY" \
  "https://api.compsniper.com/v1/scrape/category?categoryId=9355&count=100"

curl -X POST "https://api.compsniper.com/v1/cards/batch" \
  -H "Authorization: Bearer cs_live_REPLACEWITHYOURKEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: inventory-run-2026-08-29" \
  -d '{
    "cards": [
      {
        "reference": "inventory-001",
        "year": 2023,
        "set": "Topps Chrome",
        "player": "Victor Wembanyama",
        "cardNumber": "1",
        "parallel": "Refractor",
        "grader": "PSA",
        "grade": 10
      },
      {
        "reference": "inventory-002",
        "keyword": "1999 pokemon base set charizard 4/102 psa 9"
      }
    ],
    "options": {
      "count": 60,
      "outputMode": "summary",
      "relevance": true
    }
  }'

curl -H "Authorization: Bearer cs_live_REPLACEWITHYOURKEY" \
  "https://api.compsniper.com/v1/cards/batch/JOB_ID"

{
  "mcpServers": {
    "compsniper": {
      "command": "npx",
      "args": ["-y", "compsniper"],
      "env": { "COMPSNIPER_API_KEY": "cs_live_REPLACEWITHYOURKEY" }
    }
  }
}