# eBay listing details

> One eBay listing by item id or URL: price, condition, quantity sold and available, seller and feedback, shipping, returns, photos and item specifics.

- **Request:** `GET https://api.lurkapi.com/v1/ebay/item`
- **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_item` on `https://api.lurkapi.com/mcp`
- **Freshness:** responses are cached for up to 15 minutes
- **Try it live:** https://lurkapi.com/docs/ebay/item#try (no signup)
- **Platform:** [eBay](https://lurkapi.com/docs/ebay.md) (ebay.com)
- **Web page:** https://lurkapi.com/docs/ebay/item

## When to use this

Use it to track one listing's price and sales, or to enrich a search result. Pass the item id or any eBay listing URL (`/itm/…`, from any eBay site).

For listings with variations (sizes, colors, storage), price and quantity are the default variation's, as on ebay.com. Ended listings still answer, with `ended: true` and the status eBay shows, e.g. "Bidding ended on Mon, Oct 19 at 4:02 PM.", and the last price.

Returns 404 `not_found` when eBay has no such listing, and 403 `not_public` for adult listings, which eBay shows only to signed-in accounts.

## Parameters

All parameters go in the query string.

| Name | Type | Required | Default | Allowed values | Description | Example |
| --- | --- | --- | --- | --- | --- | --- |
| `id` | string | no |  |  | Item id, e.g. `285090601008`. Required unless you pass `url`. | `285090601008` |
| `url` | string | no |  |  | A listing URL, e.g. `https://www.ebay.com/itm/285090601008`. |  |

## 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/item?id=285090601008" \
  -H "x-api-key: YOUR_API_KEY"
```

JavaScript:

```js
const params = new URLSearchParams({
  id: "285090601008",
});
const res = await fetch(`https://api.lurkapi.com/v1/ebay/item?${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.images);
```

Python:

```python
import os
import requests

res = requests.get(
    "https://api.lurkapi.com/v1/ebay/item",
    params={
        "id": "285090601008",
    },
    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["images"])
```

## 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": 999997,
  "credits_charged": 2,
  "id": "285090601008",
  "url": "https://www.ebay.com/itm/285090601008",
  "title": "Bulk LEGO LOT 5 pound box Bricks, parts, Pieces, Tires accessories by the pound",
  "price": 39.94,
  "currency": "USD",
  "price_text": "US $39.94",
  "original_price": 46.99,
  "format": "fixed_price",
  "bids": null,
  "ends_at": null,
  "best_offer": false,
  "condition": "Used",
  "seller_notes": "2 Buck discount if you read the description below and click in descripti…",
  "available": 10,
  "sold": 1488,
  "ended": false,
  "status": null,
  "has_variations": false,
  "seller": {
    "username": "authentic*lego*shop",
    "name": "authenticlegoshop",
    "url": "https://www.ebay.com/str/northernmidwestlegoandtoyshop",
    "feedback_percent": 99.9,
    "feedback_count": 22047
  },
  "shipping_cost": 0,
  "shipping_text": "Free USPS Ground Advantage®.",
  "location": "Rossville, Georgia, United States",
  "returns": "30 days returns. Seller pays for return shipping.",
  "images": [
    "https://i.ebayimg.com/images/g/WxsAAeSwqcpqwF-I/s-l1600.png",
    "https://i.ebayimg.com/images/g/SPQAAeSw9nRqwBNR/s-l1600.jpg",
    "https://i.ebayimg.com/images/g/d7kAAeSwKqZqt~iB/s-l1600.jpg",
    "https://i.ebayimg.com/images/g/KtUAAeSwVIxqvwOc/s-l1600.jpg",
    "https://i.ebayimg.com/images/g/KwEAAeSw-zpqt~iB/s-l1600.jpg"
  ],
  "item_specifics": {
    "Brand": "Lego",
    "Piece Type": "Lot",
    "Custom Bundle": "No",
    "Features": "MOC - My Own Creation",
    "Recommended Age Range": "5",
    "Country of Origin": "United States",
    "Modified Item": "No",
    "UPC": "Does not apply"
  },
  "category": [
    "Toys & Hobbies",
    "Building Toys",
    "LEGO (R) Building Toys",
    "LEGO (R) Bricks, Pieces & Parts"
  ],
  "category_id": "183448",
  "listed_at": "2022-12-28T18:18:39Z",
  "description_url": "https://itm.ebaydesc.com/itmdesc/285090601008?t=1791591755000&category=1…"
}
```

## 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). |
| `id` | `string` | Item id. |
| `url` | `string` | The listing on ebay.com. |
| `title` | `string` | Listing title. |
| `price` | `number`, nullable | Current price (the current bid on auctions), in `currency`. |
| `currency` | `string`, nullable | The price's currency, e.g. USD; the seller's own currency on some international listings. |
| `price_text` | `string`, nullable | The price as ebay.com shows it, e.g. "US $189.99". |
| `original_price` | `number`, nullable | The struck-through list price on discounted listings, in `currency`; null otherwise. |
| `format` | `string` | `auction` when the listing takes bids, else `fixed_price`. |
| `bids` | `number`, nullable | Bids so far, on auctions; null otherwise. |
| `ends_at` | `string`, nullable | When an auction ends, ISO 8601; null for fixed-price listings. |
| `best_offer` | `boolean` | The seller accepts offers. |
| `condition` | `string`, nullable | Condition, e.g. "New", "Used", "Pre-owned - Good". |
| `seller_notes` | `string`, nullable | The seller's note on the condition; null without one. |
| `available` | `number`, nullable | Quantity available: "3 available" → 3, "Last one" → 1, "More than 10 available" → 10 (a lower bound); null when not shown. |
| `sold` | `number`, nullable | How many this listing has sold, from "10 sold"; null when not shown. |
| `ended` | `boolean` | The listing has ended (sold, ended by the seller, or out of time). |
| `status` | `string`, nullable | The notice eBay shows on ended listings, e.g. "Bidding ended on Mon, Oct 19 at 4:02 PM."; null on live ones. |
| `has_variations` | `boolean` | The listing has variations (sizes, colors…); price and quantity are the default one's. |
| `seller` | `object` | Who sells it. |
| `seller.username` | `string`, nullable | eBay username. Search by seller on eBay with it. |
| `seller.name` | `string`, nullable | The name the listing shows: the store name for eBay Stores, else the username. |
| `seller.url` | `string`, nullable | The seller's store or items page. |
| `seller.feedback_percent` | `number`, nullable | Positive feedback, percent, e.g. 99.8. |
| `seller.feedback_count` | `number`, nullable | Feedback score, e.g. 42027. |
| `shipping_cost` | `number`, nullable | Shipping to the US in `currency`, 0 when free; null when eBay doesn't say (e.g. local pickup only). |
| `shipping_text` | `string`, nullable | Shipping as shown, e.g. "Free USPS Ground Advantage®." |
| `location` | `string`, nullable | Where the item is, e.g. "Virginia Beach, Virginia, United States". |
| `returns` | `string`, nullable | Return policy as shown, e.g. "30 days returns. Seller pays for return shipping." |
| `images` | `string[]` | Every listing photo, full size (up to 1600 px), in the seller's order. |
| `item_specifics` | `object` | Item specifics as the seller filled them in, e.g. {"Brand": "Apple", "Model": "iPhone 12 mini"}. Condition is in `condition`. |
| `category` | `string[]` | Category path, broadest first, e.g. ["Electronics", "Cell Phones & Accessories", "Cell Phones & Smartphones"]; empty if eBay doesn't show it. |
| `category_id` | `string`, nullable | The listing's category number; pass it as `category_id` to search eBay listings for similar ones. |
| `listed_at` | `string`, nullable | When the listing started, ISO 8601. |
| `description_url` | `string`, nullable | The seller's description as its own HTML page (eBay loads it in a frame). |

## 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. |
| 403 | `not_public` | The platform confirmed this account or content isn't available to logged-out visitors. Use a publicly visible target. Charged when the platform was checked. |
| 404 | `not_found` | The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked. |
| 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_item` tool. Ask in plain English, for example:

Ask Claude:

```text
Use LurkAPI's ebay_item with id "285090601008" and summarize what you find.
```

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

Tool arguments:

```json
{
  "id": "285090601008"
}
```

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: [Search eBay listings](https://lurkapi.com/docs/ebay/search.md) · Next: [Scrape a page (Auto)](https://lurkapi.com/docs/web/scrape.md)