Comps

https://swanum.com/comps/docs
Admin
Comps is a REST API that provides tracked sales data, statistics, and sold prices for items on...
Tokens:8,928
Snippets:49
Trust Score:5.1
Update:3 days ago
Show doc for...
Tokens:
Raw
### Example JSON response for GET /vinted/sold

Source: https://swanum.com/comps/docs

A sample JSON response containing statistics, coverage information, and a list of sold items.

```json
{
  "query": {"q": "nike air force 1", "country": "FR", ...},
  "source": "vinted",
  "cached": false,
  "fetched_at": "2026-10-02T09:14:03+00:00",
  "stats": {
    "count": 41, "currency": "EUR",
    "median": 38.0, "mean": 40.12, "p25": 30.0, "p75": 48.0,
    "min": 15.0, "max": 85.0, "outliers_removed": 2,
    "median_days_to_sell": 4.1,
    "sell_through": [
      {"within_days": 1, "listings": 180, "sold": 14, "sold_pct": 8,
       "median_price_sold": 30.0, "median_price_unsold": 42.0},
      {"within_days": 7, "listings": 122, "sold": 31, "sold_pct": 25,
       "median_price_sold": 33.0, "median_price_unsold": 45.0}
    ]
  },
  "coverage": {
    "tracked_listings": 612, "tracking_since": "2026-09-24T22:41:30+00:00",
    "days_tracked": 8, "disappeared_unknown": 37,
    "note": "Sold history is built by tracking listings over time; depth grows daily."
  },
  "items": [{
    "id": "vinted:FR:10124550958",
    "title": "Nike Air Force 1 blanches",
    "price": 40.0, "currency": "EUR",
    "condition": "Très bon état", "condition_normalized": "used",
    "brand": "Nike", "size": "42",
    "listed_at": "2026-09-25T07:48:00+00:00",
    "last_active_at": "2026-09-26T08:03:12+00:00",
    "sold_detected_at": "2026-09-28T08:05:40+00:00",
    "days_to_sell": 3.0,
    "url": "https://www.vinted.fr/items/10124550958-...",
    "image_url": "https://images1.vinted.net/..."
  }]
}
```

--------------------------------

### GET /usage

Source: https://swanum.com/comps/docs

Check API usage and quota. Requires an API key.

```APIDOC
## GET /usage

### Description
Check API usage and quota. Requires an API key.

### Method
GET

### Endpoint
/usage

### Authentication
API key required via X-API-Key header.

### Request Example
```
curl -G https://swanum.com/comps/api/v1/usage -H "X-API-Key: $COMPS_KEY"
```

### Response
Returns usage information.

```

--------------------------------

### GET /usage

Source: https://swanum.com/comps/docs

Returns the current API usage and quota information for the authenticated user.

```APIDOC
## GET /usage

### Description
Returns the current API usage and quota information for the authenticated user.

### Method
GET

### Endpoint
/usage

### Parameters
None

### Response
#### Success Response (200)
- **plan** (string) - Current plan (e.g., `beta`).
- **quota** (integer) - Total quota.
- **used** (integer) - Used requests.
- **remaining** (integer) - Remaining requests.
- **period_start** (string) - Start of the current period.
- **resets_at** (string) - Reset timestamp.

#### Response Example
{
  "plan": "beta",
  "quota": 1000,
  "used": 12,
  "remaining": 988,
  "period_start": "2026-10-01T00:00:00+00:00",
  "resets_at": "2026-11-01T00:00:00+00:00"
}
```

--------------------------------

### Retrieve API usage with GET /usage

Source: https://swanum.com/comps/docs

Returns the current plan, quota limits, and usage statistics for the account.

```json
{"plan": "beta", "quota": 1000, "used": 12, "remaining": 988,
 "period_start": "2026-10-01T00:00:00+00:00", "resets_at": "2026-11-01T00:00:00+00:00"}
```

--------------------------------

### Python API Request Example

Source: https://swanum.com/comps/docs

Retrieves sold item statistics using the requests library with an API key from environment variables.

