---
title: "Compare Metrics Between Function Versions"
method: POST
path: "/v3/functions/compare"
tags: ["Function Accuracy"]
---

# Compare Metrics Between Function Versions

`POST /v3/functions/compare`

**Compare metrics between two function versions.**

Computes aggregate and field-level lift/regression between any two
versions of a function: accuracy, precision, recall, F1, and PR-AUC.
Field-level changes are returned only for fields whose lift exceeds
1% in either direction.

Supported for every function type that produces labeled
transformations: `extract`, `transform`, `analyze`, `join`. Pass
`isRegression: true` to compare only the regression dataset (rows
produced by `POST /v3/functions/regression`) — the canonical way to
judge a candidate version before promoting it.

Defaults: `baselineVersionNum = currentVersionNum - 1`,
`comparisonVersionNum = currentVersionNum`.

## Request body

- FunctionVersionCompareRequest — **Request to compare metrics between two function versions** Compares metrics from two versions of a function to show lift or regression.
  - `functionName` string, required — Name of the function to compare versions for
  - `baselineVersionNum` integer — **Baseline version number for comparison** If not provided, defaults to the previous version (current - 1).
  - `comparisonVersionNum` integer — **Comparison version number** If not provided, defaults to the current version.
  - `isRegression` boolean — **Whether to compare regression test data only** If true, only compares transformations marked as regression tests.

## Response `200`

The request has succeeded.

