---
title: "Usage Stats"
method: GET
path: "/api/v1/stats/usage"
tags: ["stats"]
---

# Usage Stats

`GET /api/v1/stats/usage`

## Request

- Base URL: `https://api.billcommons.org`
- URL: `https://api.billcommons.org/api/v1/stats/usage`
- Auth: none declared

Aggregate MCP tool usage. Public, because the honest number is the point.

This exists because "is anyone using this?" was unanswerable. Over one log
window the MCP server served 139 successful POSTs and exactly ONE tool
call: everything else connected, listed the tools, and disconnected --
directory health probers, not researchers. Connections are not usage, and
only tool CALLS distinguish them.

Published rather than kept private: a project whose pitch is that it
refuses to dress up what it does not know should not quietly sit on its own
adoption numbers. Aggregate only -- no IP, no query text, no bill ids.

Our own read-path monitor calls a real tool every two minutes, on purpose:
a handshake succeeds against a dead database, so nothing cheaper detects
the outage that prompted it. That makes it ~720 synthetic calls a day, and
for the first hours of this table's life it was 61 of 63 rows. Those calls
are tagged at the MCP edge and excluded here, and the count we subtracted
is reported as `self_probe_calls` so the arithmetic is checkable.

## Query parameters

- `days` integer

## Response `200`

Successful Response

- UsageStatsOut: Aggregate MCP tool usage. Counts CALLS, not connections. A directory health prober connects, lists the tools and disconnects -- that is not usage, and conflating the two is how a project convinces itself it has adoption it does not have.
  - `window_days` integer, required
  - `total_tool_calls` integer, required
  - `tools` ToolUsageRow[], required
    - `tool` string, required
    - `ok` integer
    - `error` integer
    - `median_ms` integer, nullable
  - `error_codes` object, required
  - `self_probe_calls` integer
  - `note` string, required
  - `meta` object, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/billcommons/apis/bill-commons-api.md) · [All operations](https://skmtc.dev/billcommons/apis/bill-commons-api/llms.txt) · [OpenAPI document](https://skmtc.dev/billcommons/apis/bill-commons-api/revisions/bfb8cd50a317?raw)