> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/sdks/backend-sdk/iad/technical_documentation/api_reference/management/operational-metrics-snapshot.md).

# Operational metrics snapshot

Returns a cheap JSON snapshot with traffic, saturation, latency, usage, the last engine health check, the aggregated quality of the evaluations, the state classification and the active alerts. It only reads state already observed in memory and does not call the analysis engine, so it is suitable for frequent scraping.

* `state.engine` reflects the last analysis engine check made by the service; until the first one, `lastHealthKnown` is `false`.
* `traffic.windows.*.errorRate` counts every 4xx and 5xx response, including HTTP 400 rejections such as `NoneBecause*` or `Replay attack detected`. To classify the service and raise `HIGH_ERROR_RATE`, the 5-minute rate leaves out the captures rejected with `Replay attack detected`.
* Any 5xx response in the last 5 minutes, including the HTTP 503 answers of `GET /api/v1/iad/health` and of the capture endpoints, classifies the service as `degraded` when no condition with higher priority applies.
* The `metrics_*` thresholds decide `state.classification` and the alerts.

```json
{"openapi":"3.0.1","info":{"title":"IAD Service REST API","version":"3.0.0"},"tags":[{"name":"Management","description":"Service management and monitoring endpoints"}],"servers":[{"url":"http://127.0.0.1:6982/"}],"security":[],"paths":{"/api/v1/iad/metrics":{"get":{"summary":"Operational metrics snapshot","description":"Returns a cheap JSON snapshot with traffic, saturation, latency, usage, the last engine health check, the aggregated quality of the evaluations, the state classification and the active alerts. It only reads state already observed in memory and does not call the analysis engine, so it is suitable for frequent scraping.\n\n- `state.engine` reflects the last analysis engine check made by the service; until the first one, `lastHealthKnown` is `false`.\n- `traffic.windows.*.errorRate` counts every 4xx and 5xx response, including HTTP 400 rejections such as `NoneBecause*` or `Replay attack detected`. To classify the service and raise `HIGH_ERROR_RATE`, the 5-minute rate leaves out the captures rejected with `Replay attack detected`.\n- Any 5xx response in the last 5 minutes, including the HTTP 503 answers of `GET /api/v1/iad/health` and of the capture endpoints, classifies the service as `degraded` when no condition with higher priority applies.\n- The `metrics_*` thresholds decide `state.classification` and the alerts.\n","operationId":"getMetrics","tags":["Management"],"responses":{"200":{"description":"Current operational metrics snapshot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationalMetricsResponse"}}}},"400":{"description":"The service is not initialized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResult"}}}}}}}},"components":{"schemas":{"OperationalMetricsResponse":{"type":"object","description":"Cheap operational snapshot for observability and scraping. It only reads state already observed in memory and does not call the analysis engine.","properties":{"schemaVersion":{"type":"string"},"service":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"},"pathBase":{"type":"string"},"configuredThreads":{"type":"integer"}}},"state":{"type":"object","properties":{"initialized":{"type":"boolean"},"license":{"type":"object","properties":{"valid":{"type":"boolean"}}},"engine":{"$ref":"#/components/schemas/EngineHealthSnapshot"},"classification":{"type":"string","description":"Summary of the service state according to the `metrics_*` thresholds.","enum":["ok","idle","degraded","saturated","unhealthy","unknown"]}}},"traffic":{"type":"object","description":"Every request handled by the service, management requests included.","properties":{"totals":{"$ref":"#/components/schemas/TrafficCounters"},"windows":{"type":"object","properties":{"1m":{"$ref":"#/components/schemas/TrafficWindow"},"5m":{"$ref":"#/components/schemas/TrafficWindow"},"15m":{"$ref":"#/components/schemas/TrafficWindow"}}},"byEndpoint":{"type":"array","description":"One entry per endpoint that has already received requests.","items":{"$ref":"#/components/schemas/EndpointTraffic"}}}},"saturation":{"type":"object","properties":{"inflight":{"type":"integer"},"maxInflight1m":{"type":"integer"},"configuredThreads":{"type":"integer"},"queueP95Ms1m":{"type":"integer"},"backlogSuspected":{"type":"boolean"}}},"latency":{"type":"object","properties":{"scope":{"type":"string"},"windows":{"type":"object","properties":{"1m":{"$ref":"#/components/schemas/LatencyWindow"},"5m":{"$ref":"#/components/schemas/LatencyWindow"},"15m":{"$ref":"#/components/schemas/LatencyWindow"}}}}},"usage":{"type":"object","description":"Business operations handled since startup. Management endpoints (`/health`, `/version`, `/config` and `/metrics`) are excluded.","properties":{"enabled":{"type":"boolean"},"total":{"type":"integer"},"operations":{"type":"object","description":"Requests per operation, keyed by `\"<METHOD> <path>\"`. Only operations that have already received requests appear.","additionalProperties":{"type":"integer"}}}},"quality":{"$ref":"#/components/schemas/QualityMetrics"},"alerts":{"type":"array","items":{"$ref":"#/components/schemas/MetricsAlert"}}}},"EngineHealthSnapshot":{"type":"object","description":"Result of the last analysis engine check made by the service, which `GET /api/v1/iad/health` runs and reuses for up to `engine_health_max_age_seconds`.","properties":{"healthy":{"type":"boolean","description":"Whether the last check succeeded."},"lastHealthKnown":{"type":"boolean","description":"Whether the service has checked the analysis engine since startup. It is `false` until the first check."},"lastHealthCheckAt":{"type":"string","description":"UTC instant of the last check, in `%Y-%m-%dT%H:%M:%SZ` format. Empty until the first check."},"lastError":{"type":"string","description":"Reason of the last failed check, for example `Connection failed`, `Request timeout`, `Engine is unhealthy (503)` or `Engine process ended`. Empty when the last check succeeded. A license that is not valid is not recorded here."}}},"TrafficCounters":{"type":"object","properties":{"requests":{"type":"integer","description":"Requests handled."},"success":{"type":"integer","description":"Responses with a 2xx status."},"clientErrors":{"type":"integer","description":"Responses with a 4xx status, including HTTP 400 rejections and HTTP 401."},"serverErrors":{"type":"integer","description":"Responses with a 5xx status."},"unauthorized":{"type":"integer","description":"Responses with HTTP 401 (also counted in `clientErrors`)."}}},"TrafficWindow":{"type":"object","properties":{"requests":{"type":"integer"},"rps":{"type":"number","description":"Requests per second over the window."},"successRate":{"type":"number","description":"Fraction of 2xx responses."},"errorRate":{"type":"number","description":"Fraction of 4xx and 5xx responses."},"clientErrors":{"type":"integer","description":"Responses with a 4xx status within the window, HTTP 401 included."},"serverErrors":{"type":"integer","description":"Responses with a 5xx status within the window, including the HTTP 503 answers of `GET /api/v1/iad/health` and of the capture endpoints."},"unauthorized":{"type":"integer","description":"Responses with HTTP 401 within the window (also counted in `clientErrors`)."}}},"EndpointTraffic":{"allOf":[{"$ref":"#/components/schemas/TrafficCounters"},{"type":"object","properties":{"method":{"type":"string"},"path":{"type":"string"}}}]},"LatencyWindow":{"type":"object","properties":{"totalMs":{"$ref":"#/components/schemas/LatencyStats"},"queueMs":{"$ref":"#/components/schemas/LatencyStats"},"sdkMs":{"$ref":"#/components/schemas/LatencyStats"}}},"LatencyStats":{"type":"object","description":"Latency in milliseconds.","properties":{"avg":{"type":"integer"},"p50":{"type":"integer"},"p95":{"type":"integer"},"p99":{"type":"integer"},"max":{"type":"integer"}}},"QualityMetrics":{"type":"object","description":"Aggregated quality of the `/evaluate` and `/evaluate/custom` evaluations since the service started. The block is an empty object until the first evaluation or the first capture the analysis engine could not evaluate. `detection` appears with the first successful evaluation, and `summary` appears as soon as the block is not empty.\n\nAn `Attack` verdict is the service detecting an attack, not a low-quality sample, so it never raises `LOW_QUALITY` nor degrades the classification, even when it comes with low scores.\n","properties":{"detection":{"type":"object","properties":{"samples":{"type":"integer","description":"Successful evaluations aggregated."},"noAttack":{"type":"integer","description":"Evaluations with the `NoAttack` verdict."},"attack":{"type":"integer","description":"Evaluations with the `Attack` verdict."},"probability":{"$ref":"#/components/schemas/NumericSummary"},"score":{"$ref":"#/components/schemas/NumericSummary"},"faceProbability":{"$ref":"#/components/schemas/NumericSummary"}}},"summary":{"type":"object","properties":{"lowQualitySamples":{"type":"integer","description":"Captures the analysis engine could not evaluate (`NoneBecause*` errors, such as `NoneBecauseFaceNotFound`). It does not include `Attack` verdicts nor captures rejected with `Replay attack detected`."},"lowQualitySince":{"type":"string","description":"Start of the low-quality episode that keeps the `LOW_QUALITY` alert active. Only present once a capture could not be evaluated."}}}}},"NumericSummary":{"type":"object","description":"Aggregated summary of a score reported by the analysis, on a 0 to 1 scale.","properties":{"samples":{"type":"integer"},"avg":{"type":"number"},"min":{"type":"number"},"max":{"type":"number"}}},"MetricsAlert":{"type":"object","properties":{"code":{"type":"string","enum":["LICENSE_EXPIRED","ENGINE_UNAVAILABLE","HIGH_ERROR_RATE","SATURATED","LOW_QUALITY","IDLE"]},"severity":{"type":"string","enum":["critical","warning","info"]},"message":{"type":"string"},"since":{"type":"string","description":"UTC instant associated with the alert. For `LOW_QUALITY`, the start of the low-quality episode; for `ENGINE_UNAVAILABLE`, the last failed analysis engine check; for the other alerts, the time of the snapshot."}}},"BadRequestResult":{"type":"object","description":"The request is not valid, the capture could not be processed, or the license of the service is not valid.","properties":{"status":{"type":"number"},"error":{"type":"string"},"message":{"type":"string","description":"Service error message or error normalized by Facephi.","oneOf":[{"$ref":"#/components/schemas/FacephiErrorMessage"},{"type":"string"}]},"timeStamp":{"$ref":"#/components/schemas/TimeStamp"}}},"FacephiErrorMessage":{"type":"string","description":"Documented public error messages returned in HTTP 400 responses.\n\n- Capture that the analysis engine could not evaluate (the three capture endpoints): `NoneBecause*` values.\n- Capture rejected by the experimental replay mitigation (the three capture endpoints): `Replay attack detected`.\n- Unclassified failure of the analysis engine: `ErrorProcessing` (`POST /api/v1/iad/evaluate` and `POST /api/v1/iad/evaluate/custom`) or `ErrorFacialImage` (`POST /api/v1/iad/extract`).\n- License that stopped being valid while the service runs (the three capture endpoints): `Invalid license: <reason> (code: <code>)`. The capture is not analyzed.\n- Request validation on the three capture endpoints: `Empty multipart payload`, `Required multipart field 'capture' not found` and `Empty data in multipart field 'capture'`.\n- Request validation specific to `POST /api/v1/iad/evaluate/custom`: the `pipeline` and `calibration` messages.\n- Service not ready: `Service not initialized` and `Service not configured`.\n\nWhen the analysis engine does not respond, the capture endpoints answer HTTP 503 with `Engine communication error:` followed by the detail (see `ServiceUnavailableResult`). `GET /api/v1/iad/health` answers HTTP 503 when the service cannot handle evaluations.\n","enum":["NoneBecauseFaceTooClose","NoneBecauseFaceNotFound","NoneBecauseFaceTooSmall","NoneBecauseAngleTooLarge","NoneBecauseImageDataError","NoneBecauseLicenseError","NoneBecauseTooManyFaces","NoneBecauseFaceTooCloseToBorder","NoneBecauseFaceCropped","NoneBecauseFaceOccluded","NoneBecauseEyesClosed","Replay attack detected","ErrorProcessing","ErrorFacialImage","Empty multipart payload","Required multipart field 'capture' not found","Empty data in multipart field 'capture'","Required multipart field 'pipeline' not found","Invalid value for 'pipeline'; expected 'iad_r01' or 'iad_r00'","Invalid value for 'calibration'; expected 'regular' or 'hardened'","Service not initialized","Service not configured"]},"TimeStamp":{"type":"string","description":"UTC date and time in `%Y-%m-%dT%H:%M:%SZ` format (second precision)."}}}}
```