```python
import os, requests

r = requests.get(
    "https://swanum.com/comps/api/v1/vinted/sold",
    headers={"X-API-Key": os.environ["COMPS_KEY"]},
    params={"q": "levis 501", "country": "DE", "condition": "used"},
    timeout=30,
)
r.raise_for_status()
data = r.json()
print(data["stats"]["median"], data["stats"]["currency"], "from", data["stats"]["count"], "sales")
```

--------------------------------

### curl API Usage Request

Source: https://swanum.com/comps/docs

Example command to check API usage using curl.

```bash
curl -G https://swanum.com/comps/api/v1/usage -H "X-API-Key: $COMPS_KEY"
```

--------------------------------

### PHP API Request Example

Source: https://swanum.com/comps/docs

Retrieves sold item statistics using cURL and json_decode.

```php
$q = http_build_query(["q" => "levis 501", "country" => "DE"]);
$ch = curl_init("https://swanum.com/comps/api/v1/vinted/sold?$q");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["X-API-Key: " . getenv("COMPS_KEY")],
]);
$data = json_decode(curl_exec($ch), true);
echo $data["stats"]["median"] . " " . $data["stats"]["currency"];
```

--------------------------------

### JavaScript API Request Example

Source: https://swanum.com/comps/docs

Fetches sold item data using the Fetch API, suitable for Node 18+ or server-side browser environments.

```javascript
const url = new URL("https://swanum.com/comps/api/v1/vinted/sold");
url.search = new URLSearchParams({ q: "levis 501", country: "DE" });

const res = await fetch(url, { headers: { "X-API-Key": process.env.COMPS_KEY } });
if (!res.ok) throw new Error((await res.json()).error.message);
const { stats, items } = await res.json();
console.log(stats.median, stats.currency, items.length);
```

--------------------------------

### GET /alerts

Source: https://swanum.com/comps/docs

Lists all alerts for the authenticated user, including status and current sales count.

```APIDOC
## GET /alerts

### Description
Lists all alerts for the authenticated user, including status and current sales count.

### Method
GET

### Endpoint
/alerts

### Parameters
None

### Response
#### Success Response (200)
- **alerts** (array) - List of alert objects, each with fields: `id`, `q`, `source`, `market`, `status`, `sales_now`, `notify_at_sales`, `expires_at`, `notified_at`.

#### Response Example
{
  "alerts": [
    {
      "id": 42,
      "q": "dr. martens 1460",
      "source": "vinted",
      "market": "ES",
      "status": "waiting",
      "sales_now": 1,
      "notify_at_sales": 5,
      "expires_at": "...",
      "notified_at": null
    }
  ]
}
```

--------------------------------

### GET /vinted/sold

Source: https://swanum.com/comps/docs

Search for sold Vinted items. Returns statistics and item details. Requires an API key.

```APIDOC
## GET /vinted/sold

### Description
Search for sold Vinted items. Returns statistics and item details. Requires an API key.

### Method
GET

### Endpoint
/vinted/sold

### Parameters
#### Query Parameters
- **q** (string) - Required - Search query, e.g., "levis 501".
- **country** (string) - Optional - Country code, e.g., "DE".
- **condition** (string) - Optional - Condition filter, e.g., "used".

### Request Example
```
GET /vinted/sold?q=levis%20501&country=DE&condition=used
```

### Response
#### Success Response (200)
- **stats** (object) - Contains median, currency, count, and other statistics.
- **items** (array) - List of sold items.

#### Response Example
```
{
  "stats": {
    "median": 25.0,
    "currency": "EUR",
    "count": 100
  },
  "items": []
}
```

```

--------------------------------

### GET /health

Source: https://swanum.com/comps/docs

Health check endpoint that returns per-source status from the monitor. No API key is required and it does not count against your quota.

```APIDOC
## GET /health

### Description
Health check endpoint that returns per-source status from the monitor. No API key is required and it does not count against your quota.

### Method
GET

### Endpoint
/health

### Authentication
None required.

### Response
Returns the same data as the status page.

```

--------------------------------

### GET /vinted/sold

Source: https://swanum.com/comps/docs

Retrieves sold items from Vinted's tracked history. Returns statistics, coverage, and individual sold items based on query parameters.

