Metrics & Catalog API

These endpoints cover reading metric series, the multidimensional fleet view, the metric catalog (definitions), metric sources, and platform system alerts. Concepts behind them are in Metrics & the Metric Catalog and Multidimensional (Fleet) Metrics.

Identifiers: metric definitions, sources, and bindings use integer id. Series, fleet, and binding routes that take {metricKey}/{id} for a metric use the string metric key.

Permissions: reads require CanViewAlerts; writes/tests require CanManageRules.

Metric series & catalog reads

`GET /api/metrics?q={text}&isEvaluable={bool}&page=1&pageSize=20`

Lists metrics from the unified metric catalog (not from adapter-specific sources). Backs lazy metric pickers such as the rule-builder metric autocomplete. q, isEvaluable, page, and pageSize are optional. Use isEvaluable=true when the caller needs only metrics that can be targeted by rules.

{
  "items": [
    {
      "id": "demo.api.response.duration.ms",
      "name": "API response duration",
      "unit": "ms",
      "managementMode": "EXTERNALLY_MANAGED",
      "catalogSource": "demo_seed",
      "dataStatus": "ACTIVE",
      "lastSyncedAt": "2026-06-02T08:00:00Z",
      "lastIngestedAt": "2026-06-02T09:00:00Z",
      "syncStatus": "SYNCED",
      "isEvaluable": true
    }
  ],
  "page": 1,
  "pageSize": 20,
  "totalCount": 1,
  "totalPages": 1,
  "hasPreviousPage": false,
  "hasNextPage": false
}

Field	Meaning
`id`	The metric key (string).
`dataStatus`	Data availability (see concept page).
`syncStatus`	Metadata freshness — independent of `dataStatus`.
`isEvaluable`	`true` only when local metric data is active. Rules can target only evaluable metrics.

`GET /api/metrics/{id}/series?from={iso}&to={iso}`

Returns the raw time series for a metric, read from the metric store by metric key. {id} is the string metric key, not a numeric ID.

[
  { "timestamp": "2026-06-02T09:00:00Z", "value": 214 },
  { "timestamp": "2026-06-02T09:01:00Z", "value": 208 }
]

`GET /api/metrics/{id}/fleet`

For a multidimensional metric, returns the fleet summary plus per-dimension peer standing and top deviators. Returns 404 if the metric is not multidimensional.

{
  "metricKey": "demo.http.requests.by_instance.per2m",
  "displayName": "HTTP requests by instance (mbl-web fleet)",
  "unit": "count",
  "timestamp": "2026-06-02T09:00:00Z",
  "dimensionCount": 40,
  "peerMedian": 1180,
  "min": 110,
  "max": 1320,
  "deviatingCount": 2,
  "dimensions": [
    {
      "dimensionKey": "mbl-web-07",
      "labels": { "instance": "mbl-web-07" },
      "value": 140,
      "peerMedian": 1180,
      "deviationPercent": -88.1,
      "robustZScore": -7.4,
      "isDeviating": true,
      "severity": "Critical",
      "direction": "Below"
    }
  ]
}

See Multidimensional (Fleet) Metrics for field semantics.

Metric Definitions (the catalog)

A metric definition is the catalog record for a metric key. The full object (MetricDefinitionDto) includes identity, metadata, ownership, collection config, entity linkage, lifecycle status, and (for multidimensional metrics) fleet settings.

`POST /api/metric-definitions`

Create a definition. Requires CanManageRules.

{
  "metricKey": "database.sessions.active",
  "displayName": "Active Database Sessions",
  "unit": "count",
  "metricType": "gauge",
  "namespace": "database",
  "managementMode": "LUMETRY_MANAGED",
  "metricSourceId": 3,
  "sourceQuery": "SELECT count(*) FROM v$session WHERE status = 'ACTIVE'",
  "pollingIntervalSeconds": 60,
  "pollingConfig": "{}",
  "entityType": "DATABASE",
  "entityIdentifier": "database/prod",
  "metadata": "{}"
}

Key request fields:

