# CUSIP API — Finradar API
> Version: 3.61.0 | Generated: 2026-06-20 | Content Hash: 626527fd
> Fetch this file at: https://uat.finradarapi.com/llms/cusip-api.txt

## Authentication
All endpoints require an API key. Pass it via query parameter `?apiKey=YOUR_KEY` or header `X-API-Key: YOUR_KEY`. WebSocket endpoints accept the key in the `token` auth payload or query parameter.

---

## CUSIP API

Resolve CUSIPs to Tickers and vice-versa.

### GET /api/v1/cusip/lookup/{cusip}

Resolve CUSIP to Ticker.

**Token cost:** 1 token per call

**Response fields:**
- `cusip` (string): Echoed 9-character CUSIP (post-normalization — leading whitespace stripped, padded to 9 chars if input was 8). Use for index-matching against the request input.
- `ticker` (string (nullable)): Resolved canonical ticker (hyphen form — `BRK-A` not `BRK.A`). Null when (a) the CUSIP exists in the catalog but has no associated ticker (debt securities, private placements, delisted issuers), or (b) the OpenFIGI enrichment fallback failed without a key (~24% of legacy CUSIPs without `OPENFIGI_API_KEY` set; with the key set this drops to <2%).
- `issuer_name` (string (nullable)): Issuer name from the canonical catalog (typically all-caps EDGAR convention for SEC-registered issuers — `APPLE INC` not `Apple Inc.`; varies for international issuers). Null when the CUSIP is unmapped.
- `cik` (string (nullable)): 10-character zero-padded SEC CIK of the issuer (e.g. `0000320193` for Apple). Null when the issuer has no SEC registration (rare; foreign-private issuers without ADR programs). Pair with `/api/v1/sec/filings?cik=...` for filing history.
- `cusip6` (string): First 6 characters of the CUSIP — the ISSUER PREFIX. A single legal issuer can have multiple 9-char CUSIPs across share classes / debt issues, all sharing the same `cusip6`. Useful for grouping multi-class issuers (e.g. BRK-A `084670108` and BRK-B `084670702` both share `cusip6=084670`).
- `security_group` (string (nullable)): Security classification — one of `Stocks` (common equity), `ETFs`, `Preferred`, `Warrants`, `Debt` (bonds, notes), `Other` (REITs, partnership units). Null when the catalog entry exists but security_group is not yet enriched.

**Since:** v1.0.0

**Utility:** Convert 9-digit CUSIPs (the universal SEC-filing security identifier) to canonical hyphen-form tickers — the single-row variant of the batch endpoint, optimised for the 'I have one CUSIP, what ticker is this?' workflow common in single-filing parsing pipelines. Backed by FinRadar's `cusip_security_catalog` (~26K rows post v3.11.0). When a CUSIP has been replaced by a corporate-action successor (SPAC merger, reorg, redomicile) this endpoint returns the CURRENT ticker — for the full historical chain use [GET /api/v1/cusip/chain/{cusip}](/docs/reference-data/cusip-api/get-cusip-chain).

**Use case:** Mapping 13F holdings data to actionable ticker symbols when you only have the CUSIP from a parsed filing row — e.g. SEC 13F-HR information table rows arrive with CUSIPs, but downstream alpha models speak ticker. Also useful in 'reverse-lookup' workflows: a customer asks 'what stock is CUSIP 037833100?' and you need the ticker + issuer name in one call.

**Parameters:**
- `cusip` (path, required): 9-character CUSIP. Whitespace and case are normalized server-side; 8-character CUSIPs (missing the trailing check digit) are zero-padded to 9. Returns 404 when the CUSIP is not in `cusip_security_catalog` — for stale or successor-replaced CUSIPs try `/cusip/chain/{cusip}` to chase corporate-action history. Real public-domain examples: `037833100` (Apple), `594918104` (Microsoft), `02079K305` (Alphabet Class A), `02079K107` (Alphabet Class C), `084670702` (Berkshire Class B).

**Sample response:**
```json
{
  "cusip": "037833100",
  "ticker": "AAPL",
  "issuer_name": "APPLE INC",
  "cik": "0000320193",
  "cusip6": "037833",
  "security_group": "Stocks"
}
```

