# 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.

- **Request:** `GET https://api.lurkapi.com/v1/ebay/search`
- **Auth:** `x-api-key` header ([get a free key](https://lurkapi.com/login?next=/dashboard))
- **Cost:** 2 credits per call. Validation errors, `401`/`402`/`429` rejections and `5xx` failures are free; `not_found` is charged ([how charging works](https://lurkapi.com/docs.md#credits)).
- **MCP tool:** `ebay_search` on `https://api.lurkapi.com/mcp`
- **Freshness:** responses are cached for up to 15 minutes
- **Try it live:** https://lurkapi.com/docs/ebay/search#try (no signup)
- **Platform:** [eBay](https://lurkapi.com/docs/ebay.md) (ebay.com)
- **Web page:** https://lurkapi.com/docs/ebay/search

## 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.

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

## Example request

Replace `YOUR_API_KEY` with your key, or set `LURKAPI_KEY` for the code. [Get a free key](https://lurkapi.com/login?next=/dashboard).

curl:

```bash
curl "https://api.lurkapi.com/v1/ebay/search?query=nintendo+switch+oled" \
  -H "x-api-key: YOUR_API_KEY"
```

JavaScript:

```js
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:

```python
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 `…`.

200 OK (application/json):

```json
{
  "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.

| 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` | `number`, nullable | 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` | `string`, nullable | The lines under the title other than the condition: the seller's subtitle and key specifics, joined with ` · `. |
| `items[].condition` | `string`, nullable | Condition as the card shows it, e.g. "Brand New", "Pre-Owned", "Good - Refurbished". |
| `items[].image` | `string`, nullable | Thumbnail URL (i.ebayimg.com). |
| `items[].price` | `number`, nullable | 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` | `number`, nullable | 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` | `string`, nullable | The price as shown, e.g. "$189.99" or "$20.00 to $35.00". |
| `items[].original_price` | `number`, nullable | 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` | `number`, nullable | Bids so far, on auctions; null otherwise. |
| `items[].time_left` | `string`, nullable | 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` | `number`, nullable | Shipping to the US: 0 when free, in US dollars; null when the card doesn't show it. |
| `items[].shipping_text` | `string`, nullable | Shipping as shown, e.g. "Free delivery in 2-4 days" or "+$8.99 delivery". |
| `items[].location` | `string`, nullable | Where the item ships from, e.g. "United States" or "China". |
| `items[].free_returns` | `boolean` | The card says free returns. |
| `items[].sold` | `number`, nullable | How many the listing has sold, from "1,234 sold" (a lower bound for "99+ sold"); null when not shown. |
| `items[].watchers` | `number`, nullable | Watchers, from "16+ watchers" (a lower bound); null when not shown. |
| `items[].seller` | `object`, nullable | 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` | `number`, nullable | Positive feedback, percent, e.g. 99.8; null for a seller without ratings. |
| `items[].seller.feedback_count` | `number`, nullable | 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` | `number`, nullable | 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](https://lurkapi.com/docs.md#credits)). [All error codes](https://lurkapi.com/docs.md#errors).

| 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](https://lurkapi.com/docs.md#claude), this endpoint is the `ebay_search` tool. Ask in plain English, for example:

Ask Claude:

```text
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:

```json
{
  "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.

---

Previous: [Linktree page](https://lurkapi.com/docs/linkinbio/linktree.md) · Next: [eBay listing details](https://lurkapi.com/docs/ebay/item.md)