# Cars & Bids Auction State API Documentation

<p><strong>Cars & Bids Auction State API Documentation</strong> Poll the live state of one Cars & Bids auction by id: status, end time as ISO 8601 UTC, current bid in USD, high bidder, number of bids, comments, questions and watchers. A small, fast response for tracking an auction until it ends. Closed auctions return their final state. The counters are real counts, so 0 means none yet.</p>

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

## 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 |
| --- | --- | --- | --- |
| `id` | string | Yes | The 8 character auction id from the search endpoint or the auction URL, e.g. KVQ8JYAP. |

## Example response

```json
{
    "data": {
        "id": "KVQ8JYAP",
        "url": "https://carsandbids.com/auctions/KVQ8JYAP",
        "bids": 18,
        "status": "reserve_not_met",
        "watchers": 918,
        "questions": 0,
        "auction_end": "2026-10-14T19:57:00Z",
        "current_bid": 83333,
        "high_bidder": "r32fan",
        "comments_count": 28
    },
    "meta": {
        "billable": true,
        "endpoint_family": "auction_state"
    },
    "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. |
| 404 | Auction Not Found | No Cars & Bids auction exists for this id. This response is not billable and is not retried. |
| 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)