### GET /api/v1/cusip/ticker/{ticker}

Resolve Ticker to CUSIP.

**Token cost:** 1 token per call

**Response fields:**
- `ticker` (string): Echoed canonical ticker (post-normalization to hyphen form). Use for index-matching against the request input.
- `cusip` (string): 9-character CUSIP for the CURRENT primary security mapped to this ticker. For a ticker like `RKLB` that has been through a SPAC merger, this is the CURRENT CUSIP only — append `?chain=true` to receive the full historical chain instead. For multi-class issuers, this is the most-liquid class only (BRK-A returns the A-class CUSIP, BRK-B returns the B-class CUSIP).
- `issuer_name` (string): Issuer name from the canonical catalog (all-caps EDGAR convention for SEC-registered issuers — `APPLE INC`).
- `cik` (string (nullable)): 10-character zero-padded SEC CIK of the issuer (e.g. `0000320193`). Null when the issuer has no SEC registration.
- `cusip6` (string): 6-character CUSIP issuer prefix. Multi-class issuers share a CUSIP6 (BRK-A `084670108` and BRK-B `084670702` both share `084670`). Use to group across share classes.

**Since:** v1.0.0

**Utility:** Reverse direction of [GET /api/v1/cusip/lookup/{cusip}](/docs/reference-data/cusip-api/get-cusip-lookup) — given a ticker, return the CUSIP. Useful when you need to bridge ticker-shaped customer input into CUSIP-shaped 13F query parameters (e.g. `POST /form-13f/holdings` accepts CUSIPs but a UI may want to expose ticker search). Backed by `cusip_security_catalog`. Returns the CURRENT active CUSIP only — to retrieve historical CUSIPs across corporate actions append `?chain=true` (see [/cusip/ticker/{ticker}?chain=true](/docs/reference-data/cusip-api/get-cusip-ticker-chain)).

**Use case:** Preparing data for institutional reporting or regulatory filings — converting customer-facing tickers (e.g. `AAPL`) into the CUSIP form (e.g. `037833100`) required by 13F holdings queries, regulatory submissions, and CUSIP6-grouped multi-class drill-downs. Also useful in 'enrich a watchlist of tickers with CUSIPs for batch 13F lookup' flows.

**Parameters:**
- `ticker` (path, required): Canonical hyphen-form ticker (`BRK-A` not `BRK.A`). Server-side normalization applies the v3.14.2 ticker-coercion shim — `BRK.A`, `BRK/A`, `BRKA` all coerce to `BRK-A`. Returns 404 when no active CUSIP mapping exists (delisted issuers, foreign tickers without OpenFIGI coverage).

**Sample response:**
```json
{
  "ticker": "AAPL",
  "cusip": "037833100",
  "issuer_name": "APPLE INC",
  "cik": "0000320193",
  "cusip6": "037833"
}
```

### POST /api/v1/cusip/batch

Batch CUSIP resolution.

**Token cost:** 5 tokens per call

**Response fields:**
- `results` (array): One row per requested CUSIP, in INPUT ORDER (not sorted) — so client code can safely zip the response array back against the request array. Unmapped CUSIPs still produce a row (with null `ticker` / `issuer_name` / `security_group`) so output length always matches input length.
- `results[].cusip` (string): Echoed 9-character CUSIP (post-normalization — leading whitespace stripped, padded to 9 chars if input was 8). Use for index-matching against the input array when needed.
- `results[].ticker` (string (nullable)): Resolved canonical ticker (hyphen form). Null when (a) the CUSIP is not in our `cusip_security_catalog` (~3% of legacy 13F filings), (b) the security has no ticker (debt, private placements), or (c) the issuer was delisted before our enrichment ran. For chain-aware multi-CUSIP-per-ticker tracking use `/cusip/chain/{cusip}`.
- `results[].issuer_name` (string (nullable)): Issuer name from the canonical catalog (typically all-caps EDGAR convention for SEC-registered issuers; varies for international issuers). Null when the CUSIP is unmapped. Use for human-readable rendering rather than the raw `cusip` itself.
- `results[].security_group` (string (nullable)): Security classification — one of `Stocks` (common equity), `ETFs` (exchange-traded funds), `Preferred` (preferred stock), `Warrants`, `Debt` (bonds, notes), `Other` (REITs, partnership units, etc.). Null when the catalog entry exists but security_group is not yet enriched. Filter 13F holdings to `Stocks` only for clean common-equity flow analysis.
- `results[].cusip6` (string): First 6 characters of the CUSIP — the ISSUER PREFIX (a single legal issuer can have multiple 9-char CUSIPs across share classes / debt issues, all sharing the same `cusip6`). Useful for grouping multi-class issuers. Always present even when the full 9-char CUSIP is unmapped.
- `meta` (object): Resolution-rate metadata: `{ requested: integer, resolved: integer, unmapped: integer }`. `resolved + unmapped == requested`. A high `unmapped` count (>10%) suggests the input batch contains stale/legacy CUSIPs — try with chain-expansion via `/cusip/chain/{cusip}` per-row to chase corporate-action successors.

