# Ricardo Category Listings API Documentation

<p><strong>Ricardo Category Listings API Documentation</strong> List Ricardo.ch listings of one category, with the same result fields, filters and pagination as the search endpoint. Leaf and child categories give the best results; find category ids with the categories endpoint. A valid category without listings is a successful response with an empty results list.</p>

- **Documentation:** [https://scrappa.co/docs/ricardo-api/ricardo_category](https://scrappa.co/docs/ricardo-api/ricardo_category)
- **API group:** Ricardo API
- **Endpoint:** `GET https://scrappa.co/api/ricardo/category`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `category_id` | string | Yes | Ricardo category number, e.g. 82249 for Velos. Leaf and child categories give the best results; use the categories endpoint to find ids. |
| `page` | integer | No | 1-based page number, 1 to 50. Defaults to 1. Ranking shifts between calls, so pages can overlap; ids are unique inside one page. |
| `limit` | integer | No | Results per page, 1 to 100. Defaults to 20. |
| `auction_only` | boolean | No | Set true to return pure auctions only. Defaults to false. |
| `price_min` | integer | No | Minimum price in whole CHF, 0 or higher. |
| `price_max` | integer | No | Maximum price in whole CHF. Must be at least price_min. |
| `language` | string | No | Language of labels and the listing url: de or fr. Defaults to de. |

## Example response

```json
{
    "data": {
        "page": 1,
        "limit": 3,
        "total": 15443,
        "results": [
            {
                "id": "1327275878",
                "url": "https://www.ricardo.ch/de/a/1327275878/",
                "city": "Wauwil",
                "title": "Pivot Firebird Carbon 27.5 | Fox 38 180 mm - Gr\u00f6sse M",
                "currency": "CHF",
                "end_date": "2026-11-16T19:51:00Z",
                "position": 1,
                "zip_code": "6242",
                "condition": "acceptable",
                "image_url": "https://img.ricardostatic.ch/images/d0bd6c59-a24c-4e62-b0c5-874622ec316f/t_450/pivot-firebird-carbon-275-fox-38-180-mm-groesse-m",
                "seller_id": "200095338",
                "created_at": "2026-08-18T20:28:00Z",
                "offer_type": "fixed_price",
                "category_id": "82249",
                "buy_now_price": 2800
            },
            {
                "id": "1331859138",
                "url": "https://www.ricardo.ch/de/a/1331859138/",
                "city": "Kyburg",
                "title": "Mtb Fully SCOTT made in USA ab Service",
                "currency": "CHF",
                "end_date": "2026-10-15T20:17:00Z",
                "position": 2,
                "zip_code": "8314",
                "condition": "acceptable",
                "image_url": "https://img.ricardostatic.ch/images/07ca7e25-beb1-4497-b245-006a87522ad9/t_450/mtb-fully-scott-made-in-usa-ab-service",
                "seller_id": "409290340",
                "created_at": "2026-10-08T20:36:00Z",
                "offer_type": "auction_with_buynow",
                "category_id": "82249",
                "next_min_bid": 240,
                "buy_now_price": 280
            }
        ],
        "has_more": true,
        "category_id": "82249"
    },
    "meta": {
        "billable": true,
        "endpoint_family": "category"
    },
    "success": true
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | The category_id is missing or not a category number, or the page, limit, price range or language is out of range. This response is not billable. |
| 503 | Invalid Source Response | Ricardo answered with a response Scrappa could not read. This response is not billable. |
| 503 | Service Unavailable | The upstream service is temporarily unavailable. Please retry shortly. |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)