---
title: "The live book for one instrument"
method: GET
path: "/v2/quotes/{ref}"
tags: ["quotes"]
---

# The live book for one instrument

`GET /v2/quotes/{ref}`

## Request

- Base URL: `https://api.cardog.app`
- URL: `https://api.cardog.app/v2/quotes/{ref}`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

## Path parameters

- `ref` string, required

## Response `200`

NBBO-style quote line: best, percentiles, DOM, cuts

- Quote
  - `ref` string, required: Ref of the instrument (the thing being priced: a model year or a squish), e.g. "model-year:honda/cr-v/2026"
  - `grain` 'mmy' | 'mmy.drive' | 'mmy.fuel' | 'mmy.body' | 'squish', required: Level of detail the instrument is priced at: "mmy" (model year), "mmy.drive", "mmy.fuel" or "mmy.body" (model year split by drive type, fuel type, or body style), or "squish" (exact configuration: WMI + VDS + model year, plant-agnostic)
  - `liveCount` integer, required: Number of live listings the quote is computed from. Treat it as the sample size.
  - `bestPrice` number, nullable, required: Lowest live asking price
  - `priceP25` number, nullable, required: 25th percentile of live asking prices
  - `priceMedian` number, nullable, required: Median live asking price
  - `priceP75` number, nullable, required: 75th percentile of live asking prices
  - `avgDomDays` number, nullable, required: Average days on market across the live listings
  - `cuts30d` integer, nullable, required: Number of price cuts observed in the trailing 30 days
  - `avgCutPct30d` number, nullable, required: Average price cut as a percentage, trailing 30 days
  - `sightings30d` integer, nullable, required: Number of listing observations in the trailing 30 days
  - `asOf` string, required: When the quote was last computed (ISO 8601)
  - `links` object: Related resources, keyed by relation name, each a server-relative path. Example: {"recalls": "/v2/recalls/entity/model-year:toyota/rav4/2021"}

## Other responses

- `400`: Invalid request — grammar failure or unknown-but-well-formed refs, NAMED in `refs`/`details`, with nearest-ref `suggestions` where computable. Never a fuzzy fallback.
- `401`: No valid credential (API key, session, or internal token)
- `402`: Insufficient credits (free-tier hard stop; paid tiers bill overage instead)
- `404`: Resource not found
- `429`: Per-minute rate limit exceeded
- `500`: Internal error

---

[API](https://skmtc.dev/cardog/apis/cardog-api-v2.md) · [All operations](https://skmtc.dev/cardog/apis/cardog-api-v2/llms.txt) · [OpenAPI document](https://skmtc.dev/cardog/apis/cardog-api-v2/revisions/b9d48193126f?raw)