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, 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. When ticker enrichment is disabled the typical mapped-rate sits around 76%; when enabled 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 ticker-enrichment enablement state. The natural admin-dashboard rollup for the cusip_security_catalog. Mapping rate variance is significant: when ticker enrichment is disabled, expect ~76% mapped (CUSIPs resolved purely via SEC company-tickers.json + filing-derived enrichment); when enabled, climbs to >98% via broad 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 + nightly ticker-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. When ticker enrichment is disabled, expect ~76% mapped (CUSIPs resolved via SEC company-tickers.json + filing-derived enrichment). When enabled, climbs to >98%.
unmappedintegernoCount of CUSIPs with null ticker (no public-equity ticker found). Includes debt securities, private placements, delisted issuers, and ticker-enrichment-coverage-gap CUSIPs. Typical: ~24% when disabled, ~2% when enabled.
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 ticker enrichment is enabled in the FinRadar environment (larger batch size and lower per-request delay — 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 ticker 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).