---
title: "Published public-dataset counters"
method: GET
path: "/api/v1/stats"
tags: ["System"]
---

# Published public-dataset counters

`GET /api/v1/stats`

Return the number of legal entities actually published in the active company_public_v2 sidecar, plus an optional offline person-mention approximation. It never exposes the raw 2.8M-row companies population and never runs a request-path COUNT. Sidecar unavailability is 503, not a zero/null company count.

## Headers

- `If-None-Match` string

## Response `200`

Stats response

- object
  - `total_companies` integer, required — company_public_projection_state.row_count for the active bundle
  - `total_persons_approx` integer, nullable, required
  - `person_count_source` 'person_public_v1' | 'null', nullable, required — Null means person authority unavailable; never reinterpret as zero.
  - `person_public_source_generation` string, nullable, required
  - `built_at` string, date-time, required
  - `timestamp` string, date-time, required
  - `version` '1.2', required
  - `count_source` 'company_public_v2', required

## Other responses

- `304` — The company-public generation and bounded statistics representation have not changed.
- `429` — Rate limit exceeded
- `503` — The public read failed closed because its legal source catalog, subject classification, bounded projection, database helper or required artifact is unavailable. Clients must not infer an empty result.

---

[API](https://skmtc.net/openmercantil/apis/openmercantil-public-api.md) · [All operations](https://skmtc.net/openmercantil/apis/openmercantil-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openmercantil/openmercantil-public-api/versions/996f96a11758/schema)