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

# Vinted

> What a keyword captures on Vinted, plus the observed price history and market statistics.

## Enabled markets

Nephia enables these Vinted markets:

| Code | Domain |
| - | - |
| `fr` | vinted.fr |
| `de` | vinted.de |
| `uk` | vinted.co.uk |
| `it` | vinted.it |
| `es` | vinted.es |
| `pl` | vinted.pl |
| `nl` | vinted.nl |
| `be` | vinted.be |
| `cz` | vinted.cz |
| `lt` | vinted.lt |
| `pt` | vinted.pt |
| `at` | vinted.at |
| `lu` | vinted.lu |
| `sk` | vinted.sk |
| `dk` | vinted.dk |
| `fi` | vinted.fi |
| `se` | vinted.se |
| `ro` | vinted.ro |
| `hu` | vinted.hu |
| `hr` | vinted.hr |
| `gr` | vinted.gr |
| `us` | vinted.com |
| `au` | vinted.com.au |
| `lv` | vinted.lv |
| `ee` | vinted.ee |

Pass `market` on a Vinted search and on analytics requests. On analytics requests an omitted `market` defaults to **`fr`** (same default as Vinted); on a keyword, `market` is required.

A market outside this allowlist returns `400` with code `VALIDATION`.

## Coverage

A keyword with Vinted enabled polls a catalog search and keeps every listing that matches. `market`, `priceMin` and `priceMax` are criteria of the search itself; the id filters are Vinted's own and go in the search's `overrides.filters` (see [Keywords](/keywords#create)).

| Criterion | Type | Description |
| - | - | - |
| `market` | string | Market code. Must be one of the enabled markets above. |
| `query` | string | Text search. One term only: a catalog search is not a boolean text search, so `terms` and `match` do not apply. |
| `priceMin` | number | Minimum price |
| `priceMax` | number | Maximum price |
| `filters.brand_ids` | list of integers | Brand filter |
| `filters.size_ids` | list of integers | Size filter |
| `filters.catalog_ids` | list of integers | Catalog filter |
| `filters.color_ids` | list of integers | Colour filter |
| `filters.status_ids` | list of integers | Condition filter |

The ids are the numeric ids Vinted uses. Each filter takes a list (`[53, 14]`) or a comma-separated string (`"53, 14"`); both are stored as the same list of integers, and anything that is not a positive integer is refused with **400** `VALIDATION`.

`sort` is not a criterion: polling is always **newest first**, which is what lets a tick tell a new listing from one it has already seen. A `sort` sent on a search is overwritten on every tick.

```bash theme={null}
curl -X POST https://api.nephia.cc/v1/keywords \
  -H "x-api-key: $NEPHIA_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "name": "Levis 501 on Vinted FR",
    "refreshIntervalSeconds": 900,
    "globalCriteria": { "market": "fr", "query": "jean levis 501" },
    "sources": [
      {
        "source": "vinted",
        "enabled": true,
        "searches": [
          {
            "overridesEnabled": true,
            "overrides": {
              "priceMax": 40,
              "filters": { "brand_ids": [10], "status_ids": [2, 3] }
            }
          }
        ]
      }
    ],
    "webhookUrl": "https://example.com/hooks/nephia"
  }'
```

Interval: **15 to 86400** seconds (your plan's floor applies on top, see [Limits](/limits#polling-limits)). At most **50** active Vinted searches per Account. Each tick costs **4 credits**.

## What an event carries

The first tick establishes a silent baseline and emits nothing. Later ticks emit `listing.created`, `listing.price_changed` (with `previousPrice`) and `listing.delisted`, each with the full listing. `webhookUrl` is optional: without it the keyword still records every match, readable through `GET /v1/keywords/{id}/events` in the same shape. See [Keywords](/keywords#events) and [Webhooks](/webhooks#replay).

## Price history & market stats

Nephia records what listings cost as it sees them, and exposes two reads over that
history: our own observations, not a call to Vinted.

`GET /v1/vinted/items/{id}/price-history` returns every point observed for one item,
oldest first:

```json theme={null}
{
  "itemId": "1234567890",
  "market": "fr",
  "history": [
    {
      "observedAt": "2026-08-01T09:12:44.000Z",
      "price": 45,
      "currency": "EUR",
      "status": "Très bon état",
      "favouriteCount": 12,
      "viewCount": 340
    }
  ]
}
```

| Parameter | Type | Description |
| - | - | - |
| `market` | string | Market code, default `fr` |
| `from` | ISO-8601 | Lower bound on `observedAt` |
| `to` | ISO-8601 | Upper bound on `observedAt` |
| `limit` | number | Points to return, default `200`, max `500` |

`GET /v1/vinted/market/stats` returns per-day percentiles over a market, newest first:

```json theme={null}
{
  "market": "fr",
  "from": "2026-07-19T00:00:00.000Z",
  "to": "2026-08-18T00:00:00.000Z",
  "filters": { "brand_id": 53, "catalog_id": null, "size_id": null, "status": null, "currency": null },
  "stats": [
    { "date": "2026-08-18", "currency": "EUR", "count": 412, "p25": 18, "median": 29, "p75": 45, "soldRate": null }
  ]
}
```

| Parameter | Type | Description |
| - | - | - |
| `market` | string | Market code, default `fr` |
| `from` | ISO-8601 | Start of the range, default 30 days ago |
| `to` | ISO-8601 | End of the range, default now |
| `brand_id` | number | Brand filter: the numeric id Vinted uses, as it appears on observed listings |
| `catalog_id` | number | Catalog filter |
| `size_id` | number | Size filter |
| `status` | string | Vinted condition label as observed, e.g. `Très bon état` |
| `currency` | string | Currency code, e.g. `EUR` |

A range may not exceed 365 days. Days are grouped by currency as well as by date, so
percentiles are never averaged across two currencies.

<Warning>
  **These endpoints describe what Nephia has observed, not all of Vinted.** A point
  exists only for an item that appeared in a search Nephia ran: a tick of a Vinted search.
  Coverage grows with usage, and a brand nobody watches has no history. Treat the
  numbers as a sample, not a census.
</Warning>

A point is recorded when an item's price or status changed, or once every 24 hours
while neither did, so consecutive points are movements, not poll ticks. Observations
are kept for **365 days**.

`soldRate` is always `null`: Vinted does not confirm sales, and Nephia does not yet
infer them.


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