---
title: "Trace usage aggregations — bucketed counts and top groups"
method: GET
path: "/traces/usage"
tags: ["observe"]
---

# Trace usage aggregations — bucketed counts and top groups

`GET /traces/usage`

Aggregate execution traces in a time window for monitoring dashboards.

The endpoint serves three pieces of information in one round-trip:

1. `stats` — totals, success/failed split, mean and p50/p95 latency, and a
   point-in-time count of in-flight async jobs. Powers the HealthStrip.
2. `buckets` — equally-sized time slices for stacking success/failed bar
   charts. Bucket width is chosen by the server based on the window:
   windows ≤ 1h use 60s buckets, ≤ 24h use 1h buckets, anything bigger
   uses 1d buckets. We never return more than ~144 buckets.
3. `top` — the top N groups (toolkits, agents or API hosts) by trace count.

All filters compose with AND semantics on top of the tenant scope.

## Query parameters

- `since` number, nullable — Window start (unix seconds, inclusive). Defaults to 24h ago.
- `until` number, nullable — Window end (unix seconds, exclusive). Defaults to now.
- `group_by` string — What to group the `top` list by: 'toolkit' | 'api' | 'agent'.
- `top_limit` integer — Maximum rows in `top` list (1–50)
- `toolkit_id` string, nullable — Filter to one toolkit before aggregating
- `agent_id` string, nullable — Filter to one agent before aggregating
- `api_id` string, nullable — Filter by upstream API. Exact match against the indexed `api_id` column on executions (catalog-form `apis.id`, e.g. `stripe.com`). Same semantics as `/traces?api_id=`.
- `status` string, nullable — Filter to a single status before aggregating

## Response `200`

Successful Response

- UsageResponse — Aggregated trace usage for the Monitor page (HealthStrip + bar chart + breakdown).
  - `since` number, required — Window start (unix seconds)
  - `until` number, required — Window end (unix seconds)
  - `bucket_seconds` integer, required — Width of one bucket in seconds (chosen by server)
  - `group_by` string, required — Grouping for the `top` list: 'toolkit' | 'api' | 'agent'
  - `stats` UsageStats, required — High-level trace counts and latency for a single time window.
    - `total` integer, required — Number of traces in window
    - `success` integer, required — Traces with status=success
    - `failed` integer, required — Traces with status=failed
    - `pending` integer — Traces still in flight (status=pending)
    - `avg_ms` number, nullable — Mean duration in milliseconds (success+failed)
    - `p50_ms` number, nullable — Median duration in milliseconds
    - `p95_ms` number, nullable — 95th percentile duration in milliseconds
    - `active_now` integer — Snapshot count of in-flight async jobs (status pending or running) at query time — not bound by the [since,until) window.
  - `buckets` UsageBucket[] — Time-bucketed counts
    - `ts` number, required — Unix-second start of the bucket
    - `total` integer, required — Total traces in bucket
    - `success` integer, required — Successful traces in bucket
    - `failed` integer, required — Failed traces in bucket
    - `avg_ms` number, nullable — Mean duration in this bucket
  - `top` UsageTopRow[] — Top groups by total traces, descending. Capped at `limit`.
    - `key` string, required — Group key — toolkit_id, agent_client_id, or api host (depending on group_by)
    - `label` string, nullable — Human-readable label for the row. For `group_by=agent` this is the agent's `client_name`; for `group_by=api` it is `apis.name` when the API is registered in the catalog (null otherwise — the frontend falls back to rendering `key`). For `group_by=toolkit` the label is null (toolkit ids are already human-readable slugs).
    - `total` integer, required — Total traces in this row
    - `success` integer, required — Successful traces
    - `failed` integer, required — Failed traces
    - `avg_ms` number, nullable — Mean duration
    - `trend` integer[], nullable — Compact time-series of trace counts for this row across the window, aligned to a fixed number of equally-sized buckets (12 by default). Used to render per-row sparklines on the Monitor page Breakdown table. Independent of the top-level `buckets` field — this one always has the same length regardless of window size, while `buckets` width is chosen by the server.

## Other responses

- `422` — Validation Error

## Changes

- **2026-06-08** `0d76c7617aae` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/jentic/apis/jentic-control-plane-api/changes/traces/usage/get.md)

---

[API](https://skmtc.dev/jentic/apis/jentic-control-plane-api.md) · [All operations](https://skmtc.dev/jentic/apis/jentic-control-plane-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/jentic/jentic-control-plane-api/revisions/0d76c7617aae/schema)