Monitoring

Get Usage Stats

Changed on

Return detailed usage statistics for the monitoring overview.

get/monitoring/usage

Request

  • Base URL: / (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /monitoring/usage
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL /authorize, token URL /oauth/token)

Query parameters

sinceinteger nullable

Start of the window in Unix epoch seconds (inclusive); defaults to 24 hours before until.

Example:1767225600
untilinteger nullable

End of the window in Unix epoch seconds (exclusive); defaults to the next minute boundary after now.

Example:1769903999
group_by'api' | 'toolkit' | 'credential' | 'agent'

Grouping dimension for usage statistics.

TOOLKIT is a legacy axis: it groups over the surviving execution_records.toolkit_id attribution column, which nothing writes since the toolkit path was deleted (theme-5 Phase 6b). It stays so historical dashboards keep working; CREDENTIAL is the live consumer axis (execution records carry credential_id since Phase 2).

Dimension to group the top rows by; defaults to api.

top_limitinteger

Maximum number of top rows to return (1-50, default 10).

Example:10
toolkit_idstring nullable

Legacy: only count executions mediated by this toolkit.

Example:tk_6968b3981ec22d56dbbc91e8
api_idstring nullable

Only count executions of this API, given as vendor/name.

Example:stripe.com/stripe
agent_idstring nullable

Only count executions run by this actor ID.

Example:agnt_6968b3984d1c238dbe7e2e29
statusstring nullable

Only count executions with this status, e.g. completed or failed.

Example:completed

Response

Successful Response

bucket_secondsinteger required

Width of each entry in buckets, in seconds; chosen from the window length.

group_bystring required

Dimension the top rows are grouped by.

sinceinteger required

Start of the window, in Unix epoch seconds (inclusive).

untilinteger required

End of the window, in Unix epoch seconds (exclusive).

Example response

{
  "bucket_seconds": 86400,
  "buckets": [
    {
      "avg_ms": 231.4,
      "failed": 2,
      "success": 40,
      "total": 42,
      "ts": 1767225600
    }
  ],
  "group_by": "api",
  "since": 1767225600,
  "stats": {
    "active_now": 0,
    "avg_ms": 245.6,
    "failed": 80,
    "p50_ms": 180,
    "p95_ms": 720,
    "pending": 0,
    "success": 1200,
    "total": 1280
  },
  "top": [
    {
      "avg_ms": 212.8,
      "failed": 12,
      "key": "stripe.com/stripe",
      "label": "Stripe",
      "success": 330,
      "total": 342,
      "trend": [
        40,
        52,
        47,
        61,
        58,
        84
      ]
    }
  ],
  "until": 1769903999
}

Changes