> ## Documentation Index
> Fetch the complete documentation index at: https://develop.cotality.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data freshness and coverage

> Refresh cadence, historical depth, and geographic coverage for each Cotality data asset — so agents and developers set correct date ranges and expectations.

## Why this page exists

Time-sensitive workflows fail when code assumes data that doesn't exist yet, or requests
history that doesn't go back far enough. This page gives the **refresh cadence, history
depth, and coverage** for each asset so agents set correct temporal parameters.

## Freshness at a glance

| Data asset                   | Refresh cadence                                                        | Historical depth                                 | Coverage                                                  |
| ---------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------- |
| **Property characteristics** | On public-record update (varies by county — typically weeks to months) | Current snapshot + multi-year assessment history | \~99.9% of U.S. residential and commercial properties     |
| **Market and HPI**           | **Monthly**                                                            | Multi-year historical + forward HPI forecasts    | U.S. residential, aggregated at ZIP → state               |
| **Climate and peril risk**   | Annual model updates                                                   | Current scores + **30-year** forecast horizon    | Property-level; peril coverage varies by model and region |
| **Age of roof**              | Periodic (imagery-driven updates)                                      | Current estimate only — no historical series     | U.S. residential; commercial coverage limited             |
| **Transactions and liens**   | As recorded by county                                                  | Multi-year                                       | Where public records are digitally available              |

<Info>
  Platform context: **1M+ data points refreshed monthly**, **30 years** of historical
  trends, and **22,000+** verified property and public-record sources. Per-asset rows above
  take precedence for any specific call.
</Info>

## Rules for time-aware tool calls

<Steps>
  <Step title="Match granularity to cadence">
    Monthly assets (Market, HPI) take month-level `YearMonth` ranges. Never request daily or
    real-time values — the data does not exist at that granularity.
  </Step>

  <Step title="Omit time_range for latest data">
    For analytics tools, omit `time_range` entirely to retrieve the latest available period.
    Do not pass a partial object — both `from` and `to` are required when `time_range` is present.
  </Step>

  <Step title="Distinguish actual vs. forecast">
    HPI forecasts and 30-year climate projections are model projections, not observations.
    Always label them as forecasts or estimates when presenting to users.
  </Step>

  <Step title="Check the envelope messages">
    Freshness notes and partial-coverage warnings surface in the `messages` array of the
    [response envelope](/reference/response-envelope). Always read these.
  </Step>
</Steps>

## Geographic granularity by asset

| Data asset               | Property | ZIP | County | CBSA | State |
| ------------------------ | -------- | --- | ------ | ---- | ----- |
| Property characteristics | ✓ (CLIP) | —   | —      | —    | —     |
| Climate and peril risk   | ✓ (CLIP) | —   | —      | —    | —     |
| Age of roof              | ✓ (CLIP) | —   | —      | —    | —     |
| Market trends            | —        | ✓   | ✓      | ✓    | ✓     |
| Listing trends           | —        | ✓   | ✓      | ✓    | ✓     |
| Rental trends            | —        | ✓   | ✓      | ✓    | ✓     |
| HPI                      | —        | ✓   | ✓      | ✓    | ✓     |
| HPI forecasts            | —        | ✓   | ✓      | ✓    | ✓     |

<Warning>
  Exact cadence, depth, and coverage can vary by region, entitlement tier, and data source
  availability. Confirm the current values with your Cotality account team for time-critical
  or compliance-driven integrations.
</Warning>