**Since:** v1.0.0

**Utility:** Bulk CUSIP→ticker resolution — pass up to 1,000 CUSIPs in one request and receive ticker, issuer name, security group classification, and CUSIP6 (issuer prefix) for each. The hot-path enrichment endpoint for 13F holdings normalization workflows: 13F filings deliver positions as 9-character CUSIPs, but downstream analytics need tickers. Backed by FinRadar's `cusip_security_catalog` (~26K rows post-v3.11.0 expansion). Returns 6 security-group buckets: Stocks, ETFs, Preferred, Warrants, Debt, Other — useful for filtering 13F books to common-stock-only views without per-row decisions. Single-CUSIP variants (`/cusip/lookup/{cusip}`) exist but cost more per row at scale; this batch endpoint is the right choice for any multi-CUSIP workflow.

**Use case:** Resolving all holdings in a large portfolio in a single request.

**Parameters:**
- `cusips` (body, required): Array of 9-character CUSIP strings (max 1,000 per request — server returns 400 above the cap; for larger universes split into multiple batches client-side). 8-char CUSIPs (missing check digit) are zero-padded server-side. Whitespace and case are normalized. Order is preserved in the response so client code can zip results back to inputs.

**Sample response:**
```json
{
  "results": [
    {
      "cusip": "037833100",
      "ticker": "AAPL",
      "issuer_name": "APPLE INC",
      "security_group": "Stocks",
      "cusip6": "037833"
    },
    {
      "cusip": "02079K305",
      "ticker": "GOOGL",
      "issuer_name": "ALPHABET INC",
      "security_group": "Stocks",
      "cusip6": "02079K"
    }
  ],
  "meta": {
    "requested": 2,
    "resolved": 2,
    "unmapped": 0
  }
}
```

### GET /api/v1/cusip/chain/{cusip}

Get full CUSIP successor chain for a security (corporate actions tracking).

**Token cost:** 5 tokens per call

**Response fields:**
- `cusip` (string): Echoed input CUSIP — the seed for the chain walk.
- `chain` (array): Array of chain entries in CHRONOLOGICAL order (oldest CUSIP first, current CUSIP last). The last entry's `cusip` is the CURRENT active CUSIP for the security.
- `chain[].cusip` (string): 9-character CUSIP at this point in the chain.
- `chain[].issuer_name` (string): Issuer name AT THE TIME this CUSIP was active — preserves the historical-issuer-identity view (e.g. `VECTOR ACQUISITION CORP` for the pre-SPAC RKLB CUSIP, `ROCKET LAB USA INC` for the post-SPAC CUSIP, `ROCKET LAB CORP` for the post-redomicile CUSIP).
- `chain[].effective_date` (string (nullable)): ISO-8601 date this CUSIP became active. Null on the seed CUSIP (catalog-origin date is not always known; the chain only tracks the TRANSITION dates between CUSIPs, not the initial issuance).
- `chain[].reason` (string (nullable)): Corporate-action reason that triggered the CUSIP transition — one of `SPAC merger`, `Reorg`, `Redomicile`, `Acquisition`, `Spin-off`, `Reverse merger`, `Symbol change`. Null on the seed (initial-issuance) entry.
- `chain[].is_current` (boolean): `true` for exactly one entry — the CURRENT active CUSIP. `false` for all historical predecessors.
- `current_ticker` (string (nullable)): Convenience field — the canonical ticker for the CURRENT CUSIP (last chain entry). Null when the security is delisted or has no public-equity ticker.