```APIDOC
## GET /vinted/sold

### Description
Retrieves sold items from Vinted's tracked history. Returns statistics, coverage, and individual sold items based on query parameters.

### Method
GET

### Endpoint
https://swanum.com/comps/api/v1/vinted/sold

### Parameters
#### Query Parameters
- **q** (string, 2-200) - Required - Words matched against item titles (all words must appear; accents, punctuation and plural s don't matter).
- **country** (string: FR DE UK IT ES NL PL) - Optional - Which Vinted site. Prices are in that site's currency (EUR, GBP, PLN). Default: FR.
- **brand** (string) - Optional - Exact brand as Vinted shows it, case-insensitive.
- **size** (string) - Optional - Exact size label, e.g. M, 42.
- **condition** (string: new · used · any) - Optional - new = with or without tags; used = very good / good / satisfactory. Default: any.
- **days** (integer, 1-365) - Optional - Sales detected in the last N days. Default: 90.
- **limit** (integer, 1-240) - Optional - Items returned (stats always use every match). Default: 50.

### Request Example
curl -G https://swanum.com/comps/api/v1/vinted/sold \
  -H "X-API-Key: $COMPS_KEY" \
  --data-urlencode "q=nike air force 1" -d country=FR

### Response
#### Success Response (200)
- **query** (object) - The query parameters used.
- **source** (string) - The source of the data, e.g., "vinted".
- **cached** (boolean) - Whether the response was cached.
- **fetched_at** (string) - Timestamp of when the data was fetched.
- **stats** (object) - Statistics including count, currency, median, mean, p25, p75, min, max, outliers_removed, median_days_to_sell, and sell_through array.
- **coverage** (object) - Coverage details including tracked_listings, tracking_since, days_tracked, disappeared_unknown, and note.
- **items** (array) - List of sold items with id, title, price, currency, condition, condition_normalized, brand, size, listed_at, last_active_at, sold_detected_at, days_to_sell, url, and image_url.

#### Response Example
{
  "query": {"q": "nike air force 1", "country": "FR", ...},
  "source": "vinted",
  "cached": false,
  "fetched_at": "2026-10-02T09:14:03+00:00",
  "stats": {
    "count": 41, "currency": "EUR",
    "median": 38.0, "mean": 40.12, "p25": 30.0, "p75": 48.0,
    "min": 15.0, "max": 85.0, "outliers_removed": 2,
    "median_days_to_sell": 4.1,
    "sell_through": [
      {"within_days": 1, "listings": 180, "sold": 14, "sold_pct": 8,
       "median_price_sold": 30.0, "median_price_unsold": 42.0},
      {"within_days": 7, "listings": 122, "sold": 31, "sold_pct": 25,
       "median_price_sold": 33.0, "median_price_unsold": 45.0}
    ]
  },
  "coverage": {
    "tracked_listings": 612, "tracking_since": "2026-09-24T22:41:30+00:00",
    "days_tracked": 8, "disappeared_unknown": 37,
    "note": "Sold history is built by tracking listings over time; depth grows daily."
  },
  "items": [{
    "id": "vinted:FR:10124550958",
    "title": "Nike Air Force 1 blanches",
    "price": 40.0, "currency": "EUR",
    "condition": "Très bon état", "condition_normalized": "used",
    "brand": "Nike", "size": "42",
    "listed_at": "2026-09-25T07:48:00+00:00",
    "last_active_at": "2026-09-26T08:03:12+00:00",
    "sold_detected_at": "2026-09-28T08:05:40+00:00",
    "days_to_sell": 3.0,
    "url": "https://www.vinted.fr/items/10124550958-...",
    "image_url": "https://images1.vinted.net/..."
  }]
}
```

--------------------------------

### GET /ebay/sold

Source: https://swanum.com/comps/docs

Retrieves sold listings from eBay US with optional filters. Returns a match object and sales statistics. Other marketplaces return 503 source_unavailable.