- FunctionVersionCompareResponse — **Response containing metrics comparison between two function versions** Shows absolute differences, lift percentages, and field-level changes.
  - `functionName` string, required — Name of the compared function
  - `baselineVersionNum` integer, required — Baseline version number used for comparison
  - `comparisonVersionNum` integer, required — Comparison version number
  - `baselineTransformationCount` integer — Number of transformations used to calculate baseline metrics
  - `comparisonTransformationCount` integer — Number of transformations used to calculate comparison metrics
  - `aggregateComparison` MetricsComparison — Comparison of metrics between two versions
    - `accuracy` MetricComparison — Comparison of a single metric between two versions
      - `baselineValue` number, nullable — Value in baseline version (null if not available)
      - `comparisonValue` number, nullable — Value in comparison version (null if not available)
      - `difference` number, nullable — Absolute difference (comparisonValue - baselineValue)
      - `liftPercent` number, nullable — **Percentage change from baseline to comparison** Formula: ((comparisonValue - baselineValue) / baselineValue) * 100 - Positive values indicate improvement - Negative values indicate regression
    - `precision` MetricComparison — Comparison of a single metric between two versions
      - `baselineValue` number, nullable — Value in baseline version (null if not available)
      - `comparisonValue` number, nullable — Value in comparison version (null if not available)
      - `difference` number, nullable — Absolute difference (comparisonValue - baselineValue)
      - `liftPercent` number, nullable — **Percentage change from baseline to comparison** Formula: ((comparisonValue - baselineValue) / baselineValue) * 100 - Positive values indicate improvement - Negative values indicate regression
    - `recall` MetricComparison — Comparison of a single metric between two versions
      - `baselineValue` number, nullable — Value in baseline version (null if not available)
      - `comparisonValue` number, nullable — Value in comparison version (null if not available)
      - `difference` number, nullable — Absolute difference (comparisonValue - baselineValue)
      - `liftPercent` number, nullable — **Percentage change from baseline to comparison** Formula: ((comparisonValue - baselineValue) / baselineValue) * 100 - Positive values indicate improvement - Negative values indicate regression
    - `f1Score` MetricComparison — Comparison of a single metric between two versions
      - `baselineValue` number, nullable — Value in baseline version (null if not available)
      - `comparisonValue` number, nullable — Value in comparison version (null if not available)
      - `difference` number, nullable — Absolute difference (comparisonValue - baselineValue)
      - `liftPercent` number, nullable — **Percentage change from baseline to comparison** Formula: ((comparisonValue - baselineValue) / baselineValue) * 100 - Positive values indicate improvement - Negative values indicate regression
  - `fieldMetricsChanges` FieldMetricsComparison[] — **Field-level metrics that changed significantly** Only includes fields where metrics changed by more than 1%.
    - `fieldPath` string, required — JSON pointer path to the field
    - `comparison` MetricsComparison, required — Comparison of metrics between two versions
      - `accuracy` MetricComparison — Comparison of a single metric between two versions
        - `baselineValue` number, nullable — Value in baseline version (null if not available)
        - `comparisonValue` number, nullable — Value in comparison version (null if not available)
        - `difference` number, nullable — Absolute difference (comparisonValue - baselineValue)
        - `liftPercent` number, nullable — **Percentage change from baseline to comparison** Formula: ((comparisonValue - baselineValue) / baselineValue) * 100 - Positive values indicate improvement - Negative values indicate regression
      - `precision` MetricComparison — Comparison of a single metric between two versions
        - `baselineValue` number, nullable — Value in baseline version (null if not available)
        - `comparisonValue` number, nullable — Value in comparison version (null if not available)
        - `difference` number, nullable — Absolute difference (comparisonValue - baselineValue)
        - `liftPercent` number, nullable — **Percentage change from baseline to comparison** Formula: ((comparisonValue - baselineValue) / baselineValue) * 100 - Positive values indicate improvement - Negative values indicate regression
      - `recall` MetricComparison — Comparison of a single metric between two versions
        - `baselineValue` number, nullable — Value in baseline version (null if not available)
        - `comparisonValue` number, nullable — Value in comparison version (null if not available)
        - `difference` number, nullable — Absolute difference (comparisonValue - baselineValue)
        - `liftPercent` number, nullable — **Percentage change from baseline to comparison** Formula: ((comparisonValue - baselineValue) / baselineValue) * 100 - Positive values indicate improvement - Negative values indicate regression
      - `f1Score` MetricComparison — Comparison of a single metric between two versions
        - `baselineValue` number, nullable — Value in baseline version (null if not available)
        - `comparisonValue` number, nullable — Value in comparison version (null if not available)
        - `difference` number, nullable — Absolute difference (comparisonValue - baselineValue)
        - `liftPercent` number, nullable — **Percentage change from baseline to comparison** Formula: ((comparisonValue - baselineValue) / baselineValue) * 100 - Positive values indicate improvement - Negative values indicate regression
  - `baselineMetrics` MetricsDetails — Detailed performance metrics and analysis
    - `fieldMetrics` FieldMetrics[] — Enhanced field metrics with comprehensive analytics
      - `fieldPath` string, required — JSON path to the field
      - `metrics` Metrics — Comprehensive performance metrics
        - `accuracy` number, float, nullable — Overall accuracy
        - `precision` number, float, nullable — Precision (TP / (TP + FP))
        - `recall` number, float, nullable — Recall (TP / (TP + FN))
        - `f1Score` number, float, nullable — F1 Score (harmonic mean of precision and recall)
        - `tp` integer — True Positives
        - `fp` integer — False Positives
        - `tn` integer — True Negatives
        - `fn` integer — False Negatives
    - `precisionRecallAuc` number, float — Area Under the Precision-Recall Curve
    - `aggregateMetrics` Metrics — Comprehensive performance metrics
      - `accuracy` number, float, nullable — Overall accuracy
      - `precision` number, float, nullable — Precision (TP / (TP + FP))
      - `recall` number, float, nullable — Recall (TP / (TP + FN))
      - `f1Score` number, float, nullable — F1 Score (harmonic mean of precision and recall)
      - `tp` integer — True Positives
      - `fp` integer — False Positives
      - `tn` integer — True Negatives
      - `fn` integer — False Negatives
  - `comparisonMetrics` MetricsDetails — Detailed performance metrics and analysis
    - `fieldMetrics` FieldMetrics[] — Enhanced field metrics with comprehensive analytics
      - `fieldPath` string, required — JSON path to the field
      - `metrics` Metrics — Comprehensive performance metrics
        - `accuracy` number, float, nullable — Overall accuracy
        - `precision` number, float, nullable — Precision (TP / (TP + FP))
        - `recall` number, float, nullable — Recall (TP / (TP + FN))
        - `f1Score` number, float, nullable — F1 Score (harmonic mean of precision and recall)
        - `tp` integer — True Positives
        - `fp` integer — False Positives
        - `tn` integer — True Negatives
        - `fn` integer — False Negatives
    - `precisionRecallAuc` number, float — Area Under the Precision-Recall Curve
    - `aggregateMetrics` Metrics — Comprehensive performance metrics
      - `accuracy` number, float, nullable — Overall accuracy
      - `precision` number, float, nullable — Precision (TP / (TP + FP))
      - `recall` number, float, nullable — Recall (TP / (TP + FN))
      - `f1Score` number, float, nullable — F1 Score (harmonic mean of precision and recall)
      - `tp` integer — True Positives
      - `fp` integer — False Positives
      - `tn` integer — True Negatives
      - `fn` integer — False Negatives
  - `message` string — Optional message with additional details

## Other responses

- `400` — The server could not understand the request due to invalid syntax.
- `404` — The server cannot find the requested resource.
- `500` — Server error

---

[API](https://skmtc.dev/bem-team/apis/bem-api.md) · [All operations](https://skmtc.dev/bem-team/apis/bem-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/bem-team/bem-api/revisions/a6e4624117c6/schema)