**Since:** v1.0.0

**Utility:** Returns the complete chain of CUSIPs for a security that has undergone corporate actions (SPAC mergers, holding company reorgs, redomiciliations). Shows the progression from original -> intermediate -> current CUSIP with effective dates, reasons, and the current ticker. The single canonical answer to 'show me every CUSIP that has ever represented this security' — Phase 11 (initial chain table) + Phase 47 (unified-holder layer chain expansion) work product. Without chain awareness, ownership data appears to show 3 different securities instead of 1 (and 13F-derived position-history charts get clipped at every CUSIP transition).

**Use case:** Tracking Rocket Lab (RKLB) through its SPAC merger: `G9442R126` (Vector Acquisition Corp pre-SPAC) -> `773122106` (Rocket Lab USA post-SPAC) -> `773121108` (Rocket Lab Corporation post-redomicile). Without chain awareness, the position-history chart for RKLB clips at each CUSIP transition. With chain awareness, the underlying 13F holdings query expands to all 3 CUSIPs and the timeline is continuous. Also useful for any holdings-aggregation workflow that needs to roll up legacy CUSIPs (DLTR pre-Family-Dollar-merger, AVGO pre-VMware-acquisition, etc.).

**Parameters:**
- `cusip` (path, required): Any CUSIP in the chain (old or current). The endpoint walks the chain in BOTH directions from the input — pre-mergers AND post-mergers — to return the complete history. Examples: `G9442R126` (pre-SPAC RKLB) returns the same chain as `773121108` (current RKLB).

**Sample response:**
```json
{
  "cusip": "773121108",
  "chain": [
    {
      "cusip": "G9442R126",
      "issuer_name": "VECTOR ACQUISITION CORP",
      "effective_date": null,
      "reason": null,
      "is_current": false
    },
    {
      "cusip": "773122106",
      "issuer_name": "ROCKET LAB USA INC",
      "effective_date": "2021-08-25",
      "reason": "SPAC merger",
      "is_current": false
    },
    {
      "cusip": "773121108",
      "issuer_name": "ROCKET LAB CORPORATION",
      "effective_date": "2025-11-01",
      "reason": "Redomicile",
      "is_current": true
    }
  ],
  "current_ticker": "RKLB"
}
```

### GET /api/v1/cusip/ticker/{ticker}?chain=true

Resolve Ticker to CUSIP with full successor chain.

**Token cost:** 1 token per call

**Response fields:**
- `ticker` (string): Echoed canonical ticker (post-normalization to hyphen form).
- `cusip` (string): 9-character CUSIP for the CURRENT primary security mapped to this ticker. Same field as the no-chain variant; present even when `chain=true`.
- `issuer_name` (string): Issuer name of the CURRENT security (all-caps EDGAR convention).
- `cik` (string (nullable)): 10-character zero-padded SEC CIK of the CURRENT issuer.
- `cusip6` (string): 6-character CUSIP issuer prefix of the CURRENT CUSIP. NOTE: CUSIP6 changes across reorgs — do NOT use as a stable issuer identifier.
- `chain` (array (nullable)): Array of historical CUSIPs sharing this security's lineage, in CHRONOLOGICAL order (oldest first, current last). Only present when `?chain=true`. Each entry: `{ cusip: string, issuer_name: string, effective_date: string|null, reason: string|null, from_chain: boolean }`. The `from_chain: true` flag distinguishes chain predecessors from the seed CUSIP itself.

**Since:** v1.0.0

**Utility:** Ticker-keyed variant of [GET /api/v1/cusip/chain/{cusip}](/docs/reference-data/cusip-api/get-cusip-chain) — when you have the current ticker (`RKLB`) and need every CUSIP that has ever represented it (pre-SPAC + post-SPAC + post-redomicile). Without `chain=true` (default false), the endpoint behaves identically to the no-chain variant and returns the CURRENT CUSIP only. With `chain=true`, the response includes a `chain[]` array of all historical CUSIPs with `from_chain` flags. The most-natural entrypoint for ticker-shaped UI inputs that need chain-aware downstream queries.