```APIDOC
## GET /ebay/sold

### Description
Retrieves sold listings from eBay US with optional filters. Returns a match object and sales statistics. Other marketplaces return 503 source_unavailable.

### Method
GET

### Endpoint
/ebay/sold

### Parameters
#### Query Parameters
- **q** (string, 2–200) - Required - Search text.
- **marketplace** (string) - Optional - US (default), UK, DE, CA, AU, FR, IT, ES.
- **condition** (string) - Optional - `working` (default), `new`, `used`, `refurbished`, `for_parts`, `any`.
- **min_price**, **max_price** (number) - Optional - Price range in the marketplace currency.
- **days** (integer, 1–90) - Optional - Lookback window (default 90).
- **category_id** (integer) - Optional - eBay leaf category ID.
- **exclude** (comma-separated) - Optional - Drop items whose title contains any of these words.
- **limit** (integer, 1–240) - Optional - Number of results (default 50).
- **sort** (string) - Optional - `date_desc` (default), `price_asc`, `price_desc`.
- **include_best_offer** (bool) - Optional - Include accepted Best Offer sales in stats (default false).
- **fresh** (bool) - Optional - Bypass the 15-minute cache (default false).

### Response
#### Success Response (200)
- **match** (object) - Contains `mode` (`exact` or `broad`) and `note`.
- **sales** (array) - List of sold items with fields: `price`, `listed_at`, `last_active_at`, `sold_detected_at`, `days_to_sell`, `category_id`, `category`, `item_specifics`.
- **stats** (object) - Contains `median_days_to_sell`, `sell_through`, `median_price_sold`, `median_price_unsold`.
- **notify** (object) - Present when sales < 5.

#### Error Response (503)
- **source_unavailable** - Returned when the marketplace is not tracked yet.

#### Response Example
{
  "match": {"mode": "exact"},
  "sales": [
    {
      "price": 120.0,
      "listed_at": "2026-09-01T10:00:00Z",
      "last_active_at": "2026-09-10T10:00:00Z",
      "sold_detected_at": "2026-09-12T10:00:00Z",
      "days_to_sell": 11,
      "category_id": 139971,
      "category": "Video Game Consoles",
      "item_specifics": {"Model": "PS5"}
    }
  ],
  "stats": {
    "median_days_to_sell": 5,
    "sell_through": [0.1, 0.2, 0.3, 0.4, 0.5],
    "median_price_sold": 100.0,
    "median_price_unsold": 90.0
  }
}
```

--------------------------------

### GET /vinted/sold

Source: https://swanum.com/comps/docs

Retrieves sold listings from Vinted with optional filters. Returns a match object indicating exact or broad matching, and includes sales statistics.

```APIDOC
## GET /vinted/sold

### Description
Retrieves sold listings from Vinted with optional filters. Returns a match object indicating exact or broad matching, and includes sales statistics.

### Method
GET

### Endpoint
/vinted/sold

### Parameters
#### Query Parameters
- **q** (string, 2–200) - Required - Search text.
- **source** (string) - Required - Must be `vinted`.
- **market** (string) - Required - Vinted country: FR DE UK IT ES NL PL.
- **condition** (string) - Optional - `working` (default) or `any`. `working` excludes for-parts listings.
- **min_price**, **max_price** (number) - Optional - Price range in the marketplace currency.
- **days** (integer, 1–90) - Optional - Lookback window for sales (default 90).
- **category_id** (integer) - Optional - Vinted category ID to filter by.
- **exclude** (comma-separated) - Optional - Drop items whose title contains any of these words.
- **limit** (integer, 1–240) - Optional - Number of results (default 50).
- **sort** (string) - Optional - `date_desc` (default), `price_asc`, or `price_desc`.
- **include_best_offer** (bool) - Optional - Include accepted Best Offer sales in stats (default false).
- **fresh** (bool) - Optional - Bypass the 15-minute cache (default false).

### Response
#### Success Response (200)
- **match** (object) - Contains `mode` (`exact` or `broad`) and `note` (explains broad matching).
- **sales** (array) - List of sold items with fields: `price`, `listed_at`, `last_active_at`, `sold_detected_at`, `days_to_sell`, `category_id`, `category`, `item_specifics`.
- **stats** (object) - Contains `median_days_to_sell`, `sell_through` (array of shares at 1, 3, 7, 14, 30 days), `median_price_sold`, `median_price_unsold`.
- **notify** (object) - Present when sales < 5, contains the exact request to create an alert.

#### Response Example
{
  "match": {"mode": "exact"},
  "sales": [
    {
      "price": 45.0,
      "listed_at": "2026-09-01T10:00:00Z",
      "last_active_at": "2026-09-10T10:00:00Z",
      "sold_detected_at": "2026-09-12T10:00:00Z",
      "days_to_sell": 11,
      "category_id": 123,
      "category": "Shoes",
      "item_specifics": {"Model": "1460"}
    }
  ],
  "stats": {
    "median_days_to_sell": 5,
    "sell_through": [0.1, 0.2, 0.3, 0.4, 0.5],
    "median_price_sold": 40.0,
    "median_price_unsold": 35.0
  }
}
```

