Max Mode

Max Mode runs multiple result pages as an asynchronous server-side job. Use it for deeper research when a single page of up to 240 sold listings is not enough.

Start

curl -X POST "https://api.compsniper.com/v1/scrape/max" \
  -H "Authorization: Bearer cs_live_REPLACEWITHYOURKEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: max-mode-2026-08-31" \
  -d '{"keyword":"shure sm7b","maxPages":5,"count":240,"exactMatch":true}'

The response contains a jobId.

exactMatch is optional and defaults to false. When true, each page excludes eBay's explicit Results matching fewer words section. A page containing that boundary reports no next exact page, so the job stops cleanly.

Poll

GET /v1/scrape/max/results/:jobId

Poll about every five seconds. Terminal states are done, maxPages_reached, cancelled, and failed. Each successfully fetched result page uses carryover first, then one monthly request, then one purchased credit after monthly quota is exhausted. Add X-Credit-Source: credits when starting the job to fund every page from credits first (it falls back to your monthly allowance if credits run out). Failed pages are not charged.

The response keeps the original pagesDone and itemsFound fields and also includes structured progress: currentPage, pagesAttempted, pagesSucceeded, pagesFailed, failedPages, itemsCollected, and consecutiveFailures. Each page receives one bounded retry after 2.5 seconds. A failed attempt is never charged, and a page is recorded as failed only after both attempts fail.

terminationReason explains why work stopped:

• natural_end: eBay reported no next page.
• maxPages_reached: the requested page ceiling was reached.
• quota_exhausted: monthly quota and purchased credits ran out.
• upstream_unhealthy: five consecutive pages failed after their bounded retries.
• cancelled: the account requested cancellation.
• terminal_error: page 1 or another required job operation failed.

Terminal responses include the same values in summary, plus partial. A job can therefore preserve successful pages while reporting exactly which later pages failed.

Cancel

DELETE /v1/scrape/max/:jobId

Only one Max Mode or Card Batch job can run per account. A second submission returns 409 conflict with the active job details.

Export

Completed jobs provide a signed CSV URL:

GET /v1/scrape/max/:jobId/download.csv?token=SIGNED_TOKEN

Always provide maxPages, use an idempotency key for submission retries, and stop polling terminal jobs.