Data & Analytics

Data coverage / freshness introspection

Introspect what data the API covers BEFORE scanning: which states, lenders, and product types are present, row counts per segment, APR ranges, and last-updated freshness per segment. Extends the global /meta counts into a per-segment coverage matrix grouped by state, product type, or both. This route is the single source of truth; the MCP get_coverage tool calls it.

Authentication required: Pass your API key in the X-API-Key header.

post/v1/coverage

Request

  • Base URL: https://api.rateapi.dev
  • URL: https://api.rateapi.dev/v1/coverage
  • Auth: API key in header X-API-Key

Request body

group_by'state' | 'product' | 'state_product'

Segmentation axis for the matrix. Default 'state'.

product_category'mortgage' | 'auto' | 'heloc' | 'personal' | 'student' | 'credit_card'

Optional. Restrict the matrix to one product category. Omit for all.

statestring

Optional 2-letter US state code to scope the matrix to a single state.

freshness_daysinteger

Staleness window in days (clamped 1..90). Omit to use per-category freshness windows (recommended); supplying a value applies it uniformly to every category and is reported back as freshness_mode=override.

Example request

{
  "group_by": "state",
  "state": "CA",
  "freshness_days": 3
}

Response

Coverage matrix with per-segment counts and freshness.

generated_atstring nullable

MAX(scraped_at) overall, or null if empty.

freshness_daysinteger

The window supplied by the caller, or the fallback default when per-category windows applied.

freshness_mode'per_category' | 'override'

Which window applied: 'per_category' (each category used its own window; freshness_days is only the fallback) or 'override' (freshness_days applied uniformly).

next_actionsstring[]

Other endpoints or tools that are the natural next step from this result.

disclosuresstring[]

Statements that must be shown to a consumer alongside this result.

notestring

Plain-language explanation of what this result means.

Example response

{
  "institution_profiles": {
    "source": "NCUA quarterly call report"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.