---
title: "Get latest verification state and sweep coverage"
method: GET
path: "/api/v1/freshness"
---

# Get latest verification state and sweep coverage

`GET /api/v1/freshness`

## Request

- Base URL: `https://andrewsfreebies.com`
- URL: `https://andrewsfreebies.com/api/v1/freshness`
- Auth: none declared

Returns the latest official audit event for non-directory trials and redeemable savings with incorporated first-party catalog evidence, plus current/overdue/unchecked cadence coverage, historical attempted coverage, explicit evidence-resolution groups, outcome counts, per-item due times, and observed heartbeat recency. Directory-only leads and public services remain available through record search, fetch, and verification history but are excluded from this actionable-currentness denominator. Current means checked inside cadence, not confirmed; supporting evidence means the latest outcome is confirmed-exact or confirmed-partial. Provide record_type and record_id together to scope totals and items to one exact record while retaining global scheduler-operation fields.

## Query parameters

- `record_type` 'trial' | 'entitlement'
- `record_id` string
- `outcome` 'confirmed-exact' | 'confirmed-partial' | 'terms-changed' | 'explicitly-expired' | 'moved' | 'blocked' | 'fetch-error' | 'not-found' | 'unknown': Conservative field-level audit result. blocked, fetch-error, not-found, and unknown do not establish expiration.
- `limit` integer

## Response `200`

Latest-state freshness projection

- FreshnessResponse: Latest official verification event per actionable candidate, on-schedule coverage, explicit evidence resolution, and observed scheduler heartbeat recency. Record catalog status remains separate from audit outcome.
  - `api_version` '2.1', required
  - `catalog_scope` string, required: Non-directory trials and redeemable savings with incorporated first-party catalog evidence; directory-only leads and public-service records are excluded.
  - `filters` object, required
  - `totals` object, required
    - `catalog_records` integer: Backward-compatible count of records inside catalog_scope, not the complete public catalog.
    - `records_checked` integer: Records with at least one accepted official verification event.
    - `records_current` integer: Records still inside their published verification cadence; current does not mean confirmed.
    - `records_overdue` integer
    - `records_unchecked` integer
    - `records_with_supporting_evidence` integer: Records whose latest official outcome is confirmed-exact or confirmed-partial.
    - `coverage_percent` number: Current records divided by catalog records; this is cadence coverage, not a confirmation rate.
    - `attempted_coverage_percent` number: Records checked at least once divided by catalog records.
    - `supporting_evidence_percent` number: Records with confirmed-exact or confirmed-partial latest evidence divided by catalog records.
  - `by_freshness` object, required
    - `current` integer
    - `overdue` integer
    - `unchecked` integer
  - `by_evidence_resolution` object, required: Mutually exclusive evidence groups across the current actionable catalog.
    - `supporting` integer: confirmed-exact plus confirmed-partial.
    - `review_alert` integer: terms-changed, explicitly-expired, moved, or not-found; requires review and never automatically rewrites the catalog.
    - `inconclusive` integer: blocked, fetch-error, or unknown; establishes neither validity nor expiration.
    - `unchecked` integer
  - `by_outcome` object, required: Counts for all nine conservative outcomes.
  - `evidence_resolution_interpretation` string, required
  - `oldest_checked_at` string, date-time, nullable
  - `newest_checked_at` string, date-time, nullable
  - `operations` object, required
    - `policy_version` string
    - `heartbeat_target_hours` number
    - `heartbeat_alert_after_hours` number
    - `latest_run_completed_at` string, date-time, nullable
    - `latest_heartbeat_completed_at` string, date-time, nullable: Latest heartbeat of any origin, including manual checks.
    - `latest_scheduled_heartbeat_completed_at` string, date-time, nullable: Latest heartbeat produced by the configured scheduler.
    - `heartbeat_basis` 'scheduled'
    - `heartbeat_age_hours` number, nullable: Age of the latest scheduler-origin heartbeat.
    - `heartbeat_status` 'awaiting-first-run' | 'on-schedule' | 'late': Scheduler liveness; manual heartbeats cannot make this on-schedule.
  - `items` VerificationEvent[], required: Verification events include a schedule object with status, cadence_days, and due_at.
    - `record_id` string, required
    - `record_type` 'trial' | 'entitlement', required
    - `category` string: Optional; when present it must match the canonical record category.
    - `url` string, uri, required
    - `url_role` string, required
    - `checked_at` string, date-time: Defaults to generated_at.
    - `method` string: Defaults to run.method.
    - `outcome` 'confirmed-exact' | 'confirmed-partial' | 'terms-changed' | 'explicitly-expired' | 'moved' | 'blocked' | 'fetch-error' | 'not-found' | 'unknown', required: Conservative field-level audit result. blocked, fetch-error, not-found, and unknown do not establish expiration.
    - `content_hash` string
    - `evidence_excerpt` string
    - `matched_fields` string[]
    - `unmatched_fields` string[]
    - `url_health` object, required: Structured status, redirect, and reachability observations.
    - `offer_existence` object, required: Structured evidence for whether the provider currently describes the offer.
    - `terms_match` object, required: Matched, unmatched, and contradicted normalized fields.
    - `redemption_path` object, required: Structured activation, application, or claim-path result.
    - `evidence_quality` object, required: Evidence ownership, authority, and sufficiency.
    - `freshness` object, required: Audit age and next-check scheduling fields.
    - `id` string, uuid
    - `run_id` string, uuid
    - `created_at` string, date-time
    - `run` object
      - `schema_version` string
      - `generated_at` string, date-time
      - `method` string
      - `verifier` string, nullable
      - `started_at` string, date-time
      - `completed_at` string, date-time
  - `policy` string, required: The latest-state projection is review evidence and never automatically changes the catalog.

## Other responses

- `400`: Invalid filter
- `503`: Verification ledger unavailable

---

[API](https://skmtc.dev/andrewsfreebies/apis/andrew-s-freebies-api.md) · [All operations](https://skmtc.dev/andrewsfreebies/apis/andrew-s-freebies-api/llms.txt) · [OpenAPI document](https://skmtc.dev/andrewsfreebies/apis/andrew-s-freebies-api/revisions/2e23a7a12f7a?raw)