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

<ParamField query="query" type="string" required>
  Search keywords. Matches against listing titles.
</ParamField>

<ParamField query="domain" type="string" default="com">
  eBay marketplace domain TLD or alias. See [`/v1/ebay/markets`](/api-reference/endpoint/ebay/list-markets) for all supported values.

  Examples: `com`, `co.uk`, `de`, `fr`, `com.au`
</ParamField>

<ParamField query="category_id" type="string">
  Restrict results to an eBay category id. Use [`/v1/ebay/categories`](/api-reference/endpoint/ebay/list-categories) to look up ids.
</ParamField>

<ParamField query="page" type="integer" default={1}>
  Page number for paginated results. Range: `1` - `100`.
</ParamField>

<ParamField query="per_page" type="integer">
  Results per page. Clamped to one of `60`, `120`, or `240`.
</ParamField>

<ParamField query="sort_by" type="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) |
</ParamField>

<ParamField query="condition" type="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 |
</ParamField>

<ParamField query="buying_format" type="string">
  Buying format filter.

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

<ParamField query="min_price" type="number">
  Minimum price filter in the marketplace's local currency.
</ParamField>

<ParamField query="max_price" type="number">
  Maximum price filter in the marketplace's local currency.
</ParamField>

<ParamField query="free_shipping" type="boolean" default={false}>
  Only return listings with free shipping.
</ParamField>

## Response

<ResponseField name="query" type="string">The search query that was executed.</ResponseField>
<ResponseField name="domain" type="string">Marketplace domain that was searched.</ResponseField>
<ResponseField name="category_id" type="string">The category id filter applied (nullable).</ResponseField>
<ResponseField name="sold" type="boolean">Always `false` for active-listing search (see [`/completed`](/api-reference/endpoint/ebay/completed) for sold).</ResponseField>

<ResponseField name="results" type="array">
  Array of matching listings.

  <Expandable title="SearchResult object">
    <ResponseField name="position" type="integer">Position on the page (1-based).</ResponseField>
    <ResponseField name="item_id" type="string">eBay listing item id.</ResponseField>
    <ResponseField name="product_id" type="string">eBay catalog product id, if part of the catalog (nullable).</ResponseField>
    <ResponseField name="title" type="string">Listing title.</ResponseField>
    <ResponseField name="url" type="string">Full URL to the listing.</ResponseField>
    <ResponseField name="image" type="string">Primary image URL.</ResponseField>
    <ResponseField name="price" type="object">Price object with `value`, `currency`, `symbol`, `raw`.</ResponseField>
    <ResponseField name="original_price" type="object">Strikethrough original price (nullable).</ResponseField>
    <ResponseField name="discount_percent" type="number">Discount percentage off the original price (nullable).</ResponseField>
    <ResponseField name="condition" type="string">Item condition label.</ResponseField>
    <ResponseField name="brand" type="string">Brand name (nullable).</ResponseField>
    <ResponseField name="buying_format" type="string">`Buy It Now`, `Auction`, or `Best Offer`.</ResponseField>
    <ResponseField name="is_auction" type="boolean">Whether the listing is an auction.</ResponseField>
    <ResponseField name="bids" type="integer">Number of bids (auctions only, nullable).</ResponseField>
    <ResponseField name="time_left" type="string">Relative time remaining for auctions, e.g. `12h 16m` (auctions only, nullable).</ResponseField>
    <ResponseField name="current_bid" type="object">Current high bid for auction listings with `value`, `currency`, `symbol`, `raw`; mirrors `price`. Null for non-auction (fixed-price) listings.</ResponseField>
    <ResponseField name="shipping" type="string">Raw shipping text.</ResponseField>
    <ResponseField name="shipping_cost" type="object">Parsed shipping cost (nullable).</ResponseField>
    <ResponseField name="free_shipping" type="boolean">Whether shipping is free (nullable).</ResponseField>
    <ResponseField name="location" type="string">Item location text.</ResponseField>
    <ResponseField name="returns" type="string">Returns text (nullable).</ResponseField>
    <ResponseField name="sold_count" type="integer">Number sold (nullable).</ResponseField>
    <ResponseField name="watchers" type="integer">Number of watchers (nullable).</ResponseField>
    <ResponseField name="coupon" type="string">Coupon/promo text (nullable).</ResponseField>
    <ResponseField name="rating" type="number">Average catalog rating, if shown (nullable).</ResponseField>
    <ResponseField name="ratings_total" type="integer">Total ratings, if shown (nullable).</ResponseField>
    <ResponseField name="seller_name" type="string">Seller username (nullable).</ResponseField>
    <ResponseField name="seller_feedback_percent" type="number">Seller positive-feedback percent (nullable).</ResponseField>
    <ResponseField name="seller_feedback_score" type="integer">Seller feedback score (nullable).</ResponseField>
    <ResponseField name="program_badge" type="string">Program badge, e.g. `eBay Refurbished` (nullable).</ResponseField>
    <ResponseField name="is_sponsored" type="boolean">Whether the result is a sponsored placement.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="facets" type="object">Available filter facets keyed by name, each a list of string values.</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination metadata with `current_page`, `per_page`, `total_pages`, `total_results`.
</ResponseField>

<ResponseField name="scraped_at" type="string">ISO 8601 timestamp when the results were scraped.</ResponseField>

### 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": false
    },
    {
      "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": false
    }
  ],
  "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 **5 credits**. Failed requests are not charged.
</Note>


## 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
          description: Item condition filter.
        - 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.
      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'
                        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
                  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'
                  scraped_utc:
                    type:
                      - number
                      - 'null'
                  scraped_at:
                    type:
                      - string
                      - 'null'
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````