Metrics API

GET/api/metrics/budgets

request access

List all defined budgets.

Request-tier read.

Permissions

HTTP request

GET https://<your-host>/api/metrics/budgets

Path parameters

This operation has no path parameters.

Query parameters

Request headers

Request body

This operation does not accept a request body.

Response

200 response body

Structure: Value.

Returns a paginated JSON object with total/limit/offset keys.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  'https://<your-host>/api/metrics/budgets'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "budgets": null,
  "durable": false,
  "total": null,
  "limit": null,
  "offset": null
}

POST/api/metrics/budgets

execute access

Define a budget threshold on a metric.

Execute-tier. 503 when no database is configured.

Permissions

HTTP request

POST https://<your-host>/api/metrics/budgets

Path parameters

This operation has no path parameters.

Query parameters

This operation has no query parameters.

Request headers

Request body

JSON structure: MetricBudgetCreateRequest.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request POST \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '{"metric_key":"<string>","threshold":0.0}' \
  'https://<your-host>/api/metrics/budgets'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "id": null,
  "created": false
}

GET/api/metrics/budgets/status

request access

Evaluate every ENABLED budget against its metric series, reporting current and projected breaches.

Request-tier read. 503 when no database is configured.

Permissions

HTTP request

GET https://<your-host>/api/metrics/budgets/status

Path parameters

This operation has no path parameters.

Query parameters

This operation has no query parameters.

Request headers

Request body

This operation does not accept a request body.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  'https://<your-host>/api/metrics/budgets/status'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "budgets": null,
  "breached_count": null,
  "errored_count": null,
  "overall_status": null
}

DELETE/api/metrics/budgets/{id}

execute access

Remove a budget definition (swarm #19, CRUD completion).

Execute-tier (same as create). 404 if absent; 503 no DB.

Permissions

HTTP request

DELETE https://<your-host>/api/metrics/budgets/{id}

Path parameters

Query parameters

This operation has no query parameters.

Request headers

Request body

This operation does not accept a request body.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request DELETE \
  --header 'Authorization: Bearer <token>' \
  --header 'Idempotency-Key: <idempotency-key>' \
  'https://<your-host>/api/metrics/budgets/<id>'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "deleted": null
}

PUT/api/metrics/budgets/{id}

execute access

Update a budget's mutable fields (threshold, comparison, enabled); omitted fields are left unchanged (PATCH semantics, swarm #19).

Execute-tier (same as create/delete). 404 if absent; 503 no DB. The identity/scope fields are immutable here — recreate to re-scope.

Permissions

HTTP request

PUT https://<your-host>/api/metrics/budgets/{id}

Path parameters

Query parameters

This operation has no query parameters.

Request headers

Request body

JSON structure: MetricBudgetUpdateRequest.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request PUT \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '{}' \
  'https://<your-host>/api/metrics/budgets/<id>'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "updated": null
}

GET/api/metrics/commitment

request access

Model the cost of a reserved/committed capacity level vs pure on-demand for a metric.

metric_key, on_demand_rate, commitment_rate, and committed_units are required; usage defaults to the metric's mean. Request-tier read. 503 when no database is configured.

Permissions

HTTP request

GET https://<your-host>/api/metrics/commitment

Path parameters

This operation has no path parameters.

Query parameters

Request headers

Request body

This operation does not accept a request body.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  'https://<your-host>/api/metrics/commitment'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "metric_key": null,
  "site": null,
  "environment": null,
  "usage_source": null,
  "model": null
}

GET/api/metrics/insights

request access

Anomaly + waste detection over one metric series (pure ryuki_engine::metric_anomaly).

metric_key is required; site/ environment scope the (single, coherent) series; z is the anomaly z-threshold; waste_threshold/waste_fraction configure waste detection. Request-tier read. 503 when no database is configured; 500 on a query error (never a falsely-empty result).

Permissions

HTTP request

GET https://<your-host>/api/metrics/insights

Path parameters

This operation has no path parameters.

Query parameters

Request headers

Request body

This operation does not accept a request body.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  'https://<your-host>/api/metrics/insights'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "metric_key": null,
  "site": null,
  "environment": null,
  "sample_count": null,
  "summary": null,
  "anomalies": null,
  "waste": null
}

POST/api/metrics/insights/generate

execute access

Run detection over a metric series and PERSIST the resulting suggestions into aiops_suggestions (the existing suggestion surface).

Execute-tier (it writes). Each suggestion is deduped: it is skipped when an OPEN (New/Reviewed) suggestion with the same site+title already exists, so repeated calls do not pile up duplicates. Returns the suggestions that were newly persisted. 503 when no database is configured.

Permissions

HTTP request

POST https://<your-host>/api/metrics/insights/generate

Path parameters

This operation has no path parameters.

Query parameters

Request headers

Request body

This operation does not accept a request body.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request POST \
  --header 'Authorization: Bearer <token>' \
  --header 'Idempotency-Key: <idempotency-key>' \
  'https://<your-host>/api/metrics/insights/generate'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "metric_key": null,
  "site": null,
  "generated": null,
  "persisted": null,
  "suggestions": null
}

POST/api/metrics/samples

execute access

Record one time-series metric sample.

Execute-tier (operators/collectors push samples). 503 when no database is configured.

Permissions

HTTP request

POST https://<your-host>/api/metrics/samples

Path parameters

This operation has no path parameters.

Query parameters

This operation has no query parameters.

Request headers

Request body

JSON structure: MetricSampleRequest.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request POST \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '{"metric_key":"<string>","value":0.0}' \
  'https://<your-host>/api/metrics/samples'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "id": null,
  "recorded": false
}

GET/api/metrics/series

request access

