> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scrapebadger.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Listings

> Search an eBay marketplace for active listings.

## Query Parameters

**query** `string` *required*

Search keywords. Matches against listing titles.

**domain** `string` (default: com)

eBay marketplace domain TLD or alias. See [`/v1/ebay/markets`](https://docs.scrapebadger.com/api-reference/endpoint/ebay/list-markets) for all supported values.

Examples: `com`, `co.uk`, `de`, `fr`, `com.au`

**category\_id** `string`

Restrict results to an eBay category id. Use [`/v1/ebay/categories`](https://docs.scrapebadger.com/api-reference/endpoint/ebay/list-categories) to look up ids.

**page** `integer` (default: 1)

Page number for paginated results. Range: `1` - `100`.

Use `pagination.has_more` to know when to stop — eBay re-serves its last
page if you ask past the end, so this API returns an empty page there.

**per\_page** `integer`

Results per page. Clamped to one of `60`, `120`, or `240`.

**sort\_by** `string` (default: best\_match)

Sort order for results.

| Value | Description |
| - | - |
| `best_match` | Best match (default) |
| `ending_soonest` | Auctions ending soonest first |
| `newly_listed` | Most recently listed |
| `price_low_to_high` | Cheapest first (incl. shipping) |
| `price_high_to_low` | Most expensive first (incl. shipping) |

**condition** `string`

Item condition filter.

| Value | Description |
| - | - |
| `new` | Brand new |
| `open_box` | New (other) / open box |
| `refurbished` | Refurbished (any grade) |
| `used` | Pre-owned |
| `for_parts` | For parts or not working |
| `graded` | Trading cards: slabbed (PSA / BGS / CGC) |
| `ungraded` | Trading cards: raw |

`graded` / `ungraded` are eBay's card-specific conditions. Pricing a raw card
against sales that include slabs skews the average badly — price the two
separately.

**buying\_format** `string`

Buying format filter.

| Value | Description |
| - | - |
| `auction` | Auction listings |
| `buy_it_now` | Fixed-price listings |
| `best_offer` | Listings accepting best offers |

**min\_price** `number`

Minimum price filter in the marketplace's local currency.

**max\_price** `number`

Maximum price filter in the marketplace's local currency.

**free\_shipping** `boolean` (default: false)

Only return listings with free shipping.

**location** `string`

Item location.

| Value | Description |
| - | - |
| `domestic` | Only items located in this marketplace's own country (`domain=fr` → France only) |
| `worldwide` | Items from every country |

Omit it and you get eBay's default, which mixes foreign listings into a national
marketplace. Two things follow, and both matter for price research: a national
price series picks up sales that never happened in that country, and a foreign
listing's price is shown **converted** into the marketplace's currency rather
than the amount it actually sold for. `location=domestic` removes both.

Any other value returns `400 invalid_location` — it is never silently ignored.

## Response

**query** `string`

The search query that was executed.

**domain** `string`

Marketplace domain that was searched.

**category\_id** `string`

The category id filter applied (nullable).

**sold** `boolean`

Always `false` for active-listing search (see [`/completed`](https://docs.scrapebadger.com/api-reference/endpoint/ebay/completed) for sold).

**results** `array`

Array of matching listings.

**SearchResult object**

**position** `integer`

Position on the page (1-based).

**item\_id** `string`

eBay listing item id.

**product\_id** `string`

eBay catalog product id, if part of the catalog (nullable).

**title** `string`

Listing title.

**url** `string`

Full URL to the listing.

**image** `string`

Primary image URL.

**price** `object`

Price object with `value`, `currency`, `symbol`, `raw`.

**original\_price** `object`

Strikethrough original price (nullable).

**discount\_percent** `number`

Discount percentage off the original price (nullable).

**condition** `string`

Item condition label.

**brand** `string`

Brand name (nullable).

**buying\_format** `string`

`Buy It Now`, `Auction`, or `Best Offer`.

**is\_auction** `boolean`

Whether the listing is an auction.

**bids** `integer`

Number of bids (auctions only, nullable).

**time\_left** `string`

Relative time remaining for auctions, e.g. `12h 16m` (auctions only, nullable).

**current\_bid** `object`

Current high bid for auction listings with `value`, `currency`, `symbol`, `raw`; mirrors `price`. Null for non-auction (fixed-price) listings.

**shipping** `string`

Raw shipping text.

**shipping\_cost** `object`

Parsed shipping cost (nullable).

**free\_shipping** `boolean`

Whether shipping is free (nullable).

**location** `string`

Where a foreign item ships from, as eBay prints it on the card: `from United States` on co.uk and the other English-language sites, the country alone on ebay.com. `null` for an item in the marketplace's own country, and on localized sites (fr, de, …) where eBay translates the country. `location=domestic` removes foreign items on every marketplace either way.

**returns** `string`

Returns text (nullable).

**sold\_count** `integer`

Number sold (nullable).

**sold\_date** `string`

Sale date text as rendered by eBay, e.g. `2 Jul 2026` (completed/sold cards only; localized on non-English marketplaces, nullable).

**sold\_date\_at** `string`

Best-effort ISO date parsed from `sold_date`, e.g. `2026-07-02` (null when the marketplace's date format is not English).

**watchers** `integer`

Number of watchers (nullable).

**coupon** `string`

Coupon/promo text (nullable).

**rating** `number`

Average catalog rating, if shown (nullable).

**ratings\_total** `integer`

Total ratings, if shown (nullable).

**seller\_name** `string`

Seller username (nullable).

**seller\_feedback\_percent** `number`

Seller positive-feedback percent (nullable).

**seller\_feedback\_score** `integer`

Seller feedback score (nullable).

**program\_badge** `string`

Program badge, e.g. `eBay Refurbished` (nullable).

**is\_sponsored** `boolean`

Always `null`. eBay renders its "Sponsored" badge into every card as anti-scraping bait, so promoted placements cannot be distinguished from organic results.

**facets** `object`

Available filter facets keyed by name, each a list of string values.

**pagination** `object`

Pagination metadata with `current_page`, `per_page`, `total_pages`, `total_results`.

**scraped\_at** `string`

ISO 8601 timestamp when the results were scraped.

### Example Response

```json theme={null}
{
  "query": "nintendo switch oled",
  "domain": "com",
  "category_id": null,
  "sold": false,
  "results": [
    {
      "position": 1,
      "item_id": "256123456789",
      "product_id": "20057872541",
      "title": "Nintendo Switch OLED Model White Console - Brand New Sealed",
      "url": "https://www.ebay.com/itm/256123456789",
      "image": "https://i.ebayimg.com/images/g/abc/s-l500.jpg",
      "price": { "value": 299.99, "currency": "USD", "symbol": "$", "raw": "$299.99" },
      "original_price": { "value": 349.99, "currency": "USD", "symbol": "$", "raw": "$349.99" },
      "discount_percent": 14.0,
      "condition": "Brand New",
      "brand": "Nintendo",
      "buying_format": "Buy It Now",
      "is_auction": false,
      "bids": null,
      "time_left": null,
      "current_bid": null,
      "shipping": "Free shipping",
      "free_shipping": true,
      "location": "United States",
      "sold_count": 42,
      "watchers": 18,
      "seller_name": "topgames_us",
      "seller_feedback_percent": 99.4,
      "seller_feedback_score": 18452,
      "is_sponsored": null
    },
    {
      "position": 2,
      "item_id": "256987654321",
      "title": "Nintendo Switch OLED Console - No Reserve Auction",
      "url": "https://www.ebay.com/itm/256987654321",
      "image": "https://i.ebayimg.com/images/g/def/s-l500.jpg",
      "price": { "value": 212.5, "currency": "USD", "symbol": "$", "raw": "$212.50" },
      "condition": "Used",
      "buying_format": "Auction",
      "is_auction": true,
      "bids": 17,
      "time_left": "12h 16m",
      "current_bid": { "value": 212.5, "currency": "USD", "symbol": "$", "raw": "$212.50" },
      "shipping": "Free shipping",
      "free_shipping": true,
      "location": "United States",
      "seller_name": "retro_deals",
      "is_sponsored": null
    }
  ],
  "facets": { "condition": ["New", "Used"], "buying_format": ["Buy It Now", "Auction"] },
  "pagination": { "current_page": 1, "per_page": 60, "total_pages": 100, "total_results": 6000 },
  "scraped_at": "2026-06-21T12:00:00Z"
}
```

> [!NOTE]
>
> Each search request costs **8 credits**. Failed requests are not charged.


## OpenAPI

````yaml GET /v1/ebay/search
openapi: 3.1.0
info:
  title: ScrapeBadger eBay API
  version: 1.0.0
  description: >-
    eBay marketplace scraping API for searching active and completed (sold)
    listings, fetching item details, reviews, sellers, seller listings and
    feedback, category browsing, autocomplete, and reference data across 18
    marketplaces.
servers:
  - url: https://scrapebadger.com
    description: Production
security:
  - apiKeyAuth: []
paths:
  /v1/ebay/search:
    get:
      tags:
        - eBay Search
      summary: Search Listings
      description: Search an eBay marketplace for active listings.
      operationId: searchEbayListings
      parameters:
        - name: query
          in: query
          required: true
          schema:
            type: string
          description: Search keywords.
        - name: domain
          in: query
          schema:
            type: string
            default: com
          description: eBay marketplace domain TLD or alias (com, co.uk, de, fr, ...).
        - name: category_id
          in: query
          schema:
            type: string
          description: Restrict results to a category id.
        - name: page
          in: query
          schema:
            type: integer
            default: 1
            minimum: 1
            maximum: 100
          description: Page number for paginated results.
        - name: per_page
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 240
          description: Results per page. Clamped to 60, 120 or 240.
        - name: sort_by
          in: query
          schema:
            type: string
            default: best_match
            enum:
              - best_match
              - ending_soonest
              - newly_listed
              - price_low_to_high
              - price_high_to_low
          description: Sort order for results.
        - name: condition
          in: query
          schema:
            type: string
            enum:
              - new
              - open_box
              - refurbished
              - used
              - for_parts
              - graded
              - ungraded
          description: >-
            Item condition. `graded` / `ungraded` are eBay's trading-card
            conditions — slabbed (PSA/BGS/CGC) vs raw — so a card can be priced
            separately from its slabs.
        - name: buying_format
          in: query
          schema:
            type: string
            enum:
              - auction
              - buy_it_now
              - best_offer
          description: Buying format filter.
        - name: min_price
          in: query
          schema:
            type: number
            minimum: 0
          description: Minimum price filter in the marketplace's local currency.
        - name: max_price
          in: query
          schema:
            type: number
            minimum: 0
          description: Maximum price filter in the marketplace's local currency.
        - name: free_shipping
          in: query
          schema:
            type: boolean
            default: false
          description: Only return listings with free shipping.
        - name: location
          in: query
          required: false
          description: >-
            Item location. `domestic` returns only items located in this
            marketplace's own country (`domain=fr` → France only); `worldwide`
            widens to every country. Foreign listings are priced in the
            marketplace's currency after eBay CONVERTS them, so `domestic` is
            also how you get untouched native sale prices.
          schema:
            type: string
            enum:
              - domestic
              - worldwide
      responses:
        '200':
          description: Active listings
          content:
            application/json:
              schema:
                type: object
                properties:
                  query:
                    type:
                      - string
                      - 'null'
                  domain:
                    type: string
                  category_id:
                    type:
                      - string
                      - 'null'
                  sold:
                    type: boolean
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        position:
                          type: integer
                        item_id:
                          type:
                            - string
                            - 'null'
                        product_id:
                          type:
                            - string
                            - 'null'
                        title:
                          type:
                            - string
                            - 'null'
                        url:
                          type:
                            - string
                            - 'null'
                        image:
                          type:
                            - string
                            - 'null'
                        price:
                          type: object
                          properties:
                            value:
                              type:
                                - number
                                - 'null'
                            currency:
                              type:
                                - string
                                - 'null'
                            symbol:
                              type:
                                - string
                                - 'null'
                            raw:
                              type:
                                - string
                                - 'null'
                        original_price:
                          type: object
                          properties:
                            value:
                              type:
                                - number
                                - 'null'
                            currency:
                              type:
                                - string
                                - 'null'
                            symbol:
                              type:
                                - string
                                - 'null'
                            raw:
                              type:
                                - string
                                - 'null'
                        discount_percent:
                          type:
                            - number
                            - 'null'
                        currency:
                          type:
                            - string
                            - 'null'
                        condition:
                          type:
                            - string
                            - 'null'
                        brand:
                          type:
                            - string
                            - 'null'
                        buying_format:
                          type:
                            - string
                            - 'null'
                        is_auction:
                          type: boolean
                        bids:
                          type:
                            - integer
                            - 'null'
                        time_left:
                          type:
                            - string
                            - 'null'
                        current_bid:
                          type:
                            - object
                            - 'null'
                          description: >-
                            Current high bid for auction listings; mirrors
                            `price`. Null for non-auction (fixed-price)
                            listings.
                          properties:
                            value:
                              type:
                                - number
                                - 'null'
                            currency:
                              type:
                                - string
                                - 'null'
                            symbol:
                              type:
                                - string
                                - 'null'
                            raw:
                              type:
                                - string
                                - 'null'
                        shipping:
                          type:
                            - string
                            - 'null'
                        shipping_cost:
                          type: object
                          properties:
                            value:
                              type:
                                - number
                                - 'null'
                            currency:
                              type:
                                - string
                                - 'null'
                            symbol:
                              type:
                                - string
                                - 'null'
                            raw:
                              type:
                                - string
                                - 'null'
                        free_shipping:
                          type:
                            - boolean
                            - 'null'
                        location:
                          type:
                            - string
                            - 'null'
                        returns:
                          type:
                            - string
                            - 'null'
                        sold_count:
                          type:
                            - integer
                            - 'null'
                        sold_date:
                          type:
                            - string
                            - 'null'
                          description: >-
                            Sale date text as rendered by eBay on the sold card,
                            e.g. "2 Jul 2026". Localized on non-English
                            marketplaces (e.g. "Verkauft 5. Okt. 2024"). Null on
                            active listings.
                          examples:
                            - 2 Jul 2026
                        sold_date_at:
                          type:
                            - string
                            - 'null'
                          description: >-
                            Best-effort ISO 8601 date parsed from sold_date,
                            e.g. "2026-07-02". Null when the marketplace's date
                            format is not English.
                          examples:
                            - '2026-07-02'
                        watchers:
                          type:
                            - integer
                            - 'null'
                        coupon:
                          type:
                            - string
                            - 'null'
                        rating:
                          type:
                            - number
                            - 'null'
                        ratings_total:
                          type:
                            - integer
                            - 'null'
                        seller_name:
                          type:
                            - string
                            - 'null'
                        seller_feedback_percent:
                          type:
                            - number
                            - 'null'
                        seller_feedback_score:
                          type:
                            - integer
                            - 'null'
                        program_badge:
                          type:
                            - string
                            - 'null'
                        is_sponsored:
                          type:
                            - boolean
                            - 'null'
                          description: >-
                            Always null — eBay renders its Sponsored badge into
                            every card as anti-scraping bait, so promoted
                            placements cannot be distinguished from organic
                            results.
                  facets:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
                  pagination:
                    type: object
                    properties:
                      current_page:
                        type: integer
                      per_page:
                        type:
                          - integer
                          - 'null'
                      total_pages:
                        type:
                          - integer
                          - 'null'
                      total_results:
                        type:
                          - integer
                          - 'null'
                      has_more:
                        type:
                          - boolean
                          - 'null'
                        description: >-
                          True while eBay still offers a next page — the stop
                          signal for bulk extraction. total_results is populated
                          on completed/sold; total_pages may be null. Past the
                          last page eBay re-serves it, so page on has_more
                          rather than looping until empty.
                  scraped_utc:
                    type:
                      - number
                      - 'null'
                  scraped_at:
                    type:
                      - string
                      - 'null'
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.