## Reference: Quotes

The live book per instrument

**Availability: live** on `https://api.cardog.app`.

### GET /v2/quotes

Multi-quote: one call, up to 20 instruments

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `refs` | string | yes | Comma-separated instrument refs, e.g. "model-year:honda/cr-v/2026,model-year:toyota/rav4/2026". Unknown refs 400, named. |

**Response 200** `MultiQuote` — Quotes in request order

- `quotes` (object[]) — Same order as the request
  - `quotes[].ref` (string) — Instrument ref, e.g. "model-year:honda/cr-v/2026"
  - `quotes[].grain` ("mmy" | "mmy.drive" | "mmy.fuel" | "mmy.body" | "squish")
  - `quotes[].liveCount` (integer) — Active listings backing the quote
  - `quotes[].bestPrice` (number | null)
  - `quotes[].priceP25` (number | null)
  - `quotes[].priceMedian` (number | null)
  - `quotes[].priceP75` (number | null)
  - `quotes[].avgDomDays` (number | null) — Average days-on-market
  - `quotes[].cuts30d` (integer | null) — Price cuts observed, trailing 30d
  - `quotes[].avgCutPct30d` (number | null) — Average cut size, %, trailing 30d
  - `quotes[].sightings30d` (integer | null)
  - `quotes[].asOf` (string) — When the quote was last computed (ISO 8601)
  - `quotes[].links`? (object) — Related resources, rel → server-relative path. Example: {"recalls": "/v2/recalls/entity/model-year:toyota/rav4/2021"}
- `links`? (object) — Related resources, rel → server-relative path. Example: {"recalls": "/v2/recalls/entity/model-year:toyota/rav4/2021"}

**Errors** (all use the ErrorEnvelope): 400, 401, 402, 429, 500

**Example — cURL**

```bash
curl "https://api.cardog.app/v2/quotes?refs=model-year:honda/cr-v/2026,model-year:toyota/rav4/2026" \
  -H "x-api-key: $CARDOG_API_KEY"
```

**Example — TypeScript** (`npm install @cardog/api`)

```typescript
import { CardogClient } from "@cardog/api";

const client = new CardogClient({ apiKey: process.env.CARDOG_API_KEY });

const multiQuote = await client.v2.quotes.getMany(["model-year:honda/cr-v/2026", "model-year:toyota/rav4/2026"]);
console.log(multiQuote.quotes);
```

**Example — Python** (`pip install cardog`)

```python
import os

from cardog import Cardog

client = Cardog(api_key=os.environ["CARDOG_API_KEY"])

multi_quote = client.v2.quotes.get_many(["model-year:honda/cr-v/2026", "model-year:toyota/rav4/2026"])
print(multi_quote.quotes)
```

### GET /v2/quotes/{ref}

The live book for one instrument

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `ref` | string | yes | An instrument ref. Slashes in refs must be URL-encoded (%2F). |

**Response 200** `Quote` — NBBO-style quote line: best, percentiles, DOM, cuts

- `ref` (string) — Instrument ref, e.g. "model-year:honda/cr-v/2026"
- `grain` ("mmy" | "mmy.drive" | "mmy.fuel" | "mmy.body" | "squish")
- `liveCount` (integer) — Active listings backing the quote
- `bestPrice` (number | null)
- `priceP25` (number | null)
- `priceMedian` (number | null)
- `priceP75` (number | null)
- `avgDomDays` (number | null) — Average days-on-market
- `cuts30d` (integer | null) — Price cuts observed, trailing 30d
- `avgCutPct30d` (number | null) — Average cut size, %, trailing 30d
- `sightings30d` (integer | null)
- `asOf` (string) — When the quote was last computed (ISO 8601)
- `links`? (object) — Related resources, rel → server-relative path. Example: {"recalls": "/v2/recalls/entity/model-year:toyota/rav4/2021"}

**Errors** (all use the ErrorEnvelope): 400, 401, 402, 404, 429, 500

**Example — cURL**

```bash
curl "https://api.cardog.app/v2/quotes/model-year:honda%2Fcr-v%2F2026" \
  -H "x-api-key: $CARDOG_API_KEY"
```

**Example — TypeScript** (`npm install @cardog/api`)

```typescript
import { CardogClient } from "@cardog/api";

const client = new CardogClient({ apiKey: process.env.CARDOG_API_KEY });

const quote = await client.v2.quotes.getByRef("model-year:honda/cr-v/2026");
console.log(quote.ref);
```

**Example — Python** (`pip install cardog`)

```python
import os

from cardog import Cardog

client = Cardog(api_key=os.environ["CARDOG_API_KEY"])

quote = client.v2.quotes.get("model-year:honda/cr-v/2026")
print(quote.ref)
```

---

Previous: [Instruments](https://cardog.app/docs/reference/instruments.md) — API reference
Next: [Tape](https://cardog.app/docs/reference/tape.md) — API reference