Trace usage aggregations — bucketed counts and top groups

Aggregate execution traces in a time window for monitoring dashboards.

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

stats — totals, success/failed split, mean and p50/p95 latency, and a point-in-time count of in-flight async jobs. Powers the HealthStrip.
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.
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.

sincenumber nullable

Window start (unix seconds, inclusive). Defaults to 24h ago.

untilnumber nullable

Window end (unix seconds, exclusive). Defaults to now.

group_bystring

What to group the top list by: 'toolkit' | 'api' | 'agent'.

top_limitinteger

Maximum rows in top list (1–50)

toolkit_idstring nullable

Filter to one toolkit before aggregating

agent_idstring nullable

Filter to one agent before aggregating

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

statusstring nullable

Filter to a single status before aggregating

Response

Successful Response

sincenumber required

Window start (unix seconds)

untilnumber required

Window end (unix seconds)

bucket_secondsinteger required

Width of one bucket in seconds (chosen by server)

group_bystring required

Grouping for the top list: 'toolkit' | 'api' | 'agent'

Example response

{
  "since": 1699913600,
  "until": 1700000000,
  "bucket_seconds": 3600,
  "group_by": "toolkit",
  "stats": {
    "total": 1234,
    "success": 980,
    "failed": 20,
    "avg_ms": 412.3,
    "p50_ms": 210,
    "p95_ms": 1800,
    "active_now": 3
  },
  "buckets": [
    {
      "ts": 1700000000,
      "total": 42,
      "success": 40,
      "failed": 2,
      "avg_ms": 395
    }
  ],
  "top": [
    {
      "key": "api.github.com",
      "label": "GitHub",
      "total": 500,
      "success": 490,
      "failed": 10,
      "avg_ms": 320,
      "trend": [
        3,
        5,
        2,
        8,
        11,
        7,
        4,
        6,
        9,
        5,
        3,
        7
      ]
    }
  ]
}

Trace usage aggregations — bucketed counts and top groups

Query parameters

Response

Example response

Changes