---
title: "Get Classifieds"
description: "Search collector car classifieds with asking prices, source links, vehicle specifications, sale status, and freshness timestamps."
url: "https://oldcarsdata.com/docs/classifieds"
dateModified: "2026-11-18"
type: "api-docs"
---

# Get Classifieds

Read classified listings from the published database. Build inventory search, dealer feeds, watchlists, or a local copy of listing history.

See [classifieds sources](/docs/sources#classifieds-sources) for every available dealer and marketplace and its exact `source` filter key.

**GET** `https://api.oldcarsdata.com/classifieds`

## Authentication and usage

Send the same API key you use for the other REST endpoints:

```bash
curl "https://api.oldcarsdata.com/classifieds?make=Porsche&currency=USD&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Each successful REST request or MCP call consumes one query from your existing monthly allowance. Validation errors, authentication errors, rate limit responses, and failed queries do not consume a query. The existing limit of 250 requests per minute applies. Starter accounts can retrieve up to 20 results per cursor traversal; paid accounts can continue through every matching listing.

## MCP access

Connect your AI client to the [MCP server](/docs/mcp), then call `search_classifieds`. It accepts every parameter in the table below with the same defaults and validation as REST. Supply integers as JSON numbers. Results include both structured output and matching JSON text with the same `data` and `meta` fields as REST.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_classifieds",
    "arguments": {
      "make": "Porsche",
      "currency": "USD",
      "status": "active",
      "limit": 10
    }
  }
}
```

Use `status: "sold"` for retained sold history, or `status: "all"` with `updated_since` for a complete stored change feed. Pass `meta.next_cursor` as `cursor` with the same filters and direction. REST and MCP classifieds cursors work across both interfaces, and the Starter traversal limit applies across them.

## Default behavior

Requests return active listings eligible for current inventory, ordered by `updated_at` descending, then `id` descending. Missing update times sort last. There is no auction ending-time requirement.

`status` describes the listing: `active`, `sold`, `withdrawn`, `gone`, or `unknown`. A confirmed missing source page (HTTP 404 or 410) changes a previously active or unknown listing to `gone`. This does not establish whether the car sold. Confirmed sold and withdrawn outcomes remain intact when their pages disappear. Temporary access errors and parsing failures never imply `gone`. An active status does not guarantee that the seller still has the car.

Use `status=sold` to search retained sold history, including listings whose source pages disappeared. The `sold`, `withdrawn`, and `unknown` filters include retained listings regardless of page access. Use `status=all` to include every stored listing, including active listings no longer eligible for current inventory.

Use `status=gone` to retrieve missing adverts. A newer successful capture can restore the listing to active. When syncing a local inventory, request `status=all` so a transition to `gone` removes the advert from your active inventory without deleting its price history.

Use `last_seen_at` to assess freshness, `changed_since` to sync listing facts, and `updated_since` to include routine freshness updates. Source checking details stay internal.

## Freshness and capture times

Each classifieds source has an independent hourly schedule. We monitor `last_seen_at` for each listing eligible for active inventory against a target of six hours. Scheduling, scan duration, source errors, and backlogs can delay checks. This is a monitoring target, not a guarantee that every listing receives a full detail capture each hour or meets the target at all times.

The response keeps four clocks separate:

- `last_seen_at` is the capture time of the latest evidence that the listing was present at its source. A verified native inventory page showing a listing for sale can provide this evidence.
- `last_observed_at` is the latest full listing detail capture. Presence checks alone do not advance this timestamp or the observation dates in `asking_price_history`.
- `updated_at` records stored updates, including routine presence and detail checks. It controls `updated_since` and the default cursor order.
- `changed_at` orders published changes to listing facts: price, status, specifications, financing, price history, seller details, location, canonical matches, and image URLs. Routine freshness checks, unchanged detail captures, price-observation timestamps, and internal checking workflow do not advance it. Use `changed_since` to retrieve these changes in `changed_at, id` order.

We publish verified presence evidence as each native inventory page is processed, so `last_seen_at` can advance before the full source scan or detail refresh finishes. Generic sitemap membership alone does not establish active presence. Evidence retains its original capture time.

`active` has no automatic expiry after six hours in REST or MCP. If your application requires listings seen within a strict window, apply that cutoff to `last_seen_at` in your application and treat missing timestamps as unknown. A recent presence check does not establish that prices or other listing details were captured again; use `last_observed_at` and the dated price observations for those facts. Older presence evidence alone does not establish `gone`, sold, or withdrawn.

## Request parameters

Every parameter is optional. Supply each parameter once. Unknown parameters, repeated parameters, and blank values return HTTP 400. All filters are combined with AND.

| Parameter | Type | Behavior |
| --- | --- | --- |
| `make`, `model` | string | Exact canonical `ocd_make_name` and `ocd_model_name`. Listings without a canonical match can still be found by source labels. |
| `listing_make` | string | Exact source make label. |
| `listing_model` | string | Exact source model label after trimming and lowercasing. |
| `vin` | string | Exact stored VIN. Separate listings for the same VIN retain separate IDs. |
| `source` | string | Exact source key, such as `streetside` or `classiccars`. See the [full classifieds source list](/docs/sources#classifieds-sources). |
| `seller_type` | string | Exact source seller type, such as `dealer`. |
| `engine`, `transmission`, `body_style`, `drivetrain` | string | Exact source specification after trimming and lowercasing. No inferred categories or substring matching. `manual` does not match `6-speed manual`. |
| `year_min`, `year_max` | integer | Inclusive model-year bounds, from 1 to 9999. The minimum cannot exceed the maximum. |
| `price_min`, `price_max` | integer | Inclusive **current asking price** bounds, from 0 to 2147483647. Listings without a current asking price do not match. The minimum cannot exceed the maximum. |
| `currency` | string | Three-letter currency code, normalized to uppercase. Prices remain in their source currency; no currency conversion is performed. Pair this with price filters to compare like amounts. |
| `country_code` | string | Two-letter country code, normalized to uppercase. |
| `state` | string | Exact stored state or region label. |
| `keyword` | string | Case-insensitive literal substring in the title. `%` and `_` are literal characters. |
| `status` | enum | `active` (default) selects current inventory. `gone` selects confirmed missing adverts with unconfirmed sale outcomes. `sold`, `withdrawn`, and `unknown` select retained listing states. `all` includes every stored listing. |
| `updated_since` | date-time | Inclusive `updated_at` lower bound. Requires ISO 8601 with a timezone offset, such as `2026-11-15T00:00:00Z`. |
| `changed_since` | date-time | Inclusive `changed_at` lower bound for changes to listing facts. Routine freshness checks are excluded. Requires ISO 8601 with a timezone offset. Selects `changed_at, id` order. Use `status=all` to include every sale state. |
| `last_seen_before` | date-time | Returns listings whose `last_seen_at` is strictly before this ISO 8601 cutoff with a timezone offset. Equal and unknown timestamps are excluded. Age alone does not imply `gone`, sold, or withdrawn. |
| `direction` | enum | `desc` (default) for newest first, or `asc` for oldest first. Orders by `updated_at, id`, or `changed_at, id` when `changed_since` is supplied. Missing times sort last. |
| `limit` | integer | Results per request: 1–100, default 50. |
| `cursor` | string | Opaque `meta.next_cursor` from the preceding response. Keep all filters and direction unchanged. You may change `limit`. |

Text filters are trimmed and limited to 256 UTF-8 bytes. Control characters and invalid UTF-8 are rejected. Native specification values preserve their original spelling in responses. Other text matches are case-sensitive unless stated above.

## Prices and source evidence

The response keeps each price's meaning:

| Field | Meaning |
| --- | --- |
| `asking_price` | Current source asking price, when disclosed. |
| `sold_price` | A confirmed transaction amount when captured. A sold status alone does not establish a transaction amount. |
| `last_asking_price` | Most recently observed total asking price. It remains available after the price is removed or the listing sells. |
| `last_asking_price_observed_at` | When that asking price was observed. |
| `asking_price_history` | First observed asking price and later changes, oldest first. Each entry contains `price` and `observed_at`, in the listing's `currency`. |
| `financing` | Advertised monthly quote: `monthly_payment`, plus `down_payment_percent` and `term_months` when stated. `null` when no single monthly quote was captured. |
| `asking_price_negotiable` | Whether the source says its asking price is negotiable, when known. |
| `currency` | Currency of the recorded amounts. |

Missing prices and dates remain `null`. An undisclosed sold price is never replaced with the last asking price. Price filters use `asking_price` only, including when searching history.

`asking_price_history` records changes to the total asking price. Repeated checks at the same price and changes to monthly payments do not add entries. An empty history is `[]`. Older listings start with their retained price observation; earlier prices are not reconstructed or inferred. Each timestamp records when we observed a price, rather than the exact time the seller changed it.

`financing.monthly_payment` is separate from the total purchase price and preserves fractional currency amounts. It is a source-advertised financing quote, never calculated from `asking_price`. The listing's `currency` applies to both. Missing down payment or term details remain `null`; other lender conditions may apply at the source.

For example, the purchase price and monthly quote remain separate when a listing drops from $210,495 to $200,495:

```json
{
  "asking_price": 200495,
  "last_asking_price": 200495,
  "asking_price_history": [
    { "price": 210495, "observed_at": "2026-11-14T06:41:44Z" },
    { "price": 200495, "observed_at": "2026-11-15T18:03:10Z" }
  ],
  "financing": {
    "monthly_payment": 1544.37,
    "down_payment_percent": 20,
    "term_months": 240
  },
  "currency": "USD"
}
```

## Response

The following excerpt shows selected fields. The [OpenAPI contract](https://api.oldcarsdata.com/openapi.json) describes every response field.

```json
{
  "data": [
    {
      "id": 12345,
      "source": "streetside",
      "source_listing_id": "6007-tpa",
      "url": "https://www.streetsideclassics.com/vehicles/6007-tpa/example",
      "title": "1985 Porsche 911 Carrera",
      "sale_type": "classified",
      "status": "active",
      "year": 1985,
      "listing_make": "Porsche",
      "listing_model": "911 Carrera",
      "ocd_make_name": "Porsche",
      "ocd_model_name": "911",
      "asking_price": 65000,
      "sold_price": null,
      "last_asking_price": 65000,
      "asking_price_history": [
        { "price": 65000, "observed_at": "2026-11-15T12:00:00Z" }
      ],
      "financing": null,
      "currency": "USD",
      "sold_on": null,
      "last_seen_at": "2026-11-15T12:00:00Z",
      "updated_at": "2026-11-15T12:00:00Z",
      "changed_at": "2026-11-15T12:00:00Z"
    }
  ],
  "meta": {
    "pagination": "cursor",
    "limit": 10,
    "has_more": true,
    "next_cursor": "OPAQUE_CURSOR"
  }
}
```

Listings also include mileage and its unit, trim, engine, transmission, drivetrain, fuel type, body style, colors, condition, restoration history, title status, seller name and type, stock number, location, and a featured image URL. Listing descriptions are excluded from responses and keyword search.

`listed_on`, `source_updated_on`, and `sold_on` are source dates in `YYYY-MM-DD` format. `first_seen_at`, `last_observed_at`, `last_seen_at`, `last_checked_at`, `last_asking_price_observed_at`, and `updated_at` are observation or database timestamps returned in RFC 3339 format with a timezone offset. Observation times are not inferred sale dates.

`last_seen_at` records source presence, while `last_observed_at` records the full listing detail capture. `updated_at` includes routine checks; `changed_at` tracks changes to listing facts. These times can differ. A content-only sync does not keep your local freshness timestamps current; query `last_seen_before` against the server when looking for stale listings. See [freshness and capture times](#freshness-and-capture-times) before applying a strict freshness cutoff.

## Cursor pagination

Follow `next_cursor` until `has_more` is false. The last page returns `next_cursor: null`. An empty search returns `data: []`. Responses omit exact counts and numbered pages.

```javascript
const filters = new URLSearchParams({
  make: 'Porsche',
  currency: 'USD',
  price_max: '100000',
  limit: '100',
});

while (true) {
  const response = await fetch(
    `https://api.oldcarsdata.com/classifieds?${filters}`,
    { headers: { Authorization: `Bearer ${process.env.OCD_API_KEY}` } },
  );
  if (!response.ok) throw new Error(await response.text());
  const { data, meta } = await response.json();
  for (const listing of data) console.log(listing.id, listing.asking_price);
  if (!meta.has_more) break;
  filters.set('cursor', meta.next_cursor);
}
```

Page cursors are signed, specific to this endpoint and its filters, and expire 24 hours after the first page. Completed sync checkpoints described below have no time expiry. Changing filters or direction requires starting again without a cursor. Expired, changed, or malformed cursors return HTTP 400. Pages read the current database; concurrent updates can move listings between pages. Upsert by `id` when maintaining a local copy.

## Polling for changes

For changes to listing facts without re-fetching every routine freshness refresh, use:

```bash
curl "https://api.oldcarsdata.com/classifieds?country_code=US&status=all&direction=asc&changed_since=2026-11-15T00%3A00%3A00Z&limit=100" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

This orders by `changed_at`, then `id`, so routine freshness writes do not move listings between content-change pages. Keep `changed_since` fixed through the traversal. Each successful page consumes one query under your existing plan; page sizes remain 1–100. If both `changed_since` and `updated_since` are supplied, both bounds apply and order uses `changed_at, id`.

With `changed_since` and `direction=asc`, the last complete page also returns `meta.next_sync_cursor`. Save it after successfully upserting the page, then pass it as `cursor` on the next poll with the same filters and direction. The checkpoint skips the completed timestamp and ID boundary, so unchanged batches do not replay. An empty resumed poll also returns a checkpoint. An initial empty search without a prior cursor has no checkpoint; keep its current filters for the next poll.

Checkpoints have no time expiry and start a fresh traversal when reused. The new page cursors still have the normal 24-hour expiry. Checkpoints remain bound to the original filters and signing key; changing filters or rotating that key invalidates them. Starter results truncated by the plan's 20-row traversal cap do not receive a completed checkpoint. Page sizes, metering, and plan limits are unchanged.

For a first complete copy, use an early `changed_since` such as `1970-01-01T00:00:00Z`, `status=all`, and `direction=asc`, then follow pages and save the completed checkpoint. For later polls, reuse that checkpoint and the original filters. If you manage timestamp windows yourself instead, keep the inclusive boundary fixed while paging, overlap windows, and upsert by `id`.

Existing records start with their stored update time as a baseline, capped at migration time; earlier content-change dates are not reconstructed. Publication timestamps advance beyond earlier batches even after a clock correction, so new changes stay ahead of saved checkpoints. Normal full refreshes preserve unchanged records' change times. A first build or recovery without the previous serving table needs a new baseline. This returns each matching listing's current stored version, rather than every intermediate change or a deletion log.

Include all statuses so that sales, withdrawals, and listings with inaccessible source pages can update your local copy:

```bash
curl "https://api.oldcarsdata.com/classifieds?status=all&direction=asc&updated_since=2026-11-15T00%3A00%3A00Z&limit=100" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Keep `updated_since` fixed while following cursors. After finishing a traversal, start a new one from your saved update time with a small overlap, and upsert by `id`. The timestamp boundary is inclusive. This is a feed of stored listings, not a deletion log, and it has no fixed refresh-time guarantee.

## Finding listings not seen recently

Calculate an absolute cutoff in your application and keep it fixed while paging. For example, this selects eligible active US listings last seen before November 16:

```bash
curl "https://api.oldcarsdata.com/classifieds?country_code=US&status=active&last_seen_before=2026-11-16T00%3A00%3A00Z&limit=100" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Use `status=all` to include retained history as well. The cutoff is exclusive, and records with unknown `last_seen_at` do not match. The filter only selects records; it never changes their status. It works with the other filters and the same REST/MCP cursors.

Use this server query when deciding which listings are stale. A separate content sync can then use its saved checkpoint; it does not need to download every routine presence refresh or rely on old `last_seen_at` values in a local cache. Calculate a new cutoff for each freshness check and start that check without a previous cursor. Keep the cutoff fixed through its pages.

## Errors

| Status | Meaning |
| --- | --- |
| `400` | Invalid, unknown, repeated, or blank parameters; invalid or expired cursor. |
| `401` | Missing, invalid, or expired API key. |
| `403` | Account or email verification requirements were not met. |
| `429` | Monthly allowance or per-minute request limit reached. Follow `Retry-After` when supplied. |
| `500` | The database query failed. |

Errors use the same `error`, `message`, and optional `details` fields as the other REST endpoints.

The former `availability` field and filter have been removed. Requests containing `availability` return HTTP 400. Remove that parameter and restart any cursor traversal begun before this change. Use `status=all` for a complete change feed.
