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

> Search Vinted catalog items with filters.

## Query Parameters

<ParamField query="query" type="string" required>
  Search query string. Matches against item titles and descriptions.
</ParamField>

<ParamField query="market" type="string" default="fr">
  Vinted market to search. See [`/v1/vinted/markets`](/api-reference/endpoint/vinted/list-markets) for all supported values.

  Examples: `fr`, `de`, `uk`, `it`, `es`, `pl`, `us`
</ParamField>

<ParamField query="page" type="integer" default={1}>
  Page number for paginated results. Starts at `1`.
</ParamField>

<ParamField query="per_page" type="integer" default={24}>
  Number of items per page. Range: `1` - `96`.
</ParamField>

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

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

<ParamField query="brand_ids" type="string">
  Comma-separated list of brand IDs to filter by. Use [`/v1/vinted/brands`](/api-reference/endpoint/vinted/search-brands) to look up IDs.

  Example: `53`, `14,53,221`
</ParamField>

<ParamField query="color_ids" type="string">
  Comma-separated list of color IDs to filter by. Use [`/v1/vinted/colors`](/api-reference/endpoint/vinted/list-colors) to look up IDs.

  Example: `1`, `1,4,12`
</ParamField>

<ParamField query="status_ids" type="string">
  Comma-separated list of condition status IDs to filter by. Use [`/v1/vinted/statuses`](/api-reference/endpoint/vinted/list-statuses) to look up IDs.

  Example: `6` (New with tags), `1,2` (New without tags, Very good)
</ParamField>

<ParamField query="order" type="string" default="relevance">
  Sort order for results.

  | Value               | Description          |
  | ------------------- | -------------------- |
  | `relevance`         | Best match (default) |
  | `price_low_to_high` | Cheapest first       |
  | `price_high_to_low` | Most expensive first |
  | `newest_first`      | Most recently listed |
</ParamField>

<ParamField query="seller_country" type="string">
  Comma-separated list of ISO 3166-1 alpha-2 country codes (case-insensitive) to keep only items whose **seller is physically located** in one of those countries.

  Vinted markets federate listings across borders — a search on `vinted.fr` returns items from sellers in IT, DE, NL, ES, and elsewhere (prices and labels are localized, but the seller is abroad). Vinted exposes no native country facet, so ScrapeBadger resolves each result item's seller country and drops items outside the requested set.

  Examples: `fr`, `fr,be`, `IT,ES`

  <Note>
    `market` and `seller_country` are **different axes**. `market` selects which Vinted domain you search (which catalog and currency you see); `seller_country` filters on where the seller actually is. For example, `market=fr&seller_country=it` searches the French catalog but returns only items shipped by sellers in Italy.
  </Note>

  <Warning>
    Pagination totals (`total_entries` / `total_pages`) reflect Vinted's **unfiltered** result set. After seller-country filtering, a page may contain fewer than `per_page` items (or none), even though more matching items exist on later pages. Iterate through pages until you have collected enough matching items.
  </Warning>
</ParamField>

## Response

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

  <Expandable title="Item object">
    <ResponseField name="id" type="integer">Item ID.</ResponseField>
    <ResponseField name="title" type="string">Item title.</ResponseField>
    <ResponseField name="price" type="string">Price in local currency (e.g. `"15.00"`).</ResponseField>
    <ResponseField name="currency" type="string">ISO 4217 currency code (e.g. `"EUR"`).</ResponseField>
    <ResponseField name="brand_title" type="string">Brand name.</ResponseField>
    <ResponseField name="size_title" type="string">Size label.</ResponseField>
    <ResponseField name="photo" type="object">Primary photo with `url`, `width`, `height`.</ResponseField>
    <ResponseField name="url" type="string">Full URL to the Vinted listing.</ResponseField>
    <ResponseField name="user" type="object">Seller summary with `id`, `login`, `photo`.</ResponseField>
    <ResponseField name="favourite_count" type="integer">Number of users who favourited this item.</ResponseField>

    <ResponseField name="seller_country_code" type="string">
      ISO 3166-1 alpha-2 code of the seller's physical country (e.g. `"IT"`), or `null` if it could not be resolved. Always present on each item; populated whether or not `seller_country` filtering was requested.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total_entries" type="integer">
  Total number of matching items across all pages.
</ResponseField>

<ResponseField name="current_page" type="integer">
  Current page number.
</ResponseField>

<ResponseField name="per_page" type="integer">
  Number of items per page.
</ResponseField>

<ResponseField name="seller_country" type="string">
  Echo of the normalized `seller_country` filter that was applied (uppercase, comma-separated ISO-2 codes, e.g. `"FR,BE"`), or `null` when no filter was requested.
</ResponseField>

### Example Response

```json theme={null}
{
  "items": [
    {
      "id": 4856231890,
      "title": "Nike Air Force 1 '07 White",
      "price": "45.00",
      "currency": "EUR",
      "brand_title": "Nike",
      "size_title": "42",
      "photo": {
        "url": "https://images1.vinted.net/t/...",
        "width": 800,
        "height": 600
      },
      "url": "https://www.vinted.fr/items/4856231890",
      "user": {
        "id": 12345678,
        "login": "seller_username",
        "photo": {
          "url": "https://images1.vinted.net/t/..."
        }
      },
      "favourite_count": 12,
      "seller_country_code": "FR"
    }
  ],
  "total_entries": 2847,
  "current_page": 1,
  "per_page": 24,
  "seller_country": "FR"
}
```

