Docs · Search eBay listings

Search eBay listings

Active eBay listings for a keyword, with price, bids, condition, shipping, seller and how many sold, filtered and sorted like ebay.com.

2 credits per callFresh within 15 minutesMCP tool: ebay_search

GEThttps://api.lurkapi.com/v1/ebay/search

Example response View as markdown

Try it live

GET /v1/ebay/search

2 credits

Examples

Keywords *

Keywords, as typed into eBay's search box, e.g. iphone 15 pro.

More options (8)

Condition

new, open_box, refurbished (any refurbished grade), used, for_parts, or any (default).

Buying format

buy_it_now, auction, best_offer (accepts offers), or any (default).

Sort

best_match (eBay's default), ending_soonest, newly_listed, price_low or price_high (price plus shipping).

Min price

Lowest item price in US dollars, e.g. 100.

Max price

Highest item price in US dollars, e.g. 500.

Free shipping

true keeps listings with free shipping only.

Category ID

An eBay category number, e.g. 9355 (Cell Phones & Smartphones).

Page

Page of results, 1–100; 60 listings each. Use next_page from the previous answer.

5 free tries a day, no signup

When to use this

Use it for price research and sourcing: what's listed, at what price, in what condition, and which listings sell. Filters map to eBay's own: condition, buying_format, min_price/max_price (item price, without shipping), free_shipping and category_id (the number in an eBay category URL, or category_id from listing details).

Results are eBay's own cards: sponsored listings eBay places among the results are included, as on ebay.com; carousels and ads between them aren't. sold is how many a multi-quantity listing has sold, not sold listings: eBay shows those only to signed-in accounts.

Pagination. 60 listings per page. Pass next_page as page for more; it's null on the last page.

Parameters

All parameters go in the query string.

Parameter	Description
`query` stringrequired	Keywords, as typed into eBay's search box, e.g. `iphone 15 pro`. Example `nintendo switch oled`
`condition` stringoptional	`new`, `open_box`, `refurbished` (any refurbished grade), `used`, `for_parts`, or `any` (default). One of `anynewopen_boxrefurbishedusedfor_parts` Default `any`
`buying_format` stringoptional	`buy_it_now`, `auction`, `best_offer` (accepts offers), or `any` (default). One of `anybuy_it_nowauctionbest_offer` Default `any`
`sort` stringoptional	`best_match` (eBay's default), `ending_soonest`, `newly_listed`, `price_low` or `price_high` (price plus shipping). One of `best_matchending_soonestnewly_listedprice_lowprice_high` Default `best_match`
`min_price` numberoptional	Lowest item price in US dollars, e.g. `100`.
`max_price` numberoptional	Highest item price in US dollars, e.g. `500`.
`free_shipping` booleanoptional	`true` keeps listings with free shipping only. One of `truefalse` Default `false`
`category_id` stringoptional	An eBay category number, e.g. `9355` (Cell Phones & Smartphones).
`page` integeroptional	Page of results, 1–100; 60 listings each. Use `next_page` from the previous answer. Default `1`

Example request

Replace YOUR_API_KEY with your key, or set LURKAPI_KEY for the code. Get a free key.

curlJavaScriptPython

JavaScript · reads your key from LURKAPI_KEY

const params = new URLSearchParams({
  query: "nintendo switch oled",
});
const res = await fetch(`https://api.lurkapi.com/v1/ebay/search?${params}`, {
  headers: { "x-api-key": process.env.LURKAPI_KEY },
});
const data = await res.json();
if (!data.success) throw new Error(`${data.code}: ${data.error}`);
console.log(data.items);

Python · reads your key from LURKAPI_KEY

import os
import requests

res = requests.get(
    "https://api.lurkapi.com/v1/ebay/search",
    params={
        "query": "nintendo switch oled",
    },
    headers={"x-api-key": os.environ["LURKAPI_KEY"]},
    timeout=60,
)
data = res.json()
if not data["success"]:
    raise RuntimeError(f"{data['code']}: {data['error']}")
print(data["items"])

Example response

A real response from this endpoint, captured from the live API and trimmed to a couple of items. Strings over 96 characters (mostly signed media URLs) are cut short and end in ….

Show the example response (2 KB)

{
  "success": true,
  "credits_remaining": 999998,
  "credits_charged": 2,
  "total_results": 6600,
  "items": [
    {
      "id": "226794283368",
      "url": "https://www.ebay.com/itm/226794283368",
      "title": "Nintendo Switch OLED Model HEG-001 Handheld Console w/ Accessories - Excellent",
      "subtitle": "Nintendo Switch · Nintendo Switch (OLED Model)",
      "condition": "Pre-Owned",
      "image": "https://i.ebayimg.com/images/g/XXUAAeSwrqNpvBXC/s-l500.webp",
      "price": 244.99,
      "price_max": 249.99,
      "price_text": "$244.99 to $249.99",
      "original_price": 284.99,
      "format": "fixed_price",
      "bids": null,
      "time_left": null,
      "best_offer": false,
      "shipping_cost": 12.99,
      "shipping_text": "+$12.99 delivery",
      "location": "United States",
      "free_returns": false,
      "sold": 6,
      "watchers": null,
      "seller": {
        "username": "cocosprinkles",
        "feedback_percent": 99.8,
        "feedback_count": 42000
      },
      "badges": [
        "From $225.39 with coupon"
      ]
    },
    {
      "id": "336852421836",
      "url": "https://www.ebay.com/itm/336852421836",
      "title": "Nintendo Switch OLED Model Console with case, 128 GB SD card and deck.",
      "subtitle": "Nintendo Switch · Nintendo Switch (OLED Model)",
      "condition": "Pre-Owned",
      "image": "https://i.ebayimg.com/images/g/gSgAAeSw~oxq1i4A/s-l500.webp",
      "price": 175,
      "price_max": null,
      "price_text": "$175.00",
      "original_price": null,
      "format": "fixed_price",
      "bids": null,
      "time_left": null,
      "best_offer": true,
      "shipping_cost": 12.97,
      "shipping_text": "+$12.97 delivery",
      "location": "United States",
      "free_returns": false,
      "sold": null,
      "watchers": null,
      "seller": {
        "username": "hat-1634",
        "feedback_percent": null,
        "feedback_count": 0
      },
      "badges": [
        "New Listing"
      ]
    }
  ],
  "page": 1,
  "next_page": 2
}

Response fields

Every field of a successful response. [] marks a list: a[].b is the b of each item in a. nullable fields can be null; optional fields can be missing.

Show all 32 fields

Field	Type	Description
success	true	Always true here; errors have `success: false`.
credits_remaining	number	Your balance after this call. On anonymous playground calls: free tries left today.
credits_charged	number	Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1).
total_results	numbernullable	Matching listings as eBay counts them, from "40,000+ results" (a rounded lower bound for big searches).
items	object[]	One page of listings, in `sort` order.
items[].id	string	Item id, e.g. `285090601008`. Pass it to eBay listing details (ebay_item) for specifics, seller and shipping.
items[].url	string	The listing on ebay.com.
items[].title	string	Listing title.
items[].subtitle	stringnullable	The lines under the title other than the condition: the seller's subtitle and key specifics, joined with `·` .
items[].condition	stringnullable	Condition as the card shows it, e.g. "Brand New", "Pre-Owned", "Good - Refurbished".
items[].image	stringnullable	Thumbnail URL (i.ebayimg.com).
items[].price	numbernullable	Price (the low end of a range, for listings with variations), in US dollars; null when the card doesn't show it.
items[].price_max	numbernullable	The high end of a price range; null for a single price, in US dollars; null when the card doesn't show it.
items[].price_text	stringnullable	The price as shown, e.g. "$189.99" or "$20.00 to $35.00".
items[].original_price	numbernullable	The struck-through earlier price on discounted listings, in US dollars; null when the card doesn't show it.
items[].format	string	`auction` when the card shows bids, else `fixed_price`.
items[].bids	numbernullable	Bids so far, on auctions; null otherwise.
items[].time_left	stringnullable	Time left on auctions as shown, e.g. "6d 23h" or "46m"; null otherwise.
items[].best_offer	boolean	The seller accepts offers.
items[].shipping_cost	numbernullable	Shipping to the US: 0 when free, in US dollars; null when the card doesn't show it.
items[].shipping_text	stringnullable	Shipping as shown, e.g. "Free delivery in 2-4 days" or "+$8.99 delivery".
items[].location	stringnullable	Where the item ships from, e.g. "United States" or "China".
items[].free_returns	boolean	The card says free returns.
items[].sold	numbernullable	How many the listing has sold, from "1,234 sold" (a lower bound for "99+ sold"); null when not shown.
items[].watchers	numbernullable	Watchers, from "16+ watchers" (a lower bound); null when not shown.
items[].seller	objectnullable	The seller, when the card shows one (eBay leaves it off some layouts).
items[].seller.username	string	The seller's eBay username.
items[].seller.feedback_percent	numbernullable	Positive feedback, percent, e.g. 99.8; null for a seller without ratings.
items[].seller.feedback_count	numbernullable	Feedback score as the card shows it; eBay rounds large ones (42K → 42000).
items[].badges	string[]	Other labels on the card, e.g. "New Listing", "Last one", "eBay Refurbished", "Authenticity Guarantee", coupons.
page	number	This page's number.
next_page	numbernullable	Pass as `page` for the next 60 listings; null on the last page.

Caching and freshness

Responses are cached for up to 15 minutes, so a repeat call within that window can return the same data. It still costs 2 credits.

Errors

Errors return { success: false, error, code, docs } with the HTTP status below. Validation errors, 401/402/429 rejections and 5xx failures are free; not_found is charged (how charging works). All error codes.

Status	Code	Meaning
401	`missing_api_key`	No API key. Send it in the `x-api-key` header.
401	`invalid_api_key`	The key is unknown or was revoked.
402	`insufficient_credits`	Not enough credits for this call. Buy a pack or wait for tomorrow's top-up.
403	`account_suspended`	This account is suspended. Contact support@lurkapi.com. Never charged.
405	`method_not_allowed`	Endpoints take GET with query params.
429	`rate_limited`	Too many calls at once. Wait for the `retry-after` seconds, then retry.
500	`internal_error`	Something broke on our side. Retry; 5xx errors are free.
502	`upstream_error`	The platform didn't give a usable answer. Retry; 5xx errors are free.
503	`upstream_busy`	All our connections to the platform are busy. Retry in a few seconds; 5xx errors are free.
504	`upstream_timeout`	The platform took over 30 seconds to answer (90 for web pages). Retry; timeouts are free.

Use it in Claude

Once LurkAPI is connected to Claude, this endpoint is the ebay_search tool. Ask in plain English, for example:

Ask Claude

Use LurkAPI's ebay_search with query "nintendo switch oled" and summarize what you find.

Claude calls ebay_search with arguments like these, and each call costs 2 credits:

Tool arguments

{
  "query": "nintendo switch oled"
}

Tool results are compact to save tokens: no nulls or empty lists, one URL per image or video, transcripts as plain text unless you pass timestamps=true. A result over 45,000 characters comes in parts: its _note gives the offset for the rest, and later parts are free for 15 minutes. trim=false returns the full response.

From the blog

All posts