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.

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

Returns historical minute-bucketed member series for a multidimensional metric. Supply from and to; optionally narrow the members with a JSON scope, override member identity with splitBy, and cap the returned series with seriesLimit (1–50). The response includes totalMemberCount plus series[], where each series contains its stable member, latest representative labels, and raw timestamp/value points. Use POST /api/rules/preview when you need the selected rule's expected band and violation state over the same history.

`GET /api/metrics/{id}/fleet/baseline-series`

Returns the same historical member-series shape with each point evaluated against that member's stored seasonal baseline. Supply from and to; optional scope narrows the members, seriesLimit caps the response at 1–50 series, and dimension keeps one requested member in the response even when it falls outside that cap. This endpoint always uses the metric definition's member identity because those are the members for which baselines are maintained. Each point includes expected, lower, upper, and isViolation from the same baseline quality and threshold policy used by live Baseline Deviation detection.

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​

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

GET /api/metrics/{id}/fleet/baseline-series​

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​