Return one metric's ordered series plus a summary, trend, and a linear forecast (pure ryuki_engine::metric_forecast).

metric_key is required; site/environment narrow the scope; horizon (default 3, capped 100) is the number of points to project. Request-tier read (metrics are non-sensitive aggregates). 503 when no database is configured.

Permissions

HTTP request

GET https://<your-host>/api/metrics/series

Path parameters

This operation has no path parameters.

Query parameters

Request headers

Request body

This operation does not accept a request body.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  'https://<your-host>/api/metrics/series'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "metric_key": null,
  "site": null,
  "environment": null,
  "series": null,
  "summary": null,
  "trend": null,
  "forecast": null
}

GET/api/metrics/series/aggregated

request access

Time-bucketed (hourly/daily/weekly/monthly) MIN/MAX/MEAN/COUNT rollups of a metric series for historical trend analysis.

Mirrors metrics_series's gating + #2 coherent-scope handling. Buckets are NON-EMPTY only (no gap filling); weekly is the ISO-8601 Monday-start week at UTC. request-tier (a metrics read). The scan is bounded to the last limit buckets' worth of time.

Permissions

HTTP request

GET https://<your-host>/api/metrics/series/aggregated

Path parameters

This operation has no path parameters.

Query parameters

Request headers

Request body

This operation does not accept a request body.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  'https://<your-host>/api/metrics/series/aggregated'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "metric_key": null,
  "granularity": null,
  "site": null,
  "environment": null,
  "buckets": null
}

GET/api/metrics/slo

request access

List SLO definitions.

Request-tier read.

Permissions

HTTP request

GET https://<your-host>/api/metrics/slo

Path parameters

This operation has no path parameters.

Query parameters

This operation has no query parameters.

Request headers

Request body

This operation does not accept a request body.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  'https://<your-host>/api/metrics/slo'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "slos": null,
  "durable": false
}

POST/api/metrics/slo

execute access

Define an SLO.

Execute-tier. 503 when no DB. good_metric_key/total_metric_key MUST be COUNTER-style event-count metrics — the status endpoint SUMs them over the window, which is only meaningful for additive samples (a gauge would produce nonsense compliance).

Permissions

HTTP request

POST https://<your-host>/api/metrics/slo

Path parameters

This operation has no path parameters.

Query parameters

This operation has no query parameters.

Request headers

Request body

JSON structure: SloCreateRequest.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request POST \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '{"name":"<string>","target":0.0,"good_metric_key":"<string>","total_metric_key":"<string>"}' \
  'https://<your-host>/api/metrics/slo'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "id": null,
  "created": false
}

GET/api/metrics/slo/status

request access

Evaluate every enabled SLO over its window (sum good/total from metric_samples, compute attainment + error-budget burn).

Request-tier. Alerting-safe: the one batch aggregate fails the request loud (never a false compliant), and a window with no events is insufficient-data.

Permissions

HTTP request

GET https://<your-host>/api/metrics/slo/status

Path parameters

This operation has no path parameters.

Query parameters

This operation has no query parameters.

Request headers

Request body

This operation does not accept a request body.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  'https://<your-host>/api/metrics/slo/status'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "slos": null,
  "breached_count": null,
  "errored_count": null,
  "overall_status": null
}

DELETE/api/metrics/slo/{id}

execute access

Remove an SLO definition (swarm #20, CRUD completion).

Execute-tier. 404 if absent; 503 no DB.

Permissions

HTTP request

DELETE https://<your-host>/api/metrics/slo/{id}

Path parameters

Query parameters

This operation has no query parameters.

Request headers

Request body

This operation does not accept a request body.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request DELETE \
  --header 'Authorization: Bearer <token>' \
  --header 'Idempotency-Key: <idempotency-key>' \
  'https://<your-host>/api/metrics/slo/<id>'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "deleted": null
}

PUT/api/metrics/slo/{id}

execute access

Update an SLO's mutable fields (name, target, window_days, enabled); omitted fields are left unchanged (PATCH semantics, swarm #20).

Execute-tier. 404 if absent; 503 no DB. The metric keys and scope are immutable here — recreate to re-target or re-scope.

Permissions

HTTP request

PUT https://<your-host>/api/metrics/slo/{id}

Path parameters

Query parameters

This operation has no query parameters.

Request headers

Request body

JSON structure: SloUpdateRequest.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request PUT \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '{}' \
  'https://<your-host>/api/metrics/slo/<id>'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "updated": null
}

GET/api/metrics/what-if

request access

Project a metric forward under a hypothetical growth factor and report whether/when it would breach a capacity/cost ceiling (pure ryuki_engine::metric_planning).

metric_key and ceiling are required. Request-tier read. 503 when no database is configured; 500 on a query error.

Permissions

HTTP request

GET https://<your-host>/api/metrics/what-if

Path parameters

This operation has no path parameters.

Query parameters

Request headers

Request body

This operation does not accept a request body.

Response

200 response body

Structure: Value.

Errors

JSON failures use one of the platform error envelopes and include the request correlation metadata when routing reaches the API middleware. See Errors for the exact shapes, authentication failures, retry guidance, and transport-level exceptions.

Examples

Request

curl --silent --show-error --globoff \
  --request GET \
  --header 'Authorization: Bearer <token>' \
  'https://<your-host>/api/metrics/what-if'

Schematic response body

Illustrative shape generated from the extracted field types, not a recorded live response. Values are placeholders; null marks a field whose type could not be resolved.

Success status: 200

{
  "metric_key": null,
  "site": null,
  "environment": null,
  "ceiling": null,
  "growth_factor": null,
  "breaches": null,
  "first_breach_at": null,
  "peak_projected": null,
  "headroom": null,
  "projected": null
}