---
title: "Leads Fill Rates"
method: GET
path: "/api/v1/leads/fill_rates"
tags: ["leads", "leads"]
---

# Leads Fill Rates

`GET /api/v1/leads/fill_rates`

## Request

- Base URL: `https://app.goodleads.club` (the document declares no server; this is the origin it was published from)
- URL: `https://app.goodleads.club/api/v1/leads/fill_rates`
- Auth: API key in header `X-API-Key`

The Nutrition Label for the whole data set: per field, how many records have it filled.

The delivery file's Nutrition Label counts its own rows; this counts every record we
hold, keyed by the column name a buyer sees. `fields[].pct` is filled / records;
`fields[].source` says where it was counted (lead_browse column, entity_attribute, or
contact_attribute). `not_a_property` lists delivery-time names with nothing stored to
count; `not_measured` lists stored fields this endpoint does not count yet, with the
reason — so an absence is never read as a zero.

Two numbers per field. `filled` / `pct` follow the delivery file's rule: a stored
value that is not null and not blank (a placeholder such as `unclassified` ships in
the file, so it counts), except `has_phone` / `has_email`, which count TRUE only (a
stored false means "not found"). `known` / `known_pct` is `filled` minus the placeholder
vocabulary the filter grammar already treats as missing (`FIELD_SENTINELS`:
unclassified, llm_unclassifiable, unknown, OTHER) — a real answer — and equals the
filter `exists` count. Stored keys that feed a delivery column (e.g. `status_canonical`)
are also listed under their own name with `shipped:false` and `also_feeds`.

Counts only — no record values, no contact data — so it is identical at both access
tiers. Served from the in-process cache only (never computed on a request, the
2026-09-22 OOM rule): `age_seconds` / `stale` date it, `202 computing` means this
process has not finished its first sweep.

## Query parameters

- `state` string, nullable: State code (e.g. CO). Omit for all states combined (ALL).
- `shipped_only` boolean: Only the columns a delivery file carries. Default also lists every stored field the file holds back.
- `by_state` boolean: Attach each field's fill percent in every state (`pct_by_state`).
- `fresh` boolean: Ask the background warmer to recompute soon. Never computes in the request path; the response is the last snapshot.

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/goodleads/apis/formation-gtm-api.md) · [All operations](https://skmtc.dev/goodleads/apis/formation-gtm-api/llms.txt) · [OpenAPI document](https://skmtc.dev/goodleads/apis/formation-gtm-api/revisions/2068d13a82cf?raw)