**Use case:** Building comprehensive holdings queries that span CUSIP transitions — e.g. 'show me Berkshire's RKLB position from inception to today' requires querying 13F holdings across all 3 RKLB CUSIPs. Without the chain, the position appears to drop to 0 at each merger date and re-emerge under a new CUSIP. With the chain, the position-history chart is continuous. Also useful in 'reconcile a customer's ticker watchlist with their 13F-based position blotter' workflows that need historical-CUSIP coverage.

**Parameters:**
- `ticker` (path, required): Canonical hyphen-form ticker. v3.14.2 ticker-normalization shim applies (`BRK.A`/`BRK/A`/`BRKA` all coerce to `BRK-A`). The CURRENT ticker is required — historical-only tickers like `VACQ` (pre-SPAC RKLB) are not supported as input; use the CUSIP variant if you need to seed the chain walk from a historical entity.
- `chain` (query, optional, default: false): When `true`, response includes a `chain[]` array of all historical CUSIPs sharing this security's lineage. When `false` (default) or omitted, response is byte-identical to [GET /api/v1/cusip/ticker/{ticker}](/docs/reference-data/cusip-api/get-cusip-ticker) and returns CURRENT CUSIP only — backwards-compatible with pre-Phase-11 callers.

**Sample response:**
```json
{
  "ticker": "RKLB",
  "cusip": "773121108",
  "issuer_name": "ROCKET LAB CORPORATION",
  "cik": "0001819810",
  "cusip6": "773121",
  "chain": [
    {
      "cusip": "G9442R126",
      "issuer_name": "VECTOR ACQUISITION CORP",
      "effective_date": null,
      "reason": null,
      "from_chain": true
    },
    {
      "cusip": "773122106",
      "issuer_name": "ROCKET LAB USA INC",
      "effective_date": "2021-08-25",
      "reason": "SPAC merger",
      "from_chain": true
    },
    {
      "cusip": "773121108",
      "issuer_name": "ROCKET LAB CORPORATION",
      "effective_date": "2025-11-01",
      "reason": "Redomicile",
      "from_chain": false
    }
  ]
}
```

### GET /api/v1/cusip/cik/{cik}

Look up company CUSIP mappings by CIK number. Supports both short (e.g. 320193) and 10-digit zero-padded CIK formats.

**Token cost:** 1 token per call

