Get the operational metrics snapshot

Returns a cheap JSON snapshot of the service, suitable for frequent scraping: it never processes fingerprints nor runs a health check. The traffic, saturation, latency and quality figures are accumulated in memory since the service started; the usage counters are the values of the license.

Block	Content
schemaVersion, timestamp	Payload version (1.0) and UTC instant of the snapshot
service	name (facephi-finger-service), version, role, pathBase (/api/v1/finger) and configuredThreads
state	initialized, license (valid, statusCode, statusMessage), engine (result of the last call to /health) and classification
traffic	Every request served, management endpoints included: totals, 1m/5m/15m windows and byEndpoint
saturation	inflight, maxInflight1m, configuredThreads, queueP95Ms1m and backlogSuspected
latency	Total, queue (queueMs) and processing (sdkMs) latency in milliseconds (avg, p50, p95, p99, max) per window
usage	License usage counters of the successful fingerprint operations: enabled, operations.extract, operations.authenticate and total
usageCountersEnabled, extractCount, authenticateCount, totalCount	The usage figures under the 2.1.0 field names
quality	Aggregated quality of the successful fingerprint operations
alerts	Active alerts

errorRate counts every 4xx and 5xx response, so validation rejections (HTTP 400) also increase it. A Negative authentication is returned with HTTP 200 and never counts as an error nor as a low-quality sample.

Alerts:

code	severity	message	Active when
LICENSE_EXPIRED	critical	License is invalid or expired	The license is not valid
ENGINE_UNAVAILABLE	critical	Fingerprint engine health check failed	The last call to /health failed to check the processing components
HIGH_ERROR_RATE	warning	5m error rate is above the warning threshold	The 5-minute error rate reaches metrics_error_rate_warning
SATURATED	warning	Queue latency and inflight indicate saturation	state.classification is saturated
LOW_QUALITY	warning	Recent fingerprint results show degraded quality	At least 20 extractions carry a quality figure, at least 20% of them had quality or nfiq2 below 50, and the last one of those happened within metrics_quality_alert_window_seconds
IDLE	info	Traffic is below the idle threshold	state.classification is idle

The classification thresholds (metrics_*) are configured in config.json, with the FACEPHI_FINGER_REST_METRICS_* environment variables or at runtime with POST /api/v1/finger/config. It never requires a JWT.

get

Responses

200

Operational metrics snapshot.

application/json

Operational metrics snapshot. See the operation description for the meaning of each block.

schemaVersionstringOptionalExample: 1.0

timestampstringOptional

UTC instant of the snapshot (YYYY-MM-DDTHH:MM:SSZ).

Example: 2026-09-30T10:21:00Z

usageCountersEnabledbooleanOptional

Same value as usage.enabled, kept for compatibility with 2.1.0.

Example: true

extractCountinteger · int64Optional

Same value as usage.operations.extract, kept for compatibility with 2.1.0.

Example: 12

authenticateCountinteger · int64Optional

Same value as usage.operations.authenticate, kept for compatibility with 2.1.0.

Example: 7

totalCountinteger · int64Optional

Same value as usage.total, kept for compatibility with 2.1.0.

Example: 19

400

The service is not initialized (Service not initialized).

application/json

get/api/v1/finger/metrics

GET /api/v1/finger/metrics HTTP/1.1
Host: 127.0.0.1:6982/
Accept: */*

{
  "schemaVersion": "1.0",
  "timestamp": "2026-09-30T10:21:00Z",
  "service": {
    "name": "facephi-finger-service",
    "version": "2.2.1",
    "role": "master",
    "pathBase": "/api/v1/finger",
    "configuredThreads": 1
  },
  "state": {
    "initialized": true,
    "license": {
      "valid": true,
      "statusCode": "LF_OK",
      "statusMessage": "The license is valid."
    },
    "engine": {
      "role": "master",
      "servicesConfigured": [
        "Master",
        "FingerTC",
        "Verifier"
      ],
      "healthy": true,
      "lastHealthKnown": true,
      "lastHealthCheckAt": "2026-09-30T10:20:30Z",
      "lastError": ""
    },
    "classification": "ok"
  },
  "traffic": {
    "totals": {
      "requests": 42,
      "success": 40,
      "clientErrors": 2,
      "serverErrors": 0,
      "unauthorized": 0
    },
    "windows": {
      "1m": {
        "requests": 6,
        "rps": 0.1,
        "successRate": 1,
        "errorRate": 0
      },
      "5m": {
        "requests": 30,
        "rps": 0.1,
        "successRate": 0.967,
        "errorRate": 0.033
      },
      "15m": {
        "requests": 42,
        "rps": 0.047,
        "successRate": 0.952,
        "errorRate": 0.048
      }
    },
    "byEndpoint": [
      {
        "method": "POST",
        "path": "/api/v1/finger/extract",
        "requests": 13,
        "success": 12,
        "clientErrors": 1,
        "serverErrors": 0,
        "unauthorized": 0
      }
    ]
  },
  "saturation": {
    "inflight": 1,
    "maxInflight1m": 1,
    "configuredThreads": 1,
    "queueP95Ms1m": 2,
    "backlogSuspected": false
  },
  "latency": {
    "scope": "global",
    "windows": {
      "1m": {
        "totalMs": {
          "avg": 118,
          "p50": 120,
          "p95": 160,
          "p99": 160,
          "max": 160
        },
        "queueMs": {
          "avg": 1,
          "p50": 1,
          "p95": 2,
          "p99": 2,
          "max": 2
        },
        "sdkMs": {
          "avg": 115,
          "p50": 118,
          "p95": 155,
          "p99": 155,
          "max": 155
        }
      }
    }
  },
  "usage": {
    "enabled": true,
    "operations": {
      "extract": 12,
      "authenticate": 7
    },
    "total": 19
  },
  "usageCountersEnabled": true,
  "extractCount": 12,
  "authenticateCount": 7,
  "totalCount": 19,
  "quality": {
    "extract": {
      "samples": 12,
      "measuredSamples": 12,
      "overallQuality": {
        "samples": 12,
        "avg": 81.5,
        "min": 42,
        "max": 96
      },
      "nfiq2": {
        "samples": 12,
        "avg": 74.2,
        "min": 38,
        "max": 91
      }
    },
    "authenticate": {
      "samples": 7,
      "positive": 6,
      "negative": 1,
      "similarity": {
        "samples": 7,
        "avg": 71.3,
        "min": 8.5,
        "max": 97
      }
    },
    "summary": {
      "lowQualitySamples": 1,
      "lowQualitySince": "2026-09-30T09:58:12Z"
    }
  },
  "alerts": []
}