## ebay/search

`GET /v1/ebay/search`

Search live eBay listings by keyword: title, price, condition, seller, shipping, and thumbnails, with filters for price, condition, and buying format.

*Search eBay listings*

| Parameter | Required | Description |
| --- | --- | --- |
| `query` | yes | Keywords to search listing titles for — e.g. `iphone 11` |
| `country` | no | Marketplace: a country code (us, gb, de, au, ca, fr…) or a raw eBay marketplace id (EBAY_US). Default us. — e.g. `us` |
| `page` | no | 1-based page number (mapped to offset = (page-1)*limit); use cursor to paginate reliably — e.g. `1` |
| `sort_by` | no | Best-effort sort: price_asc, price_desc, newest, or distance (unrecognized values are ignored) Accepted values: price, price_asc, price+shipping, -price, price_desc, newly_listed, newest, new, distance. Case, spaces, hyphens and underscores are interchangeable. — e.g. `price_asc` |
| `condition` | no | Item condition filter, comma-separated: new, used, refurbished, open_box, for_parts Accepted values (comma-separated): new, used, refurbished, open_box, for_parts, seller refurbished. Case, spaces, hyphens and underscores are interchangeable. — e.g. `new` |
| `buying_format` | no | Buying format filter, comma-separated: fixed_price, auction, best_offer, classified_ad Accepted values (comma-separated): fixed, fixed_price, buy_it_now, bin, auction, best_offer, classified, classified_ad. Case, spaces, hyphens and underscores are interchangeable. — e.g. `auction` |
| `show_only` | no | Extra filters, comma-separated: free_shipping, returns_accepted, authenticity_guarantee Accepted values (comma-separated): free_shipping, returns_accepted, authenticity_guarantee. Case, spaces, hyphens and underscores are interchangeable. — e.g. `free_shipping` |
| `min_price` | no | Minimum price in the marketplace currency — e.g. `50` |
| `max_price` | no | Maximum price in the marketplace currency — e.g. `500` |
| `aspects` | no | Raw eBay aspect_filter expression to narrow by item aspects — e.g. `Brand:{Apple}` |
| `cursor` | no | Opaque pagination cursor returned by the previous page (a stringified offset) — e.g. `25` |
| `dry_run` | no | Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable. — e.g. `1` |

### Useful optional inputs

- `country`: Select the documented market or country filter. Read this endpoint’s country semantics; filtering and source request location can differ.
- `cursor`: Continue the same source traversal with the complete returned cursor. Saved-result retrieval and a new source page can have different prices; quote the next call.
- `dry_run`: Read a free estimate before fetching sources or scheduling paid work. Zero credits; cache status and availability are snapshots rather than guarantees.

**Cost:** 3 credits at list price per successful uncached response; variable-cost operations may quote or settle a different charge. Confirmed uncharged or refunded failures report zero. Pending reconciliation can report credits_used:null; retain request_id and the original idempotency key.

```bash
curl "https://www.monocrawl.com/v1/ebay/search?query=iphone%2011" \
  -H "x-api-key: mn_your_key_here"
```

### Response data

Illustrative abbreviated data; documented core fields are optional and may be null. Additional source fields are allowed.

```json
{
  "_warnings": [
    "example"
  ],
  "count": 0,
  "cursor": null,
  "dropped": 0,
  "items": [
    {
      "adult_only": false,
      "bid_count": 0,
      "buying_options": [
        "example"
      ],
      "categories": [
        {}
      ],
      "condition": "example",
      "condition_id": "example",
      "current_bid_price": {
        "currency": "example",
        "value": 0
      },
      "epid": "example",
      "id": "example",
      "image_url": "https://example.com/example",
      "item_location": {
        "country": "example",
        "postal_code": "example"
      },
      "legacy_id": "example",
      "marketplace_id": "example",
      "price": {
        "currency": "example",
        "value": 0
      },
      "seller": {
        "feedback_percentage": 0,
        "feedback_score": 0,
        "username": "example"
      },
      "shipping": {
        "cost": {},
        "type": "example"
      },
      "thumbnail_url": "https://example.com/example",
      "title": "example",
      "url": "https://example.com/example"
    }
  ],
  "marketplace_id": "example",
  "query": "example",
  "total": 0
}
```

[Field reference](https://www.monocrawl.com/docs/endpoints/ebay/search#response) · [JSON Schema for response.data](https://www.monocrawl.com/schemas/ebay/search.json)