---
title: "How Patricia is used, in counts"
method: GET
path: "/v1/admin/usage"
tags: ["admin"]
---

# How Patricia is used, in counts

`GET /v1/admin/usage`

## Request

- Base URL: `https://api.patricia.app` (the document declares no server; this is the origin it was published from)
- URL: `https://api.patricia.app/v1/admin/usage`
- Auth: HTTP bearer

Return the label tallies for the window, split into every run and scored replies.

The window itself is bounded at 366 days and every run inside it is counted. Retention narrows
the COVERAGE pair only, which starts at ``coverage_since`` — scorecards are pruned on each
workspace's own schedule while runs are not, so a ratio reaching further back would read a
deletion as an ungraded reply.

## Query parameters

- `since` string, date-time, nullable
- `until` string, date-time, nullable
- `team_id` string, uuid, nullable

## Response `200`

Successful Response

- AdminUsageResponse: Every number the page draws, for one window, in one response.
  - `since` string, date-time, required
  - `until` string, date-time, required
  - `total_runs` integer, required
  - `scored_replies` integer, required
  - `replies_with_topic` integer, required: Scorecards that carry a topic — the topic chart's own denominator, not scored_replies.
  - `active_teams` integer, required: Workspaces with at least one run in the window, not the customer count.
  - `coverage_since` string, date-time, required: Where the coverage pair starts: no earlier than the shortest scorecard retention in scope.
  - `coverage_eligible_runs` integer, required: Runs the judge could have graded, since coverage_since.
  - `coverage_scored_replies` integer, required: Runs it actually graded, since coverage_since.
  - `weekly_runs` UsageWeek[], required
    - `week_start` string, date-time, required
    - `count` integer, required
  - `runs_by_trigger` UsageCount[], required
    - `code` string, required
    - `count` integer, required
  - `runs_by_source_kind` UsageCount[], required
    - `code` string, required
    - `count` integer, required
  - `replies_by_type` UsageCount[], required
    - `code` string, required
    - `count` integer, required
  - `replies_by_outcome` UsageCount[], required
    - `code` string, required
    - `count` integer, required
  - `replies_by_complexity` UsageCount[], required
    - `code` string, required
    - `count` integer, required
  - `replies_by_tool_use` UsageCount[], required: Whether a tool ran at all. Which tool is not recorded online, so it is not counted here.
    - `code` string, required
    - `count` integer, required
  - `replies_by_topic` UsageCount[], required: The subject a reply was about. Divide by replies_with_topic, not scored_replies.
    - `code` string, required
    - `count` integer, required

## Other responses

- `401`: Unauthorized
- `422`: Validation error

---

[API](https://skmtc.dev/patricia/apis/patricia-api.md) · [All operations](https://skmtc.dev/patricia/apis/patricia-api/llms.txt) · [OpenAPI document](https://skmtc.dev/patricia/apis/patricia-api/revisions/0dfb44495ea1?raw)