### Example Request — filter by seller country

Return only listings from sellers physically located in France:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://scrapebadger.com/v1/vinted/search?query=nike+air+force+1&market=fr&seller_country=fr&per_page=20" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const results = await client.vinted.search({
    query: "nike air force 1",
    market: "fr",
    seller_country: "fr",
    per_page: 20,
  });
  ```

  ```python Python theme={null}
  results = client.vinted.search(
      query="nike air force 1",
      market="fr",
      seller_country="fr",
      per_page=20,
  )
  ```
</CodeGroup>

<Note>
  A search costs **1 base credit + 1 credit per uncached seller** looked up to resolve seller country. Seller countries are cached for 7 days, so cache hits are free: a fresh page of 20 distinct sellers costs ≈ 21 credits, while repeated or overlapping searches are far cheaper. When `seller_country` is omitted, no seller lookups are performed and the request costs **1 credit**. Failed requests are not charged.
</Note>


## OpenAPI

````yaml GET /v1/vinted/search
openapi: 3.1.0
info:
  title: ScrapeBadger Vinted API
  version: 1.0.0
  description: >-
    Vinted marketplace scraping API for searching items, fetching details, user
    profiles, and reference data.
servers:
  - url: https://scrapebadger.com
    description: Production
security:
  - apiKeyAuth: []
paths:
  /v1/vinted/search:
    get:
      summary: Search Items
      description: Search Vinted catalog items with filters.
      operationId: searchVintedItems
      parameters:
        - name: query
          in: query
          required: true
          schema:
            type: string
          description: Search query string. Matches against item titles and descriptions.
        - name: market
          in: query
          schema:
            type: string
            default: fr
          description: Vinted market to search (e.g. fr, de, uk, it, es, pl, us).
        - name: page
          in: query
          schema:
            type: integer
            default: 1
            minimum: 1
          description: Page number for paginated results.
        - name: per_page
          in: query
          schema:
            type: integer
            default: 24
            minimum: 1
            maximum: 96
          description: Number of items per page.
        - name: price_from
          in: query
          schema:
            type: number
          description: Minimum price filter in the market's local currency.
        - name: price_to
          in: query
          schema:
            type: number
          description: Maximum price filter in the market's local currency.
        - name: brand_ids
          in: query
          schema:
            type: string
          description: Comma-separated list of brand IDs to filter by.
        - name: color_ids
          in: query
          schema:
            type: string
          description: Comma-separated list of color IDs to filter by.
        - name: status_ids
          in: query
          schema:
            type: string
          description: Comma-separated list of condition status IDs to filter by.
        - name: order
          in: query
          schema:
            type: string
            default: relevance
            enum:
              - relevance
              - price_low_to_high
              - price_high_to_low
              - newest_first
          description: Sort order for results.
        - name: seller_country
          in: query
          schema:
            type: string
          description: >-
            Comma-separated ISO 3166-1 alpha-2 country codes (case-insensitive)
            to keep only items whose seller is physically located in one of
            those countries (e.g. "fr" or "fr,be"). Vinted markets federate
            cross-border listings; this filters on the seller's real location,
            which is a different axis from `market`. Note: pagination totals
            stay unfiltered, so a page may return fewer than `per_page` items
            after filtering. Billing: 1 base credit + 1 credit per uncached
            seller looked up (seller country cached 7 days; cache hits are
            free).
      responses:
        '200':
          description: Successful search
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/VintedItemSummary'
                  total_entries:
                    type: integer
                    description: >-
                      Total number of matching items across all pages. Reflects
                      Vinted's unfiltered totals even when seller_country
                      filtering is applied.
                  current_page:
                    type: integer
                    description: Current page number.
                  per_page:
                    type: integer
                    description: Number of items per page.
                  seller_country:
                    type: string
                    nullable: true
                    description: >-
                      Echo of the normalized seller_country filter that was
                      applied (uppercase, comma-separated ISO-2 codes, e.g.
                      "FR,BE"), or null when no filter was requested.
components:
  schemas:
    VintedItemSummary:
      type: object
      properties:
        id:
          type: integer
          description: Item ID.
        title:
          type: string
          description: Item title.
        price:
          type: string
          description: Price in local currency (e.g. "15.00").
        currency:
          type: string
          description: ISO 4217 currency code (e.g. "EUR").
        brand_title:
          type: string
          nullable: true
          description: Brand name.
        size_title:
          type: string
          nullable: true
          description: Size label.
        photo:
          $ref: '#/components/schemas/VintedPhoto'
        url:
          type: string
          description: Full URL to the Vinted listing.
        user:
          $ref: '#/components/schemas/VintedUserSummary'
        favourite_count:
          type: integer
          description: Number of users who favourited this item.
        seller_country_code:
          type: string
          nullable: true
          description: >-
            ISO 3166-1 alpha-2 code of the seller's physical country (e.g.
            "IT"), or null if it could not be resolved.
    VintedPhoto:
      type: object
      properties:
        url:
          type: string
          description: Photo URL.
        width:
          type: integer
          nullable: true
          description: Width in pixels.
        height:
          type: integer
          nullable: true
          description: Height in pixels.
    VintedUserSummary:
      type: object
      properties:
        id:
          type: integer
          description: User ID.
        login:
          type: string
          description: Username.
        photo:
          type: object
          nullable: true
          properties:
            url:
              type: string
        feedback_reputation:
          type: number
          nullable: true
          description: Reputation score between 0 and 1.
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````