Datasets API endpoint
Searches the crawled used-vehicle listings index. source enum: `carmax`, `autotrader`, `carsdotcom`. CarMax's own national inventory is fully enumerable (re-crawled on a standing schedule); Autotrader/Cars.com coverage is a best-effort zip-code sweep, not exhaustive, and their rows approximate city/state from the searched area rather than the seller's exact location. seller_type enum: `retailer`, `dealer`, `private` (not populated for every row -- see the dataset markdown). Sort enum: `relevance`, `recently_updated`, `newly_listed`, `price_asc`, `price_desc`, `mileage_asc`, `mileage_desc`, `year_desc`, `year_asc`. Billing: this search costs 1 credit per record returned, with a minimum of 2 (an empty result costs 2, a full page of 100 costs 100).
/datasets/vehicle-listings/searchSearches the crawled used-vehicle listings index. carmax rows come from CarMax's own national inventory — a single retailer's own catalog, fully enumerable and re-crawled on a standing schedule, not a third-party dealer aggregator. autotrader/carsdotcom rows come from a best-effort zip-code sweep of those two marketplaces (neither exposes a national query) — coverage is broad but not exhaustive, and their city/state fields approximate the searched area rather than the seller's exact location.
Query parameters:
q — full-text query over make, model and trim (max 256 chars).source — exact source marketplace filter: carmax, autotrader, carsdotcom.make, model, trim, body_style, transmission, drive_type, fuel_type, state, vin, run_id — exact-match filters (max 128 chars, state max 8).seller_type — one of retailer, dealer, private. Every CarMax row is retailer. Cars.com rows infer dealer/private from whether a dealer name is present. Autotrader rows leave this blank (not available without a per-listing detail fetch, which this crawl skips to keep request volume proportional to coverage).is_price_reduced — boolean filter for listings currently marked down from a previous price.min_year, max_year — model year range.min_price, max_price — price range in US dollars.max_mileage — maximum odometer mileage.sort — one of relevance, recently_updated, newly_listed, price_asc, price_desc, mileage_asc, mileage_desc, year_desc, year_asc. Defaults to relevance with q, otherwise recently_updated.page (default 1), page_size (default 20, max 100). page * page_size must be ≤ 10000.Each row's id is <source>:<source_listing_id> (e.g. carmax:28187774) — pass it to the item and price-history endpoints. vin is present on a best-effort basis and not guaranteed on every listing. first_seen_at is set only on the crawl pass that first observed a listing, so it doubles as a days-on-market signal; last_seen_at updates on every re-crawl. city is only populated for CarMax rows (Autotrader/Cars.com search results don't carry an exact seller city); state is populated for every source, approximated from the searched metro area for Autotrader/Cars.com. accident_count/owner_count (currently CarMax-only) are only present when the listing was one of a bounded number enriched with a vehicle-history detail fetch on the pass that discovered it — absent (not 0) means not yet enriched, while 0 is a real "no accidents on record"/"one owner" claim; most rows, including most CarMax rows, will not have these fields populated. Returns {dataset, items[], page, page_size, total, sort}. An empty or not-yet-populated dataset returns an empty items list, not an error.
1 credit per record returned, minimum 2. A search that returns 20 records costs 20 credits, a full page of 100 costs 100, and an empty or one-record result costs 2. You are charged for what comes back, not for the page_size you ask for, but your balance must cover the requested page_size for the call to be accepted. The response header x-credit-cost shows what a call was charged.
| Field | Filled in, of 20 checked | Values in the sample |
|---|---|---|
| id | 20 | |
| source | 20 | |
| source_listing_id | 20 | |
| vin | 20 | |
| year | 20 | 2,014 to 2,025, median 2,022 |
| make | 20 | |
| model | 20 | |
| trim | 20 | |
| body_style | 20 | |
| mileage | 20 | 15,062 to 127,314, median 42,533 |
| exterior_color | 20 | |
| interior_color | 20 | |
| engine | 20 | |
| transmission | 20 | |
| drive_type | 20 | |
| fuel_type | 20 | |
| price | 20 | 21,998 |
| is_price_reduced | 20 | true in 0 of 20 |
| seller_type | 20 | |
| seller_name | 20 | |
| city | 20 | |
| state | 20 | |
| image_url | 20 | img2.carmax.com |
| url | 20 | carmax.com |
| first_seen_at | 20 | 2026-09-18 to 2026-10-13 |
| last_seen_at | 20 | 2026-10-13 |
| run_id | 20 | |
| crawled_at | 20 | 2026-10-13 |
| schema_version | 20 | |
| accident_count | 4 | 0 to 1, median 0 |
| owner_count | 4 | 1 to 2, median 1 |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| q | string | No | Full-text query over make, model and trim, max 256 characters | ||
| source | string | No | Exact source marketplace filter: carmax, autotrader, carsdotcom Allowed values: carmax, autotrader, carsdotcom. | ||
| make | string | No | Exact make filter (e.g. Honda, Toyota), max 128 characters | ||
| model | string | No | Exact model filter (e.g. Civic), max 128 characters | ||
| trim | string | No | Exact trim filter, max 128 characters | ||
| body_style | string | No | Exact body style filter (e.g. Sedan, SUV), max 128 characters | ||
| transmission | string | No | Exact transmission filter, max 128 characters | ||
| drive_type | string | No | Exact drivetrain filter, max 128 characters | ||
| fuel_type | string | No | Exact fuel type filter (e.g. Gas, Hybrid, Electric), max 128 characters | ||
| seller_type | string | No | Exact seller type filter: retailer, dealer, private Allowed values: retailer, dealer, private. | ||
| state | string | No | Exact US state abbreviation filter (e.g. CA), max 8 characters | ||
| vin | string | No | Exact VIN filter. Best-effort: not guaranteed on every listing | ||
| run_id | string | No | Exact crawl run-id filter, max 128 characters | ||
| is_price_reduced | boolean | No | Filter for listings currently marked down from a previous price | ||
| min_year | integer | No | Minimum model year | ||
| max_year | integer | No | Maximum model year | ||
| min_price | number | No | Minimum price in US dollars | ||
| max_price | number | No | Maximum price in US dollars | ||
| max_mileage | integer | No | Maximum odometer mileage | ||
| sort | string | No | Sort enum: relevance, recently_updated, newly_listed, price_asc, price_desc, mileage_asc, mileage_desc, year_desc, year_asc Allowed values: relevance, recently_updated, newly_listed, price_asc, price_desc, mileage_asc, mileage_desc, year_desc, year_asc. | ||
| page | integer | No | 1 | Page number, defaults to 1 | |
| page_size | integer | No | 20 and maxes at 100 | Page size, defaults to 20 and maxes at 100; page * page_size must be <= 10000 | |
| x-api-key (header) | string | Yes | API key required |
curl -X GET "https://api.crawlora.net/api/v1/datasets/vehicle-listings/search?q=coffee&source=carmax&seller_type=retailer&is_price_reduced=true&sort=relevance&page=1" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"dataset": "vehicle-listings",
"items": [
{
"id": "carmax:28187774",
"source": "carmax",
"source_listing_id": "28187774",
"vin": "1FMJK1K89REA27006",
"year": 2024,
"make": "Ford",
"model": "Expedition Max",
"trim": "Limited",
"body_style": "4D Sport Utility",
"mileage": 41406,
"exterior_color": "Black",
"transmission": "Automatic",
"drive_type": "Rear Wheel Drive",
"fuel_type": "Gas",
"price": 45998,
"is_price_reduced": false,
"seller_type": "retailer",
"seller_name": "Canoga Park",
"city": "Los Angeles",
"state": "CA",
"url": "https://www.carmax.com/car/28187774",
"accident_count": 0,
"owner_count": 1,
"first_seen_at": "2026-08-20T00:00:00Z",
"last_seen_at": "2026-08-20T00:00:00Z",
"schema_version": 1
}
],
"page": 1,
"page_size": 20,
"total": 1,
"sort": "recently_updated"
}
}Request schema
No body schema
Response schema
#/definitions/datasets.vehicleListingsSearchResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | datasets.VehicleListingSearchResponse | No | ||||
| data.dataset | string | No | ||||
| data.items | array | No | VehicleListingRecord record, 34 fields: accident_count, body_style, city, crawled_at, drive_type, engine, exterior_color, first_seen_at, fuel_type, id, image_url, interior_color and 22 more. Described under Get a vehicle listing from dataset API. | |||
| data.page | integer | No | ||||
| data.page_size | integer | No | ||||
| data.sort | string | No | ||||
| data.total | integer | No | ||||
| msg | string | No | OK |
| Status | Description | Schema |
|---|---|---|
| 400 | Bad Request | #/definitions/app.Response |
| 429 | Too Many Requests | #/definitions/app.Response |
| 500 | Internal Server Error | #/definitions/app.Response |
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X GET "https://api.crawlora.net/api/v1/datasets/vehicle-listings/search?q=coffee&source=carmax&seller_type=retailer&is_price_reduced=true&sort=relevance&page=1" \
-H "x-api-key: $CRAWLORA_API_KEY"