> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Validate Ecm Endpoint

> 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.



## OpenAPI

````yaml https://api.ionworks.com/openapi.json post /ecm/validate
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers:
  - url: https://api.ionworks.com
    description: Production
security: []
paths:
  /ecm/validate:
    post:
      tags:
        - ecm-project
      summary: Validate Ecm Endpoint
      description: >-
        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.
      operationId: validate_ecm_endpoint_ecm_validate_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateECMRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateECMResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ValidateECMRequest:
      properties:
        measurement_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Measurement Id
          description: Held-out cell measurement to validate against.
        example_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Example Id
          description: Built-in example dataset id to validate against.
        start_step:
          anyOf:
            - type: integer
            - type: 'null'
          title: Start Step
          description: Optional inclusive start step (measurement only).
        end_step:
          anyOf:
            - type: integer
            - type: 'null'
          title: End Step
          description: Optional inclusive end step (measurement only).
        initial_soc:
          anyOf:
            - type: number
              maximum: 1
              minimum: 0
            - type: 'null'
          title: Initial Soc
          description: >-
            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:
          anyOf:
            - type: number
              exclusiveMinimum: 0
            - type: 'null'
          title: Capacity
          description: >-
            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:
          anyOf:
            - $ref: '#/components/schemas/FitResultsData'
            - type: 'null'
          description: In-memory fit results to re-simulate.
        parameterized_model_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Parameterized Model Id
          description: Saved ECM parameterized model to re-simulate.
      type: object
      title: ValidateECMRequest
      description: |-
        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.
    ValidateECMResponse:
      properties:
        rmse_mV:
          type: number
          title: Rmse Mv
          description: Root-mean-square voltage error [mV].
        mae_mV:
          type: number
          title: Mae Mv
          description: Mean absolute voltage error [mV].
        max_mV:
          type: number
          title: Max Mv
          description: Maximum absolute voltage error [mV].
        num_rcs:
          type: integer
          title: Num Rcs
          description: RC-pair count of the validated model.
        capacity_Ah:
          items:
            type: number
          type: array
          title: Capacity Ah
          description: Capacity used for SOC integration [Ah] (single-element list).
        initial_soc:
          type: number
          title: Initial Soc
          description: Initial SOC used for the held-out trace.
        model_source:
          type: string
          title: Model Source
          description: Where the validated model came from.
        time:
          items:
            type: number
          type: array
          title: Time
          description: Downsampled time grid [s].
        data_voltage:
          items:
            type: number
          type: array
          title: Data Voltage
          description: Held-out measured voltage [V].
        model_voltage:
          items:
            type: number
          type: array
          title: Model Voltage
          description: Re-simulated model voltage [V].
        residual_mV:
          items:
            type: number
          type: array
          title: Residual Mv
          description: Model − data voltage residual [mV].
      type: object
      required:
        - rmse_mV
        - mae_mV
        - max_mV
        - num_rcs
        - capacity_Ah
        - initial_soc
        - model_source
        - time
        - data_voltage
        - model_voltage
        - residual_mV
      title: ValidateECMResponse
      description: 'Held-out validation result: error metrics + downsampled overlay traces.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    FitResultsData:
      properties:
        soc:
          items:
            type: number
          type: array
          title: Soc
        ocv:
          items:
            type: number
          type: array
          title: Ocv
        r0:
          items:
            type: number
          type: array
          title: R0
        rc_pairs:
          items:
            $ref: '#/components/schemas/RcPairFitData'
          type: array
          title: Rc Pairs
        capacity_Ah:
          anyOf:
            - items:
                type: number
              type: array
            - type: 'null'
          title: Capacity Ah
          description: >-
            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.
      type: object
      required:
        - soc
        - ocv
        - r0
      title: FitResultsData
      description: Fit results needed for saving (and re-simulating for validation).
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    RcPairFitData:
      properties:
        r:
          items:
            type: number
          type: array
          title: R
        c:
          items:
            type: number
          type: array
          title: C
        tau:
          items:
            type: number
          type: array
          title: Tau
      type: object
      required:
        - r
        - c
        - tau
      title: RcPairFitData
      description: RC pair fit result arrays.

````