# Cars & Bids Auction Search API Documentation

<p><strong>Cars & Bids Auction Search API Documentation</strong> Search Cars & Bids enthusiast car auctions: live, closed (past results) and new (upcoming). Filter by free text, make, model, model year, transmission and body style, and sort by ending soon, newest, lowest mileage, lowest price or highest price. Each auction carries the id, title, subtitle, url, main photo, location, transmission, mileage in miles, reserve flag, seller, status (live, sold, reserve_not_met and others), current bid or sale amount in USD and the end time as ISO 8601 UTC. Page with limit (1 to 100) and offset. Read has_more and next_offset for the next page. A valid search without results is a successful empty response.</p>

- **Documentation:** [https://scrappa.co/docs/carsandbids-api/carsandbids_search](https://scrappa.co/docs/carsandbids-api/carsandbids_search)
- **API group:** Cars & Bids API
- **Endpoint:** `GET https://scrappa.co/api/carsandbids/search`

## 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 |
| --- | --- | --- | --- |
| `status` | string | No | Which auctions to list: live (default), closed or new. New lists upcoming auctions that have no bids yet. |
| `limit` | integer | No | Auctions per page, 1 to 100. Defaults to 20. |
| `offset` | integer | No | Number of auctions to skip. Use next_offset from the previous response. Defaults to 0. |
| `search` | string | No | Free text, up to 100 characters, e.g. e39 m5. |
| `make_slug` | string | No | Make slug, lowercase, e.g. lotus. Required when model_slug is set. |
| `model_slug` | string | No | Model slug of the make, lowercase, e.g. emira. An unknown model returns a 422. |
| `start_year` | integer | No | Earliest model year, 1900 up to next year. |
| `end_year` | integer | No | Latest model year. Must not be before start_year. |
| `sort` | string | No | ending_soon (default), newest, lowest_mileage, lowest_price or highest_price. The price sorts need status=closed. |
| `transmission` | string | No | automatic or manual. |
| `body_style` | string | No | coupe, convertible, hatchback, sedan, suv, truck, van or wagon. |

## Example response

```json
{
    "data": {
        "count": 2,
        "total": 267,
        "auctions": [
            {
                "id": "36Y8275B",
                "url": "https://carsandbids.com/auctions/36Y8275B",
                "title": "2002 BMW Z8",
                "seller": "switchcars",
                "status": "live",
                "mileage": 41700,
                "location": "Twinsburg, OH 44087",
                "subtitle": "6-Speed Manual, S62 V8 Power, Sport Red Interior",
                "image_url": "https://media.carsandbids.com/8e6341e27a680ffab7d98e42bef83b0dd1b0fb94/photos/exterior/364n7vwZ-Trc6pLr/edit/LOoti.jpg?t=179039576808",
                "no_reserve": false,
                "auction_end": "2026-10-15T17:30:00Z",
                "current_bid": 122500,
                "transmission": "Manual",
                "has_inspection": false
            },
            {
                "id": "K1lbE5pz",
                "url": "https://carsandbids.com/auctions/K1lbE5pz",
                "title": "2001 Audi RS4 Avant",
                "seller": "MMST",
                "status": "live",
                "mileage": 30800,
                "location": "Winter Garden, FL 34787",
                "subtitle": "31k Miles, 6-Speed Manual, Twin-Turbo V6, Unmodified, U.S. Title",
                "image_url": "https://media.carsandbids.com/9004500a220bf3a3d455d15ee052cf8c332606f8/photos/rj0DPDLx-5pipKNGP1t/edit/-eJ9N.jpg?t=179130589228",
                "no_reserve": false,
                "auction_end": "2026-10-15T17:33:00Z",
                "current_bid": 74500,
                "transmission": "Manual",
                "has_inspection": false
            }
        ],
        "has_more": true,
        "next_offset": 2
    },
    "meta": {
        "billable": true,
        "endpoint_family": "auction_search"
    },
    "success": true
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | A parameter is missing or invalid. No upstream request is made and the 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)