--------------------------------

### Create an alert with POST /alerts

Source: https://swanum.com/comps/docs

Creates a new alert for a search query. The request includes the query, source, and market, and returns the alert status and notification threshold.

```bash
curl -X POST "https://swanum.com/comps/api/v1/alerts" -H "X-API-Key: $COMPS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "Dr. Martens 1460", "source": "vinted", "market": "ES"}'
→ 201 {"id": 42, "q": "dr. martens 1460", "source": "vinted", "market": "ES", "email": "you@example.com",
       "status": "waiting", "sales_now": 1, "notify_at_sales": 5, "expires_at": "…", "notified_at": null}
```

--------------------------------

### Make a Vinted sold items request

Source: https://swanum.com/comps/docs

Use curl to query the Vinted sold items endpoint with an API key and search parameters.

```bash
export COMPS_KEY="sc_live_..."
curl -G https://swanum.com/comps/api/v1/vinted/sold \
  -H "X-API-Key: $COMPS_KEY" \
  --data-urlencode "q=nike air force 1" -d country=FR
```

--------------------------------

### POST /alerts

Source: https://swanum.com/comps/docs

Creates a new alert that notifies the user when a search reaches a specified number of sales. Returns the created alert object.

```APIDOC
## POST /alerts

### Description
Creates a new alert that notifies the user when a search reaches a specified number of sales. Returns the created alert object.

### Method
POST

### Endpoint
/alerts

### Parameters
#### Request Body
- **q** (string) - Required - Search text.
- **source** (string) - Required - `vinted` or `ebay`.
- **market** (string) - Required - Vinted country (FR DE UK IT ES NL PL) or eBay marketplace (US).

### Request Example
{
  "q": "Dr. Martens 1460",
  "source": "vinted",
  "market": "ES"
}

### Response
#### Success Response (201)
- **id** (integer) - Alert ID.
- **q** (string) - Normalized search text.
- **source** (string) - Source marketplace.
- **market** (string) - Marketplace country.
- **email** (string) - User email.
- **status** (string) - `waiting`, `ready`, `notified`, or `expired`.
- **sales_now** (integer) - Current number of sales.
- **notify_at_sales** (integer) - Threshold for notification.
- **expires_at** (string) - Expiration timestamp.
- **notified_at** (string or null) - Notification timestamp.

#### Response Example
{
  "id": 42,
  "q": "dr. martens 1460",
  "source": "vinted",
  "market": "ES",
  "email": "you@example.com",
  "status": "waiting",
  "sales_now": 1,
  "notify_at_sales": 5,
  "expires_at": "...",
  "notified_at": null
}
```

--------------------------------

### API Error Response Format

Source: https://swanum.com/comps/docs

The standard JSON structure returned for all API errors, including a specific error code and documentation link.

```json
{"error": {"code": "quota_exceeded", "message": "...", "docs": "https://swanum.com/comps/docs#error-quota_exceeded"}}
```

--------------------------------

### DELETE /alerts/{id}

Source: https://swanum.com/comps/docs

Deletes an alert by its ID.

```APIDOC
## DELETE /alerts/{id}

### Description
Deletes an alert by its ID.

### Method
DELETE

### Endpoint
/alerts/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The alert ID.

### Response
#### Success Response (200)
No content.
```
Tokens:
Raw