---
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.

## Changes

- **2026-07-26** `996f96a11758` — 1 breaking, 16 info
  - the response property `total_persons_approx` became nullable for the status `200`
  - api operation id `getStats` was added
  - the endpoint scheme security `apiKey` was added to the API
  - the endpoint scheme security `bearerAuth` was added to the API
  - …13 more

[Change history](https://skmtc.dev/openmercantil/apis/openmercantil-public-api/changes/api/v1/stats/get.md)

---

[API](https://skmtc.dev/openmercantil/apis/openmercantil-public-api.md) · [All operations](https://skmtc.dev/openmercantil/apis/openmercantil-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/openmercantil/openmercantil-public-api/revisions/601ff6123c86/schema)