---
title: "Symbology search / most-liquid browse"
method: GET
path: "/v2/instruments"
tags: ["instruments"]
---

# Symbology search / most-liquid browse

`GET /v2/instruments`

## Request

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

With `q`: typeahead over live instruments. Without: the most-liquid screener rows.

## Query parameters

- `q` string
- `limit` integer

## Response `200`

Screener rows with quote line + sparkline

- InstrumentSearch
  - `query` string, nullable
  - `items` object[], required
    - `ref` string, required
    - `label` string
    - `makeName` string
    - `spark` number[]: Daily median prices for the trailing 45 days, oldest first. Intended for an inline sparkline.
    - `median30d` number, nullable: Median price 30 days ago. Compare with `median` to get the 30-day change.
    - `count` integer, required: Number of live listings for this instrument
    - `best` number, nullable, required: Lowest live asking price
    - `p25` number, nullable, required: 25th percentile of live asking prices
    - `median` number, nullable, required: Median live asking price
    - `p75` number, nullable, required: 75th percentile of live asking prices
    - `avgDom` 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
    - `cutPct30d` 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
  - `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)
- `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)