---
title: "Preview Sim Batch"
method: POST
path: "/api/v1/sim-batches/preview"
tags: ["simulated runs"]
---

# Preview Sim Batch

`POST /api/v1/sim-batches/preview`

## Request

- Base URL: `https://api.brumby.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.brumby.com/api/v1/sim-batches/preview`
- Auth: HTTP bearer

What this matrix would schedule. Reads nothing and writes nothing.

The form calls it while the axes are being typed, because "4 paddocks x 3
seeds x 2 herds x 2 repeats" is 48 runs and nobody does that multiplication
in their head before pressing a button that starts them.

## Request body

- SimMatrix: The axes of a sweep. The cells are their product, in this order. Empty list means "the one default": no paddock given flies the farm's default; no seed given assigns a fresh recorded seed to each cell. So a matrix with nothing in it is one run, which is what makes a single run and a sweep the same object rather than two.
  - `paddocks` string[]
  - `seeds` integer[]
  - `cows` integer[]
  - `repeats` integer
  - `herd` SimHerd: How many head, placed how, for one run. Every field is optional and an omitted one means "whatever the sim's own cattle sheet says". That matters: a sweep over seeds should not have to restate the mob profiles to leave them alone, and a run with an empty herd spec is exactly the run `pixi run sim` gives you today.
    - `seed` integer, nullable
    - `cows` integer, nullable
    - `clusters` integer, nullable
    - `cluster_spread_m` number, nullable
    - `stragglers` integer, nullable
    - `profile_mix` object, nullable

## Response `200`

Successful Response

- SimBatchPreview: What a matrix would schedule, before anything is scheduled. The form asks for this on every keystroke, because "4 paddocks x 3 seeds x 2 herds x 2 repeats" is 48 runs and nobody multiplies that in their head before pressing a button that starts them.
  - `run_count` integer, required
  - `cells` SimRunCell[], required
    - `ordinal` integer, required
    - `paddock` string, nullable, required
    - `herd` object, required
    - `label` string, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/brumby/apis/brumby-platform-api.md) - [All operations](https://skmtc.dev/brumby/apis/brumby-platform-api/llms.txt) - [OpenAPI document](https://skmtc.dev/brumby/apis/brumby-platform-api/revisions/fe185e20813e?raw)