Farna Control
Read-only demoInstall

Variant Groups

A variant group ties a set of variants to one pipeline. Create the group with weighted variants, then start runs through its run endpoint; each run draws one variant, so the pipeline definition stays untouched while results accumulate per variant.

API endpoints

  • POST /api/v1/variant-groups - Create a variant group with weighted variants
  • GET /api/v1/variant-groups - List variant groups (paginated, filterable by pipeline_id)
  • GET /api/v1/variant-groups/{id} - Get variant group by ID
  • PUT /api/v1/variant-groups/{id} - Update variant group
  • DELETE /api/v1/variant-groups/{id} - Delete variant group (soft delete)
  • POST /api/v1/variant-groups/{id}/restore - Restore a soft-deleted variant group
  • POST /api/v1/variant-groups/{id}/run - Start one run against the group (weighted random selection picks the variant)
  • POST /api/v1/variant-groups/{id}/batch-run - Run every variant once against the same input payload and return the runs with a batch_id
  • GET /api/v1/variant-groups/batches/{batch_id}/compare - Compare the runs in a batch: status, eval pass rate, cost, tokens, and the frozen snapshot and override diff
  • GET /api/v1/variant-groups/{id}/coverage-gaps - Detect eval coverage gaps per variant
  • GET /api/v1/variant-groups/{id}/prompt-diffs - Compare prompt version hashes across variant snapshots

Running every variant once

batch-run takes the same input_payload as run, fires one run per variant, and returns a batch_id plus has_evals, which is false when the pipeline has no default evals, so the comparison is cost and output diff only. The batch is all-or-nothing: every variant must carry a snapshot and the pipeline’s concurrency quota must fit the whole batch, or no run fires. Read the results with batches/{batch_id}/compare; it loads the batch by ID, so deleting the group later does not break the comparison.

Notes

  • Every endpoint carries organization context through Row-Level Security (RLS)
  • Weights apply when a run is started, so weighting changes affect subsequent runs rather than runs already in progress
  • run_context_overrides on the selected variant apply to that run alone

Selection order, quota behavior, and coverage-gap reporting are described in Variant Execution.

Next: Contribution Provenance