Skip to content
/api/v1/cusip/stats

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

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

5 tokensSince v3.14.0

Why use this

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.

Common 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.

CUSIP catalog health metrics in one call — total catalog size, ticker-resolution rate (mapped vs unmapped), CIK-coverage rate, security-group distribution, and OpenFIGI enablement state. The natural admin-dashboard rollup for the cusip_security_catalog. Mapping rate variance is significant: without OPENFIGI_API_KEY set, expect ~76% mapped (CUSIPs resolved purely via SEC company-tickers.json + filing-derived enrichment); with the key set, climbs to >98% via OpenFIGI's ~100M+ security-master coverage. The 6-bucket security_group breakdown (Stocks / ETFs / Preferred / Warrants / Debt / Other) reflects the v3.11.0 catalog-broadening from ~7,968 equity-only CUSIPs to ~26K all-types CUSIPs (Issue #241). Pair with GET /api/v1/status for cross-service health rollups and with GET /api/v1/stats for platform-wide volume metrics.

Response schema

FieldTypeNullableDescription
total_cusipsintegernoTotal 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).
mappedintegernoCount 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%.
unmappedintegernoCount 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_cikintegernoCount 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_ratenumbernoConvenience 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_groupobjectnoCount 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_enabledbooleanno`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_atstringyesISO-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.

Sample response

·
  • "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"
}

Errors

StatusLabelDescription
200OKRequest succeeded.
400Bad RequestInvalid query, body, or path parameter.
401UnauthorizedMissing or invalid Authorization header / api_Token.
402Payment RequiredInsufficient token balance for this call. Top up
429Too Many RequestsRate limit exceeded for your tier (see /pricing for tier limits). Tier limits
500Server ErrorUnexpected server-side failure. Retry with backoff; report if persistent.

Code samples

curl "https://api.finradar.ai/api/v1/cusip/stats?api_Token=YOUR_API_KEY" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Generate an API key in /account/credentials to run live queries (literal YOUR_API_KEY placeholder shown until then).