Datasets API endpoint
Returns the recorded price-change events for one listing, oldest first. An event is recorded only when a crawl first observes the listing or observes a changed price -- not one entry per crawl pass -- so a listing whose price has never changed since it was first crawled returns a single entry.
/datasets/vehicle-listings/price-history/{id}Path parameters:
id — required, formatted <source>:<source_listing_id> (e.g. carmax:28187774).An event is recorded either when a crawl first observes the listing (its initial price) or observes a price different from the last-known price — not one entry per crawl pass — or, for carsdotcom rows, backfilled from that source's own native price-history log at the pass that first discovered the listing (bounded to a limited number of newly-discovered listings per pass, same as CarMax's accident/owner-count enrichment — see the search endpoint's docs). A listing whose price has never changed since it was first crawled returns a single entry. Returns {id, items[]}, where each item is {id, source, source_listing_id, price, snapshot_date, crawled_at, schema_version}. An id with no recorded history (not yet crawled, or crawled only once at a stable price with the entry not yet indexed) returns an empty items list, not an error.
| Field | Filled in, of 1 checked | Values in the sample |
|---|---|---|
| id | 1 | |
| source | 1 | |
| source_listing_id | 1 | |
| price | 1 | 43,998 |
| snapshot_date | 1 | 2026-09-06 |
| crawled_at | 1 | 2026-09-06 |
| schema_version | 1 |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| id (path) | string | Yes | Vehicle listing id, formatted <source>:<source_listing_id> (e.g. carmax:28187774) | carmax:28187774 | |
| x-api-key (header) | string | Yes | API key required |
curl -X GET "https://api.crawlora.net/api/v1/datasets/vehicle-listings/price-history/carmax%3A28187774" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"id": "carmax:28187774",
"items": [
{
"id": "carmax:28187774:2026-08-20",
"source": "carmax",
"source_listing_id": "28187774",
"price": 46998,
"snapshot_date": "2026-08-20",
"crawled_at": "2026-08-20T00:00:00Z",
"schema_version": 1
},
{
"id": "carmax:28187774:2026-08-27",
"source": "carmax",
"source_listing_id": "28187774",
"price": 45998,
"snapshot_date": "2026-08-27",
"crawled_at": "2026-08-27T00:00:00Z",
"schema_version": 1
}
]
}
}Request schema
No body schema
Response schema
#/definitions/datasets.vehicleListingPriceHistoryResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | datasets.VehicleListingPriceHistoryResponse | No | ||||
| data.id | string | No | ||||
| data.items | array | No | ||||
| data.items[].crawled_at | string | No | ||||
| data.items[].id | string | No | ||||
| data.items[].price | number | No | ||||
| data.items[].schema_version | integer | No | ||||
| data.items[].snapshot_date | string | No | SnapshotDate is the crawl date (YYYY-MM-DD) this price was observed on -- part of the doc id, so re-crawling the same listing twice in one day at a changed price overwrites that day's entry rather than creating a second one for the same date. | |||
| data.items[].source | string | No | ||||
| data.items[].source_listing_id | string | 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/price-history/carmax%3A28187774" \
-H "x-api-key: $CRAWLORA_API_KEY"