---
title: "Aggregate run/usage stats"
method: GET
path: "/v1/runs-stats"
tags: ["usage"]
---

# Aggregate run/usage stats

`GET /v1/runs-stats`

## 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/runs-stats`
- Auth: HTTP bearer

Tenant-scoped run/usage aggregate over a UTC window: a zero-filled timeline, window totals (runs, credits, terminal-only success rate; tokens for internal callers), a by-source split, and, when `compare` is set, the prior window's totals. Usage is reported in credits (metered COGS → whole credits); the raw dollar figure is never surfaced. `start` and `end` are required, timezone-aware ISO-8601 (normalized to UTC); `end` must be after `start` and the window must not exceed 366 days (else 422). Requires `usage:read`.

## Query parameters

- `start` string, date-time, required: Window start (inclusive). Required, timezone-aware ISO-8601; normalized to UTC.
- `end` string, date-time, required: Window end (exclusive). Required, timezone-aware ISO-8601; normalized to UTC.
- `granularity` 'day' | 'week' | 'month': Timeline bucket size. Each bucket's ``date`` is its truncated UTC start (``week`` → Monday, ``month`` → the 1st).
- `compare` 'previous' | 'same_last_month' | 'same_last_year': Prior-window selector that populates ``previous_totals`` for period-over-period deltas.

## Headers

- `X-Tenant-Id` string, nullable

## Response `200`

Successful Response

- RunStatsResponse: Aggregate run/usage stats for a tenant over a UTC date window.
  - `timeline` RunStatsBucket[], required: Per-period buckets, zero-filled across the whole window.
    - `date` string, date-time, required: Truncated UTC start of the period (midnight; Monday for week, 1st for month).
    - `runs` integer, required: Runs created in this period.
    - `credits` integer, required: Credits consumed in this period (metered COGS converted to whole credits).
    - `tokens` integer, required: Summed input + output tokens for this period (internal/admin; dashboard uses credits).
    - `by_source` RunStatsBucketSource[], required: Per-source credit split of this bucket; empty on a zero-filled period. Slices sum to `credits`.
      - `source` string, required: Run trigger code (mention / dm / message / cron / heartbeat / …).
      - `runs` integer, required: Runs from this source in this bucket.
      - `credits` integer, required: Sum of this source's per-run whole credits in the bucket; source slices sum to the bucket's `credits`.
  - `totals` RunStatsTotals, required: Window totals for the KPI cards. ``success_rate`` is computed over **terminal** runs only (``completed`` / ``failed`` / ``cancelled`` / ``denied_autonomous``) as the percentage that ``completed``. It is ``null`` until at least one run in the window has reached a terminal state. A run the authority model refused counts in the denominator: it finished without succeeding, so excluding it would flatter the rate.
    - `runs` integer, required: Total runs created in the window.
    - `credits` integer, required: Total credits consumed in the window (metered COGS → whole credits), the headline usage metric.
    - `total_tokens` integer, required: Total input + output tokens across runs (internal/admin; the dashboard shows credits).
    - `success_rate` number, nullable, required: Percentage (0–100) of terminal runs that completed successfully; null when no run has finished.
  - `by_source` RunStatsSourceSlice[], required: Split by run source, most runs first.
    - `source` string, required: Run trigger code (mention / dm / message / cron / heartbeat / …).
    - `runs` integer, required: Runs created from this source in the window.
    - `credits` integer, required: Credits consumed by this source (metered COGS converted to whole credits).
    - `tokens` integer, required: Summed input + output tokens for this source (internal/admin; dashboard uses credits).
  - `previous_totals` RunStatsTotals, required: Window totals for the KPI cards. ``success_rate`` is computed over **terminal** runs only (``completed`` / ``failed`` / ``cancelled`` / ``denied_autonomous``) as the percentage that ``completed``. It is ``null`` until at least one run in the window has reached a terminal state. A run the authority model refused counts in the denominator: it finished without succeeding, so excluding it would flatter the rate.
    - `runs` integer, required: Total runs created in the window.
    - `credits` integer, required: Total credits consumed in the window (metered COGS → whole credits), the headline usage metric.
    - `total_tokens` integer, required: Total input + output tokens across runs (internal/admin; the dashboard shows credits).
    - `success_rate` number, nullable, required: Percentage (0–100) of terminal runs that completed successfully; null when no run has finished.

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden. Inspect response body `code` for the specific reason (for example: PERMISSION_DENIED, EMAIL_NOT_VERIFIED, TENANT_ACCESS_REQUIRED, ROLE_UNRESOLVED)
- `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)