---
title: "Validate Ecm Endpoint"
method: POST
path: "/ecm/validate"
tags: ["ecm-project"]
---

# Validate Ecm Endpoint

`POST /ecm/validate`

Validate a fitted ECM on held-out data (synchronous, no fit, no pipeline).

Re-simulates the fitted model forward on the held-out current using the same
engine ``POST /ecm/fit`` runs internally, then returns model-vs-data traces
and RMSE/MAE/Max voltage error.

## Request body

- ValidateECMRequest — Request body for validating a fitted ECM against a held-out trace. Provide exactly one held-out data source (``measurement_id`` or ``example_id``) and exactly one model source (``fit_results`` or ``parameterized_model_id``). The model is re-simulated forward on the held-out current — no fit and no pipeline — and compared to the held-out voltage.
  - `measurement_id` string, nullable — Held-out cell measurement to validate against.
  - `example_id` string, nullable — Built-in example dataset id to validate against.
  - `start_step` integer, nullable — Optional inclusive start step (measurement only).
  - `end_step` integer, nullable — Optional inclusive end step (measurement only).
  - `initial_soc` number, nullable — Known SOC (0–1) at the start of the held-out trace. When omitted it is recovered from the trace's first voltage via the fitted OCV(SOC) curve (assumes the trace starts near rest).
  - `capacity` number, nullable — Cell capacity [Ah] for the SOC integration. Defaults to the fit/model capacity (the SOC reference the curves were fitted against); it is never re-estimated from the held-out trace.
  - `fit_results` FitResultsData — Fit results needed for saving (and re-simulating for validation).
    - `soc` number[], required
    - `ocv` number[], required
    - `r0` number[], required
    - `rc_pairs` RcPairFitData[]
      - `r` number[], required
      - `c` number[], required
      - `tau` number[], required
    - `capacity_Ah` number[], nullable — Cell capacity used to integrate SOC, one entry per measurement segment. An estimated or fitted capacity is a single cell-wide value repeated across segments (a separate capacity is not estimated per trace); entries differ only when a per-measurement ``capacity`` is supplied. Required for validation — it is the SOC reference the curves were fitted against and is never re-estimated from the held-out trace. Save/validate use one capacity per model/trace, so the per-segment values must agree.
  - `parameterized_model_id` string, nullable — Saved ECM parameterized model to re-simulate.

## Response `200`

Successful Response

- ValidateECMResponse — Held-out validation result: error metrics + downsampled overlay traces.
  - `rmse_mV` number, required — Root-mean-square voltage error [mV].
  - `mae_mV` number, required — Mean absolute voltage error [mV].
  - `max_mV` number, required — Maximum absolute voltage error [mV].
  - `num_rcs` integer, required — RC-pair count of the validated model.
  - `capacity_Ah` number[], required — Capacity used for SOC integration [Ah] (single-element list).
  - `initial_soc` number, required — Initial SOC used for the held-out trace.
  - `model_source` string, required — Where the validated model came from.
  - `time` number[], required — Downsampled time grid [s].
  - `data_voltage` number[], required — Held-out measured voltage [V].
  - `model_voltage` number[], required — Re-simulated model voltage [V].
  - `residual_mV` number[], required — Model − data voltage residual [mV].

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/ionworks/apis/fastapi.md) · [All operations](https://skmtc.dev/ionworks/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ionworks/fastapi/revisions/7337a3cbdaf2/schema)