Field	Type	Notes
`metricKey`	string	Required. Stable identity; matches the stored `metric_name` series key.
`displayName`, `unit`	string	Required human metadata.
`metricType`	enum	Required. `gauge`, `counter`, or `histogram`.
`namespace`	string	Optional grouping.
`managementMode`	enum	`LUMETRY_MANAGED` or `EXTERNALLY_MANAGED`. Drives the rules below.
`metricSourceId`	int	Required for `LUMETRY_MANAGED`; null for externally managed.
`sourceQuery`	string	Required for `LUMETRY_MANAGED` — the query the collector runs.
`pollingIntervalSeconds`	int	Required & positive for `LUMETRY_MANAGED`.
`pollingConfig`	JSON string	Optional; must be valid JSON; defaults to the interval when omitted.
`entityType`	enum	`HOST`, `DATABASE`, `APPLICATION`, `SERVICE`, `KUBERNETES_CLUSTER`, `NAMESPACE`, `POD`, or `CUSTOM`.
`entityIdentifier`	string	Defaults to `metricKey` when omitted.
`metadata`	JSON string	Optional; must be valid JSON.
`metricMode`	enum	`single` or `multidimensional`. Defaults to `single`.
`dimensionKeys`	string[]	Expected label keys for a multidimensional metric, such as `["host.id"]`.
`analyses`	string[]	Enabled fleet analyses: `peer_deviation` and/or `baseline_deviation`. Empty disables fleet evaluation; unknown tokens are dropped.
`splitDimension`	string	The label key identifying a fleet member (e.g. `host.id`). Defaults to the first dimension key.
`scope`	JSON string	Label equality filter applied when building snapshots, e.g. `{"host.group":"mobil-web"}`. Defaults to `{}` (all series).
`minPeerCount`	int	Minimum number of dimensions needed before peer analysis is meaningful.
`maxCardinality`	int	Guardrail for the maximum number of dimensions in one snapshot.
`peerConfig`	JSON string	Optional peer-deviation settings. Defaults to `{}`.
`baselineConfig`	JSON string	Optional baseline-deviation settings (lookback weeks, band multiplier, minimum samples, direction). Defaults to `{}`.

Ownership rules enforced on write:

LUMETRY_MANAGED requires metricSourceId, sourceQuery, and a positive pollingIntervalSeconds. Lumetry runs the query on schedule and records the resulting points.
EXTERNALLY_MANAGED keeps metricSourceId/sourceQuery/polling fields null — data is expected to arrive via another pipeline. Source attribution is optional.

The response is the full MetricDefinitionDto, which additionally exposes metricSourceName, metricSourceType, sourceAdapter, and the resolved entityType/entityIdentifier, plus lifecycle fields dataStatus, syncStatus, syncError, lastSyncedAt, lastIngestedAt, and (for fleets) metricMode, dimensionKeys, analyses, splitDimension, scope, minPeerCount, maxCardinality, peerConfig, baselineConfig.

dataStatus and syncStatus are system-owned lifecycle fields, not user choices. dataStatus (owned by ingestion/collection) controls evaluability; syncStatus (owned by catalog sync) is metadata freshness only.

`GET /api/metric-definitions?namespace=&sourceAdapter=&isActive=&search=&dataStatus=&page=1&pageSize=50`

List definitions. All filters optional. search matches across metric key, display name, description, namespace, source adapter/name, entity fields, source query, and lifecycle fields. The response is paged with the same envelope shape used by GET /api/metrics.

`GET /api/metric-definitions/summary`

Returns aggregate metric-definition counts without loading metric rows.

{
  "totalCount": 1425,
  "dataStatusCounts": [
    { "status": "ACTIVE", "count": 980 },
    { "status": "STALE", "count": 22 }
  ]
}

`GET /api/metric-definitions/{id}`

Get one definition (integer id) with its topology bindings (MetricDefinitionWithBindingsDto).

`PUT /api/metric-definitions/{id}`

Update a definition by integer id. Same field semantics as create (minus metricKey, which is immutable identity).

`DELETE /api/metric-definitions/{id}`

Soft delete — sets isActive = false. The metric key and history are retained.

`POST /api/metric-definitions/bulk`

Upsert a batch of definitions (with optional bindings) by metricKey in one transaction. Intended for source-adapter / sync registration.

{ "createdCount": 3, "updatedCount": 5, "bindingsCreatedCount": 2 }

Catalog hygiene views

`GET /api/metric-definitions/activity/unregistered?lookbackMinutes=10&limit=500`

Metric names seen in the metric store within the lookback window that have no active definition — i.e. data flowing in that nobody has cataloged.