**Response fields:**
- `cik` (string): Echoed CIK in 10-character zero-padded form regardless of input format.
- `issuer_name` (string): Issuer legal name from the canonical catalog (all-caps EDGAR convention).
- `securities` (array): Array of all CUSIPs registered to this CIK — one entry per security class (common stock, preferred, convertible, etc.). Multi-class issuers like BRK (2 classes) or AMZN-pre-split (1 class) return correspondingly-sized arrays. Order is by `security_group` priority then by ticker alphabetical (Stocks > Preferred > Warrants > Debt > Other) so common-equity classes appear first.
- `securities[].cusip` (string): 9-character CUSIP for this security class.
- `securities[].ticker` (string (nullable)): Canonical hyphen-form ticker. Null for unmapped tickers (debt securities, private placements).
- `securities[].security_group` (string (nullable)): Security classification — `Stocks` / `ETFs` / `Preferred` / `Warrants` / `Debt` / `Other`. Useful for filtering to common-equity-only or all-equity-classes views.
- `securities[].cusip6` (string): 6-character CUSIP issuer prefix. All securities for one CIK typically share the same CUSIP6 (Berkshire's BRK-A and BRK-B both share `084670`), but corporate-action successors can have different CUSIP6 prefixes (RKLB has CUSIP6 history `G9442R` -> `773122` -> `773121`).

**Since:** v3.14.0

**Utility:** Reverse lookup from SEC CIK to CUSIP and ticker — when your input is the SEC's canonical company identifier (e.g. you parsed a filing accession and want the CUSIP for downstream 13F holdings query). Returns ALL CUSIPs registered to the issuer, not just the primary — multi-class issuers like BRK (A + B classes), GOOGL (Alphabet A + C), and FTCH (with foreign-equivalent classes) can have 2-5 CUSIPs per CIK. Pair with [GET /api/v1/cusip/cusip6/{cusip6}](/docs/reference-data/cusip-api/get-cusip-cusip6) when you also want preferred / convertible / debt securities for the same issuer.

**Use case:** Filing-parsing pipelines that emit `(cik, accession_number)` rows and need to enrich with `(cusip, ticker)` for downstream holdings reconciliation. Also useful in 'show me all share classes for this issuer' workflows — Berkshire Hathaway CIK `0001067983` returns both BRK-A (`084670108`) and BRK-B (`084670702`) in one call.

**Parameters:**
- `cik` (path, required): SEC CIK number. Both formats accepted: 10-character zero-padded (`0000320193`) and short unpadded (`320193`). Server-side normalization handles both via `func.ltrim(cik, '0')` matching. Returns 404 when no CUSIP is registered to the CIK (rare; typically foreign-private issuers without ADR programs, or pre-registration shell companies).

**Sample response:**
```json
{
  "cik": "0001067983",
  "issuer_name": "BERKSHIRE HATHAWAY INC",
  "securities": [
    {
      "cusip": "084670108",
      "ticker": "BRK-A",
      "security_group": "Stocks",
      "cusip6": "084670"
    },
    {
      "cusip": "084670702",
      "ticker": "BRK-B",
      "security_group": "Stocks",
      "cusip6": "084670"
    }
  ]
}
```

### GET /api/v1/cusip/cusip6/{cusip6}

Look up all securities sharing a 6-digit CUSIP issuer prefix. Returns all 9-digit CUSIPs with matching first 6 characters (same issuer, different securities — common stock, preferred, warrants, etc.).

**Token cost:** 1 token per call

**Response fields:**
- `cusip6` (string): Echoed input CUSIP6 (uppercased).
- `issuer_name` (string): Most-common issuer name across all securities sharing this CUSIP6. For multi-entity prefixes (rare but possible after reorgs) this is the modal name; consult `securities[].issuer_name` for per-CUSIP detail.
- `securities` (array): Array of all 9-character CUSIPs sharing this issuer prefix. Order: by `security_group` priority then by ticker alphabetical (Stocks first, then ETFs / Preferred / Warrants / Debt / Other). For Apple `037833`: returns common stock; for Berkshire `084670`: returns BRK-A then BRK-B.
- `securities[].cusip` (string): Full 9-character CUSIP.
- `securities[].ticker` (string (nullable)): Canonical hyphen-form ticker. Null for unmapped securities (debt, private placements).
- `securities[].issuer_name` (string): Issuer name for THIS specific CUSIP — typically identical to the top-level `issuer_name` field but can vary slightly for amended-filings or post-reorg edge cases.
- `securities[].security_group` (string (nullable)): Security classification — `Stocks` / `ETFs` / `Preferred` / `Warrants` / `Debt` / `Other`. Filter to `Stocks` for common-equity-only views; `Preferred + Warrants` for hybrid-instrument exposure analysis.
- `securities[].cik` (string (nullable)): 10-character zero-padded SEC CIK for the issuer. Typically identical across all securities in the prefix (same legal entity).

**Since:** v3.14.0

**Utility:** Find all securities sharing a 6-digit CUSIP issuer prefix — typically returns more security classes than [GET /api/v1/cusip/cik/{cik}](/docs/reference-data/cusip-api/get-cusip-cik) because the CUSIP6 prefix groups by ISSUER OPERATIONALLY (CINS-assigned by CUSIP Global Services) rather than by SEC CIK. So a single CUSIP6 like `037833` (Apple) returns the common stock CUSIP plus any preferred / convertible / debt CUSIPs the same issuer has registered through CUSIP services. Useful when you need all security types (common + preferred + convertibles + bonds) for an issuer in one call. Note: CUSIP6 is NOT stable across reorgs — successor CUSIPs typically get new CUSIP6 prefixes (RKLB went `G9442R` -> `773122` -> `773121`).

**Use case:** Discovering all security classes (common, preferred, convertible, warrants, debt) for an issuer when you only have the 6-digit issuer code from a partial CUSIP reference. Also useful in 'find all securities Apple has issued' workflows where the customer wants common stock + any registered debt for credit-spread analysis.

**Parameters:**
- `cusip6` (path, required): 6-character CUSIP issuer prefix (case-insensitive). Real public-domain examples: `037833` (Apple), `594918` (Microsoft), `02079K` (Alphabet — covers both GOOGL `02079K305` and GOOG `02079K107`), `084670` (Berkshire — covers both BRK-A `084670108` and BRK-B `084670702`). Returns 404 when no securities are registered to the prefix.

**Sample response:**
```json
{
  "cusip6": "084670",
  "issuer_name": "BERKSHIRE HATHAWAY INC",
  "securities": [
    {
      "cusip": "084670108",
      "ticker": "BRK-A",
      "issuer_name": "BERKSHIRE HATHAWAY INC",
      "security_group": "Stocks",
      "cik": "0001067983"
    },
    {
      "cusip": "084670702",
      "ticker": "BRK-B",
      "issuer_name": "BERKSHIRE HATHAWAY INC",
      "security_group": "Stocks",
      "cik": "0001067983"
    }
  ]
}
```

### GET /api/v1/cusip/search

Full-text search across CUSIP mappings. Searches CUSIP, ticker, and security name fields. Returns only valid (active) mappings with pagination.

**Token cost:** 1 token per call

**Response fields:**
- `results` (array): Array of matching catalog rows. Order: by relevance score DESC (exact ticker matches first, then exact CUSIP-prefix matches, then trigram name-similarity score). Empty array on no matches — does NOT 404.
- `results[].cusip` (string): 9-character CUSIP.
- `results[].ticker` (string (nullable)): Canonical hyphen-form ticker. Null for unmapped securities.
- `results[].issuer_name` (string): Issuer name (all-caps EDGAR convention).
- `results[].security_group` (string (nullable)): Security classification — `Stocks` / `ETFs` / `Preferred` / `Warrants` / `Debt` / `Other`.
- `results[].cusip6` (string): 6-character CUSIP issuer prefix.
- `results[].score` (number): Relevance score in range [0, 1] — exact ticker match scores 1.0, exact CUSIP match scores 0.95, name-trigram similarity scores from 0.30-0.85 depending on overlap. Useful for client-side post-filtering (e.g. drop results below 0.40 to suppress weak matches).
- `meta` (object): Pagination block: `{ total: integer, limit: integer, offset: integer, query: string }`. `total` is the full match count across all pages — use for pagination control rendering.

**Since:** v3.14.0

**Utility:** Full-text search across CUSIP / ticker / issuer-name fields — the right entrypoint for typeahead UIs that accept any of those three input shapes (e.g. user types `Apple` or `AAPL` or `037` and the search palette resolves all 3 into the same CUSIP). Built atop the same `cusip_security_catalog` (~26K rows) but with PostgreSQL trigram fuzzy matching on the issuer-name field. Returns only ACTIVE mappings (excludes superseded predecessors of corporate-action chains — for chain expansion use the dedicated [GET /api/v1/cusip/chain/{cusip}](/docs/reference-data/cusip-api/get-cusip-chain) entrypoint). Pagination via standard `limit + offset`.

**Use case:** Building a CUSIP search interface where users can type partial input across any of the three fields. Also useful in 'reconcile a customer's free-form security mention against our canonical catalog' workflows — given user input `tesla` or `tesla motors`, return TSLA / `88160R101` / `TESLA INC` for downstream pipeline use.

**Parameters:**
- `q` (query, required): Search query (matches CUSIP, ticker, or security name). Case-insensitive. Trigram fuzzy matching on the name field — `apple` matches `APPLE INC` AND `APPLE HOSPITALITY REIT`. CUSIP fragment matching is exact-prefix (so `037` matches `037833100` but `833` does not). Ticker matching is exact OR prefix on canonical hyphen form (`BRK` matches both `BRK-A` and `BRK-B`).
- `limit` (query, optional, default: 50): Max results returned (1-100). Server caps at 100 — values > 100 silently clamp to 100.
- `offset` (query, optional, default: 0): Pagination offset for chunked retrieval. Pair with `limit` for `total // limit` page count.

**Sample response:**
```json
{
  "results": [
    {
      "cusip": "037833100",
      "ticker": "AAPL",
      "issuer_name": "APPLE INC",
      "security_group": "Stocks",
      "cusip6": "037833",
      "score": 1
    },
    {
      "cusip": "03784Y200",
      "ticker": "APLE",
      "issuer_name": "APPLE HOSPITALITY REIT INC",
      "security_group": "Stocks",
      "cusip6": "03784Y",
      "score": 0.62
    }
  ],
  "meta": {
    "total": 2,
    "limit": 50,
    "offset": 0,
    "query": "apple"
  }
}
```

### GET /api/v1/cusip/stats

CUSIP database statistics: total CUSIPs, mapped (with ticker), unmapped (no ticker), with CIK, and overall mapping rate percentage.

**Token cost:** 5 tokens per call

**Response fields:**
- `total_cusips` (integer): Total row count in `cusip_security_catalog`. Grows with new SEC filings + OpenFIGI nightly enrichment runs. Typical value: ~26,000 post v3.11.0 expansion to 6 security groups (was ~7,968 prior to the v3.11.0 catalog-broadening).
- `mapped` (integer): Count of CUSIPs with a non-null ticker mapping. Without `OPENFIGI_API_KEY` set, expect ~76% mapped (CUSIPs resolved via SEC company-tickers.json + filing-derived enrichment). With the key set, climbs to >98%.
- `unmapped` (integer): Count of CUSIPs with null ticker (no public-equity ticker found). Includes debt securities, private placements, delisted issuers, and OpenFIGI-coverage-gap CUSIPs. Typical: ~24% without OpenFIGI key, ~2% with key.
- `with_cik` (integer): Count of CUSIPs with non-null SEC CIK mapping. Bridges to filing-history endpoints. Typical: ~94% (most CUSIPs in the catalog originate from SEC-registered issuers).
- `mapping_rate` (number): Convenience field — `round(mapped / total_cusips * 100, 1)` as a decimal percent (e.g. 76.4 means 76.4% of CUSIPs are ticker-mapped). Display-ready for dashboards.
- `by_security_group` (object): Count breakdown by security_group classification — `{ Stocks: integer, ETFs: integer, Preferred: integer, Warrants: integer, Debt: integer, Other: integer }`. The 6-bucket schema established in v3.11.0. Useful for verifying coverage across all security types after a catalog refresh.
- `openfigi_enabled` (boolean): `true` when `OPENFIGI_API_KEY` is set in the FinRadar environment (changes batch size from 10 -> 100 CUSIPs/batch and delay from 2.4s -> 0.24s — critical for 13F deadline-day batch enrichment). `false` otherwise — expect lower mapping_rate.
- `last_refresh_at` (string (nullable)): ISO-8601 UTC timestamp of the most-recent catalog refresh (nightly OpenFIGI enrichment + SEC company-tickers.json sync). Null on cold-start or if the refresh DAG has never completed.

**Since:** v3.14.0

**Utility:** CUSIP catalog health metrics in one call — total catalog size, OpenFIGI ticker-resolution rate, CIK-coverage rate, security-group breakdown. The right endpoint for admin dashboards monitoring data quality on the cusip_security_catalog and for surfacing enrichment regressions when an ETL run fails to populate a batch of new CUSIPs. Without `OPENFIGI_API_KEY` set the typical mapped-rate sits around 76%; with the key set it climbs to >98%. Pair with [GET /api/v1/status](/docs/resources/system-status/get-status) for cross-service health rollups.

**Use case:** Admin dashboard showing CUSIP mapping health — what percentage of CUSIPs have been resolved to tickers, how many have CIK mappings (for filing-history bridging), and the security-group distribution. Also useful for capacity planning ('we have 26K CUSIPs today, projecting 30K by end of year') and for SLA reporting to enterprise customers.

**Sample response:**
```json
{
  "total_cusips": 26080,
  "mapped": 25540,
  "unmapped": 540,
  "with_cik": 24515,
  "mapping_rate": 97.9,
  "by_security_group": {
    "Stocks": 8412,
    "ETFs": 3104,
    "Preferred": 1287,
    "Warrants": 482,
    "Debt": 11890,
    "Other": 905
  },
  "openfigi_enabled": true,
  "last_refresh_at": "2026-05-02T03:14:22Z"
}
```