Certificate Counts

GET /api/v1/certificates/counts

Return grouped certificate counts by status, optionally scoped to a county slug and/or tax year. Useful for dashboards and for sizing a paginated search sweep before you run it.

Authentication

curl -H "X-API-Key: fltc_test_..." \
  "https://fltaxcerts.com/api/v1/certificates/counts?county=polk&tax_year=2023"

Query Parameters

Name	Type	Required	Default	Description
county	string	no	—	County slug to scope the counts.
tax_year	integer	no	—	Tax year to scope the counts.

Response (200)

Object envelope { data, meta }. data echoes the applied scope (county, tax_year — null when not set) and an array of { status, count } buckets ordered by descending count.

{
  "data": {
    "county": "polk",
    "tax_year": 2023,
    "counts": [
      { "status": "sold", "count": 18452 },
      { "status": "redeemed", "count": 9210 },
      { "status": "available", "count": 4880 },
      { "status": "tax_deed_applied", "count": 1740 },
      { "status": "lands_available", "count": 612 },
      { "status": "advertised", "count": 240 },
      { "status": "cancelled", "count": 86 }
    ]
  },
  "meta": { "request_id": "req_1234567890abcdef12345", "dataset_status": "live" }
}

The status buckets are the seven certificate states: available, advertised, sold, redeemed, lands_available, tax_deed_applied, and cancelled.

Error Responses

Status	Code	Cause
401	unauthorized	Missing or invalid API key.
429	rate_limited	Rate limit exceeded.
500	internal_error	Server error — retry with backoff.