Documentation

Getting started

Create a key in the console — the free tier includes 250 credits a month, no card needed — then make your first call:

curl "https://api.trawl.dev/ebay/v1/sold?query=iphone+15+pro+256gb&condition=used" \
  -H "x-api-key: YOUR_KEY"

# pip install trawl-api
from trawl_api import Trawl

client = Trawl()  # reads TRAWL_API_KEY
sold = client.ebay.sold("iphone 15 pro 256gb", condition="used")
print(sold.count, sold.results[0].sale_price)

// npm install trawl-api
import { Trawl } from 'trawl-api'

const client = new Trawl() // reads TRAWL_API_KEY
const sold = await client.ebay.sold('iphone 15 pro 256gb', { condition: 'used' })
console.log(sold.count, sold.results[0].sale_price)

Prefer to poke around first? The playground runs real requests from your browser.

Authentication

Send your key in the x-api-key header on every request. Header names are case-insensitive. Keys are account-wide, and can be deleted at any time from the console.

x-api-key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Never put the key in a query string — query strings end up in server logs, browser history and Referer headers. And never ship it in client-side code: call the API from your backend, with the key in an environment variable. A key that leaks can be deleted and reminted in seconds from the console.

Plans & usage

Your plan includes a monthly allowance of credits shared across all of your API keys — one pool, no per-key budgets — plus a per-second request rate. A call costs one credit; on /sold, several pages cost one credit per page (see Credits & pages), two with full listing details; a call that finds nothing is free. Only successful (2xx) responses spend credits; errors are free, though they still take a slot in your per-second rate. The window follows your billing cycle: it resets when your subscription starts or renews. A plan change keeps the current window: an upgrade raises your allowance at once (what you've used so far stays used), a downgrade takes effect at the renewal. Free accounts reset on the first of each month, UTC. You're welcome to spend the whole month's allowance as fast as your rate allows.

Every response reports your standing:

A 429 means one of two things: going over your per-second rate (the response carries a Retry-After header — wait and retry), or not enough credits left for the request (no Retry-After — lower max_pages, wait for the reset, or upgrade for a bigger pool). Need more than the largest tier? Talk to us about a custom plan.

Credits & pages

Usage is measured in credits. Every successful response tells you what it cost, in a credits_charged field in the JSON body (and an X-Credits-Charged header). Most calls — /item, /categories, and any /sold search that returns a single page — cost 1 credit. The exceptions are a /sold search that returns several pages, and one with full listing details, which costs 2 credits per page.

/sold can return many pages of results in one response. There is no page-by-page fetching. A page is 100 results, and the only thing you choose is how many pages you want: set max_pages (up to 20) and everything arrives together, newest first — up to 2,000 results in a single call. For more, follow the response's next_cursor (below).

curl "https://api.trawl.dev/ebay/v1/sold?query=iphone+15+pro&max_pages=5" \
  -H "x-api-key: YOUR_KEY"

sold = client.ebay.sold("iphone 15 pro", max_pages=5)

const sold = await client.ebay.sold('iphone 15 pro', { max_pages: 5 })

max_pages is a ceiling on what the call can cost, not the price. You are charged 1 credit per page of results actually returned — count ÷ 100, rounded up (2 per page with details=1). With max_pages=5 you get up to 500 results, and the most that call can ever cost is 5 credits (10 with details):

Full listing details in the same call

A /sold result is the sale: title, price, date, condition. /item is everything else the listing page said — every item specific, the description, all images, seller, shipping, returns. Add details=1 to a search and each result arrives with both: a details object that is exactly what GET /item returns for that item_id, with no second round of calls.

Details cost 2 credits per page. A search with details=1 is sized like one without, in pages of 100, and costs 2 credits per page of results returned instead of 1; nothing if none match.

curl "https://api.trawl.dev/ebay/v1/sold?query=iphone+15+pro&details=1" \
  -H "x-api-key: YOUR_KEY"

sold = client.ebay.sold("iphone 15 pro", details=True)

const sold = await client.ebay.sold('iphone 15 pro', { details: true })

A listing eBay has removed still comes back, because it is a real sale and your comps should not silently lose it. The result carries the sale as usual, with "details": { "listing_state": "removed" } in place of the details.

One thing to know. With details=1, results are limited to the listings /item can answer for — those with full details available, and those eBay has removed; expect fewer results than the same search without it, since full details are available for a portion of sales.

No results, no charge. If your search matches nothing, you get a 200 with "count": 0, "results": [] and "credits_charged": 0. It is a successful request — the search ran, and the answer is that there are no such sales — so don't retry it or treat it as a failure; you simply aren't charged for an answer with nothing in it. The same goes for a /categories lookup that finds nothing. A failure on our side is never a 200: it is a 5xx with an error field, and errors are always free too.

Beyond 2,000: cursors

If count equals max_pages × 100, the response is full and more may exist. It then carries a next_cursor: send it back unchanged as cursor= on the same search and the next pages come back from exactly where the last response stopped. Repeat until next_cursor is null — that was the end. There is no limit to how far a cursor walks: a whole category, a whole year, is reachable one response at a time, and each call is priced like any other — 1 credit per page returned, nothing for the empty response that ends a walk.

curl "https://api.trawl.dev/ebay/v1/sold?category=261328&date_from=2026-10-01&date_to=2026-10-01&max_pages=20" \
  -H "x-api-key: $TRAWL_KEY"
# → 2,000 results, "next_cursor": "WzEsMTc…"
curl "https://api.trawl.dev/ebay/v1/sold?category=261328&date_from=2026-10-01&date_to=2026-10-01&max_pages=20&cursor=WzEsMTc…" \
  -H "x-api-key: $TRAWL_KEY"
# → the next 2,000, and the next cursor … until "next_cursor": null

cursor = None
while True:
    sold = client.ebay.sold(None, category=261328, date_from="2026-10-01", date_to="2026-10-01", max_pages=20, cursor=cursor)
    # ... 2,000 results a call
    cursor = sold.next_cursor
    if cursor is None:
        break

let cursor = null
do {
  const sold = await client.ebay.sold(null, { category: 261328, date_from: '2026-10-01', date_to: '2026-10-01', max_pages: 20, cursor })
  // ... 2,000 results a call
  cursor = sold.next_cursor
} while (cursor)

A cursor is a position in the results, not a session: it is never stored on our side and never expires. It is bound to the search that issued it — the same site, query, exclude, category, prices, dates, condition, attr and details — and refused with a 400 on any other; max_pages is the one thing you may change between calls. It cannot be combined with page.

A whole category, no keyword. query is required only when there is no category: a leaf category on its own returns every sale in it, newest first. Add date_from and date_to for a day or a month, and the cursor walks the rest. Before running a request, we check that your remaining credits cover the most it could cost — its max_pages; if they don't, you get a 429 that says so and costs nothing.

Errors

Successful requests return 200 — including a search that matches nothing, which is a successful (and free) empty result, not an error. Everything else returns JSON with a single error field explaining what went wrong:

{ "error": "min_price must be <= max_price" }

Health

One call tells you whether the API is up and how current its data is: the newest sale you can search and when we collected it. Point an uptime monitor at it. It answers 200 when everything is reachable and 503 when something is not.

Send your key as on any other call. It is free: it spends no credits, still answers when your credits are spent, doesn't count toward your per-second rate and doesn't show in your usage. It allows one request a second; faster gets a 429 with Retry-After: 1.

With no parameters it reports on the whole marketplace. Add category (a leaf category id, the same as on /sold) to report on one category, and site to pick the marketplace: /health?category=261328 is the newest sale in Trading Card Singles on ebay.com. Those two are the only parameters it takes: any other answers a 400 that names it.

{
  "ok": true,
  "time": "2026-11-06T01:01:37.787Z",
  "products": {
    "ebay": {
      "ok": true,
      "site": "EBAY_US",
      "category": "261328",
      "category_name": "Trading Card Singles",
      "last_sale_at": "2026-11-06T00:49:00.000Z",
      "last_sale_seconds_ago": 757,
      "last_scraped_at": "2026-11-06T00:55:32.053Z",
      "last_scraped_seconds_ago": 365
    }
  }
}

The gap between last_sale_at and last_scraped_at is how far behind eBay we were on that sale, usually a few minutes. To watch the feed, poll without a category: something on the marketplace sells every minute, so an old answer there means we are behind. In one category an old last_sale_at can just mean nothing has sold there lately.

Guides

One runnable script each, with the output it printed on the date shown on the page.

• eBay findCompletedItems alternative
• Scrape eBay sold listings in Python
• eBay sold listings history beyond the 90-day window
• Does eBay API return sold listings?
• The eBay sold comps API: comps for one item in one call
• eBay UK sold listings API

Comparisons

What each alternative does, row by row, with the sources read and the date.

• Trawl vs the eBay Marketplace Insights API
• Trawl vs an Apify eBay sold listings scraper
• Trawl vs Terapeak: the Terapeak API alternative
• Trawl vs the SoldComps API