---
title: "Run Function Regression Testing"
method: POST
path: "/v3/functions/regression"
tags: ["Function Accuracy"]
---

# Run Function Regression Testing

`POST /v3/functions/regression`

**Kick off a regression run between two versions of a function.**

Replays a sample of corrected historical inputs against the comparison
version, producing fresh transformations marked `isRegression: true`.
Each new run returns the workflow `callID`s you can monitor via
`GET /v3/calls/{callID}`.

Supported for every function type that produces correctable
transformations: `extract`, `transform`, `analyze`, `join`. For
`extract` specifically, the regression sample is dispatched through
the same OCR vs. vision path used at original call time (PDF, PNG,
JPEG, HEIC, HEIF, WebP go through the vision worker; everything else
goes through OCR → transform).

The comparison version must share a schema-compatible output shape
with the baseline; structural differences are reported as a 400 with
the offending field-level diffs.

## Typical flow

1. `POST /v3/functions/regression` — queues calls, returns
`{ originalReferenceID, callID }` per sample.
2. Wait (poll `GET /v3/calls/{callID}` or subscribe to webhooks).
3. `POST /v3/functions/regression/corrections` to copy baseline
corrections onto the new regression transformations.
4. `POST /v3/functions/compare` to compare baseline vs comparison
metrics for the regression dataset.

## Request body

- FunctionRegressionRequest — **Request parameters for function regression testing** Configures which function to test, sample size, and version comparison settings. All parameters except `functionName` are optional with sensible defaults.
  - `functionName` string, required — **Name of the function to test for regressions** Must be an existing function with historical transformation data containing user corrections. The function must be currently active and callable.
  - `baselineVersionNum` integer — **Function version number to use as baseline for comparison** - Defaults to `currentVersionNum - 1` (previous version) - Must be a valid, existing version number for the function - Used to retrieve historical transformation data for comparison - Cannot be the same as `comparisonVersionNum`
  - `comparisonVersionNum` integer — **Function version number to test against the baseline** - Defaults to current version number (latest version) - Must be a valid, existing version number for the function - This version will be used to create new function calls for testing - Cannot be the same as `baselineVersionNum`
  - `sampleSize` integer — **Number of historical samples to test** - Defaults to 50 samples - Minimum: 1, Maximum: 1000 - Only transformations with `correctedJSON` (user corrections) are eligible - Actual sample size may be smaller if insufficient corrected data exists - Larger samples provide more statistical confidence but take longer to process
  - `onlyCorrectedData` boolean — **Whether to only test transformations with user corrections** - Defaults to `true` (recommended) - When `true`: Only uses transformations with `correctedJSON` as ground truth - When `false`: May include transformations without corrections (less reliable) - Corrected data provides the most accurate regression testing results

## Response `200`

The request has succeeded.

- FunctionRegressionResponse — **Response from initiating a regression test** Contains the function call IDs created for async processing and tracking information. Use the returned function call IDs to monitor progress and retrieve results.
  - `functionName` string, required — **Name of the function being tested** Echoes back the function name from the request for confirmation.
  - `result` FunctionRegressionResult, required — **Detailed regression test results and tracking information** Contains function call IDs for monitoring progress. When all function calls complete, use the transformation endpoints to retrieve and analyze the actual results.
    - `functionName` string, required — **Name of the function being tested** The function for which regression testing was initiated.
    - `calls` RegressionFunctionCall[] — **Calls created for regression testing** Each object contains the original reference ID and the new call ID created for testing. Use these call IDs with standard call endpoints to monitor progress: - `GET /v2/calls/{callID}` - Check individual status - `GET /v2/calls?referenceIDs=regression-*` - List all regression calls
      - `originalReferenceID` string, required — **Original reference ID from historical transformation data** This is the reference ID that was used when the historical transformation was originally created. It provides traceability back to the original business context (e.g., invoice number, document ID).
      - `callID` string, required — **New call ID created for regression testing** Use this ID with standard call endpoints: - `GET /v2/calls/{callID}` - Check status and retrieve results - The call will have reference ID matching the original transformation
    - `totalSamples` integer, required — **Total number of samples being tested** This represents the number of historical transformations found with corrections that will be retested with the latest function version.

## Other responses

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

---

[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)