POST/sim/runsadmin

Start a simulation run: a population drawn from a pack (or a selection of personas), a stimulus, measures, a voiced tier (free text rated by SSR, with collapse checks) and dynamics (adoption over mixing groups, or opinion over an explicit graph). Runs as `simulate-voice` then `simulate` jobs; watch sim.progress / sim.done in /events. At most 3 queued or running per tenant (429).

Body

packthe pack whose dimensions the population is drawn from
population{simulate: rows, represents?: people (each row stands for represents/simulate), seed?, segments?: [{name, share, values: {dimension: value | {shares} | {range: [lo, hi]} | {distribution}}}], rake?: [category dims] | {dim: {label: share}}, mixing?: {by: [dims or a mixing_group edge], edges?: {dim: [cut points]}}} or {personas: {where?, limit?, handles?, copies?, years_before? (a self-linked persona begins that many years younger, to live its past up to its age now)}, represents?, mixing?}
stimulus{text, kind?, structure?, images?: [at most 4 base64 data: URLs (jpeg, png, webp), each under 400,000 characters], shown to every voiced member with the words}
measures[purchase_intent | appeal | share_intent | attend_intent | {key, anchors: [5 statements low..high] | [[..], [..]], ask?}] (default purchase_intent)
voice{members: 0..500 voiced by the tenant's model, rated by SSR; retest?: 0..20 (2); prior?: true; expected_sd?: 1.1; temperature?; strata?: [category dims or "segment"] for a weighted stratum sample}
dynamics{model: adoption, channels: {name: rate/day | {default, general, <segment>, "dim=value", "scalar<25", "scalar>=65", "scalar=18..24": rate} (every key is checked: an unknown one is refused by name)}, imitation?, across?: 0..1, fatigue?, fatigue_shape?, appeal?: scalar dim, appeal_measure?, events?: [{at, exposure, half_life?, duration?, who?}], event_process?: {rate: {mean, per}, exposure, half_life?, who?}} | {model: opinion, graph?: {edges: [[listener, speaker, w?]]}, homophily?: [dims], stubbornness?: 0..1, rate?}
stepany duration ("10min", "1h", "1d")
horizona duration ("40d")
report_everya duration
chunkrows per chunk
seeds1..20 (spread across seeds)
reference_dateYYYY-MM-DD the run's time starts at (default today): durations map onto the calendar from it, and derived dimensions (a cohort from age) count years from it
holdtrue: created but not started until POST /sim/runs/:id/observations {release: true}
observe{tool, args?, members?: voiced|all, max?: 1..5000}: pull per-member observations from one of the tenant's read-only tools first
calibration{targets: [{measure?, metric: mean|would_act|have_it_end|ever_had_it_end, target, tolerance?}]}: checked in results.calibration
GET/sim/runsmember

Simulation runs, newest first, with status, progress and the design (and version) each was made from.

Query

statusqueued|running|done|failed|cancelled
limit1..100 (20)
designonly this design's runs
GET/sim/runs/:idmember

One run: spec, progress {phase, voiced, voice_of, seed, seeds, step, steps, pct}, and when done its aggregate results (represented vs simulated, reactions per measure with distribution, divides, would_act and collapse checks, adoption curves with the seed spread, opinion) and results.trust (version 1): fidelity tier mix, seed spread, reliability (test-retest), collapse warnings, calibration state with raw/debiased/calibrated signals, and the design's backtest skill against naive baselines. Special-category dimensions only in groups of 10+.

GET/sim/runs/:id/membersmember

A run's sampled members, a page at a time by stable index: segment, weight, public traits (special-category values never), and the persona's handle when members are personas.

Query

afterthe last index of the previous page
limit1..1000 (100)
POST/sim/runs/:id/observationsadmin

External per-member observations: values of the pack's dimensions keyed by member index, before the run starts (a held run) or between its steps. They replace drawn values in profiles, rates and breakdowns. release: true starts a held run.

Body

observations[{i, values: {dimension: value}}] (at most 5000 per call)
sourcewhat produced them
releasetrue starts a held run
GET/sim/comparemember

Two finished runs side by side (an A/B of stimuli or designs): per measure means, would-act and JSD between distributions, adoption at the end, and whether they ran on the same seeds.

Query

arun id
brun id
POST/sim/runs/:id/canceladmin

Stop a queued, running or paused run for good (409 once finished).

POST/sim/runs/:id/pauseadmin

Pause a running run: status pausing until its next chunk boundary (a voiced batch in flight finishes first), then paused. A paused run holds no worker and survives restarts; idempotent.

POST/sim/runs/:id/resumeadmin

Continue a paused run from its checkpoint: resuming, then running. Results equal an uninterrupted run with the same seed. 429 when the tenant already has its maximum active runs.

DELETE/sim/runs/:idadmin

Delete a run with its observations and results, for good (404 when not the tenant's). Event sim.deleted.

POST/sim/runs/deleteadmin

Delete many runs at once; those not found come back under missing.

Body

ids[ids], 1..200
POST/sim/runs/:id/archiveadmin

Archive (archived: true, the default) or bring back (false) a run. Archived runs leave lists unless ?archived=1 (only archived) or all.

Body

archivedtrue | false
POST/sim/runs/archiveadmin

Archive or bring back many runs at once.

Body

ids[ids], 1..200
archivedtrue | false
A glass tree whose crown holds many small worlds like fruit

Which world will you live in?

What grows here is meant to reach the real world. Start with a world of your own.