[
  {
    "metricKey": "demo.support.tickets.created.per5m",
    "namespace": "demo",
    "source": "demo_seed",
    "lastSeenAt": "2026-06-02T09:00:00Z",
    "pointCount": 120,
    "lastValue": 7,
    "lookbackMinutes": 10
  }
]

`GET /api/metric-definitions/activity/silent?lookbackMinutes=10`

Active definitions whose latest stored point is missing or older than the lookback window — cataloged metrics that have stopped reporting. Each row wraps the full definition plus lastSeenAt, pointCount, and lastValue.

Metric ↔ topology bindings

Method & path	Purpose
`POST /api/metric-definitions/{metricKey}/bindings`	Bind a metric (string key) to a topology node. Body: `{ "nodeId": 42, "bindingType": "emits" }`.
`DELETE /api/metric-definitions/{metricKey}/bindings/{nodeId}`	Remove a binding.
`GET /api/topology-nodes/{nodeId}/metrics`	List every definition bound to a node.

Bindings are unique per (metric, node) and are idempotent. They are what let alerts resolve a related service/CI — see Topology & CMDB.

Metric Sources

A metric source is a connection Lumetry can pull from for LUMETRY_MANAGED metrics. Reads require CanViewAlerts; writes/tests require CanManageRules.

Method & path	Purpose
`GET /api/metric-sources?sourceType=&enabled=&search=`	List sources.
`GET /api/metric-sources/{id}`	Get one.
`POST /api/metric-sources`	Create.
`PUT /api/metric-sources/{id}`	Update.
`DELETE /api/metric-sources/{id}`	Delete.
`POST /api/metric-sources/{id}/test-connection`	Validate connectivity only.
`POST /api/metric-sources/{id}/test-query`	Run a query and preview results.

Create/update fields

Field	Type	Notes
`name`	string	Required, unique.
`sourceType`	enum	`POSTGRES`, `MSSQL`, `MYSQL`, `ORACLE`, `PROMETHEUS`, or Prometheus-compatible `THANOS`. No database provider is the default.
`description`	string	Optional.
`enabled`	bool	Whether the source is active for collection/health checks.
`configReference`	string	Optional deployment-managed reference for non-secret config.
`credentialReference`	string	Optional deployment-managed reference for credentials. Availability depends on the deployment's credential policy.
`connectionConfig`	JSON string	Connection settings accepted by the selected source adapter. Follow your deployment's secret-handling policy.

The response also includes adapter-health fields: lastHealthCheckAt, lastHealthyAt, healthStatus (healthy / unhealthy / unknown), and lastHealthError.

POST /api/metric-sources/{id}/test-query

{ "query": "SELECT metric_value FROM operational_metrics WHERE metric_key = 'database.sessions.active'" }

Runs the provided query (or the source's configured test query). SQL adapters require one row with one numeric value; Prometheus/Thanos normalize scalar/vector/matrix results into preview rows. Results are returned in the response only and never persisted.

{
  "success": true,
  "message": "1 row returned.",
  "preview": [
    { "timestamp": "2026-06-02T09:00:00Z", "value": 128, "valueType": "scalar", "labels": {}, "rawValue": "128" }
  ]
}

System Alerts

`GET /api/system-alerts?status=Open`

Operator-facing platform alerts — for example, a metric source that became unhealthy. Distinct from operational (metric) alerts. Requires CanViewAlerts.

Metric series & catalog reads​

GET /api/metrics?q={text}&isEvaluable={bool}&page=1&pageSize=20​

GET /api/metrics/{id}/series?from={iso}&to={iso}​

GET /api/metrics/{id}/fleet​

Metric Definitions (the catalog)​

POST /api/metric-definitions​

GET /api/metric-definitions?namespace=&sourceAdapter=&isActive=&search=&dataStatus=&page=1&pageSize=50​

GET /api/metric-definitions/summary​

GET /api/metric-definitions/{id}​

PUT /api/metric-definitions/{id}​

DELETE /api/metric-definitions/{id}​

POST /api/metric-definitions/bulk​

Catalog hygiene views​

GET /api/metric-definitions/activity/unregistered?lookbackMinutes=10&limit=500​

GET /api/metric-definitions/activity/silent?lookbackMinutes=10​

Metric ↔ topology bindings​

Metric Sources​

System Alerts​

GET /api/system-alerts?status=Open​