Cycles

Appearance

Query the event stream​

GET
/v1/admin/events

Returns paginated events with filtering by type, category, tenant, scope, and time range. This is the canonical event log — all events that triggered (or would have triggered) webhooks are queryable here.
USE CASES: - Debug why a webhook fired (or didn't fire) - Reconstruct event history for a scope - Build custom integrations without webhooks (poll-based) - Audit trail supplement (events are more granular than audit logs)
RETENTION: - Same as audit log retention (recommended: 90 days hot, 1 year cold).

Authorizations​

AdminKeyAuth

Administrative API key with full system access. Also accepted as an alternative to ApiKeyAuth on an explicit per-operation allowlist — the authoritative list is the union of operations whose security: block declares AdminKeyAuth (consult per-operation security blocks rather than this prose, which has historically drifted as the dual-auth surface expanded). When using AdminKeyAuth on list or fund endpoints, a tenant scoping parameter (typically tenant or tenant_id) is required for scoping (400 if missing) — the per-operation description specifies which. Lookup-style endpoints that uniquely identify a resource by non-tenant key (e.g. GET /v1/admin/budgets/lookup, where the (scope, unit) pair is unique) do NOT require a tenant parameter. Allowlisting is per-operation (exact method:path matching — no prefix matching, no wildcards) so new endpoints do not accidentally inherit admin-accessible status.

Type
API Key (header: X-Admin-API-Key)

Parameters​

Query Parameters

tenant_id
Type
string
event_type

Filter by specific event type

Type
string
Valid values
"budget.created""budget.updated""budget.funded""budget.debited""budget.reset""budget.reset_spent""budget.debt_repaid""budget.frozen""budget.unfrozen""budget.closed""budget.threshold_crossed""budget.exhausted""budget.over_limit_entered""budget.over_limit_exited""budget.debt_incurred""budget.burn_rate_anomaly""reservation.denied""reservation.denial_rate_spike""reservation.expired""reservation.expiry_rate_spike""reservation.commit_overage""tenant.created""tenant.updated""tenant.suspended""tenant.reactivated""tenant.closed""tenant.settings_changed""webhook.created""webhook.updated""webhook.paused""webhook.resumed""webhook.disabled""webhook.deleted""api_key.created""api_key.revoked""api_key.expired""api_key.permissions_changed""api_key.auth_failed""api_key.auth_failure_rate_spike""policy.created""policy.updated""policy.deleted""system.store_connection_lost""system.store_connection_restored""system.high_latency""system.webhook_delivery_failed""system.webhook_test"
category

Filter by event category

Type
string
Valid values
"budget""tenant""api_key""policy""reservation""system""webhook"
scope

Filter by scope path (prefix match)

Type
string
correlation_id

Filter by correlation ID to find related events

Type
string
trace_id

Filter by exact trace_id. 32 lowercase hex characters (W3C Trace Context trace-id). Narrows the event stream to events belonging to a single logical operation (may span multiple HTTP requests, so typically yields MORE rows than a request_id filter). When combined with other filters, AND-composed. Additive parameter — servers that don't recognize it MUST ignore without error (additive-parameter guarantee). See CORRELATION AND TRACING in cycles-protocol-v0.yaml.

Type
string
Pattern
"^[0-9a-f]{32}$"
request_id

Filter by exact request_id. Narrows the event stream to events emitted as side effects of a single HTTP request. When combined with other filters, AND-composed. Complements trace_id for debug scenarios like "show me all events emitted by this specific API call" (e.g., the fan-out from a bulk-action endpoint). Additive parameter — servers that don't recognize it MUST ignore without error (additive-parameter guarantee).

Type
string
from
Type
string
Format
"date-time"
to
Type
string
Format
"date-time"
search

Free-text case-insensitive substring match. Matches across: correlation_id, scope. Combined with other filter params using AND semantics. Additive parameter — servers that don't recognize it MUST ignore without error (additive-parameter guarantee). Empty string MUST be treated as absent. Max length 128 characters; longer values MUST be rejected with HTTP 400.

Type
string
Max Length
128
sort_by

Sort key. When provided, results are returned in the requested order and the returned cursor encodes the sort key so "Load more" continues in sort order. When omitted, servers use their existing default ordering. Servers that don't recognize the parameter MUST ignore it without error (additive-parameter guarantee).

Type
string
Valid values
"event_type""category""scope""tenant_id""timestamp"
Default
"timestamp"
sort_dir

Sort direction. Default descending.

Type
string
Valid values
"asc""desc"
Default
"desc"
cursor
Type
string
limit
Type
integer
Minimum
1
Maximum
100
Default
50

Responses​

Event list

application/json
JSON
{
  
"events": [
  
  
{
  
  
  
"event_id": "string",
  
  
  
"event_type": "string",
  
  
  
"category": "string",
  
  
  
"timestamp": "string",
  
  
  
"tenant_id": "string",
  
  
  
"scope": "string",
  
  
  
"actor": {
  
  
  
  
"type": "string",
  
  
  
  
"key_id": "string",
  
  
  
  
"source_ip": "string"
  
  
  
},
  
  
  
"source": "string",
  
  
  
"data": {
  
  
  
  
"additionalProperties": "string"
  
  
  
},
  
  
  
"correlation_id": "string",
  
  
  
"request_id": "string",
  
  
  
"trace_id": "string",
  
  
  
"metadata": {
  
  
  
  
"additionalProperties": "string"
  
  
  
}
  
  
}
  
],
  
"next_cursor": "string",
  
"has_more": true
}

Playground​

Authorization
Variables
Key
Value

Samples​

Powered by VitePress OpenAPI