---
title: "Run a simulation"
method: POST
path: "/v1/simulate"
tags: ["Simulation"]
---

# Run a simulation

`POST /v1/simulate`

## Request

- Base URL: `https://api.algenta.ai`
- URL: `https://api.algenta.ai/v1/simulate`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Execute a Monte Carlo simulation and receive a structured decision envelope. Use `mode: 'auto'` for minimal setup or `mode: 'expert'` for full control.

**Performance**: p50 < 15ms server-side (Mojo worker pool, async persistence).

**Execution policy**: Algenta editions have unlimited decisions and no plan request meter. HTTP 429 is reserved for explicit endpoint, provider, or operator controls.

## Request body

- union
  - SimulateRequestAuto: Auto-mode simulation request — minimal setup, engine infers distributions.
    - `mode` 'auto', required
    - `scenario` AutoScenario, required
      - `name` string, nullable
      - `variables` object, required
      - `objective` 'maximize_net_value' | 'maximize_revenue' | 'minimize_cost' | 'minimize_risk' | 'maximize_score', required
    - `runs` integer
    - `seed` integer, nullable
    - `simulation_model` 'monte_carlo' | 'qmc_sobol' | 'lhs' | 'bootstrap' | 'scenario' | 'sensitivity' | 'mcmc' | 'decision_tree' | 'time_series' | 'compare' | 'importance_sampling': Which simulation algorithm to use. ALL run natively in Mojo — zero Python bottlenecks.
    - `bootstrap_config` BootstrapConfig: Config for engine_type='bootstrap' — non-parametric resampling.
      - `historical_data` number[], required
      - `statistic` string: Statistic to compute on each resample. One of: mean, median, std, variance, sum, min, max, sharpe, percentile_5, percentile_25, percentile_75, percentile_95, range, cv
      - `confidence_level` number
    - `scenario_config` ScenarioConfig: Config for engine_type='scenario' — discrete weighted scenarios.
      - `scenarios` ScenarioItem[], required
        - `name` string, required
        - `probability` number, required
        - `variables` object
        - `objective_function` string, nullable
    - `sensitivity_config` SensitivityConfig: Config for engine_type='sensitivity' — sensitivity analysis.
      - `method` string: tornado | sobol | both
  - SimulateRequestExpert: Expert-mode simulation request — full distribution and objective control.
    - `mode` 'expert', required
    - `simulation` ExpertSimulation, required: Universal simulation specification. No restrictions on domain, variable count, or expression complexity. Works for any industry and data type. objective_function — complete function reference: Arithmetic: +, -, *, /, ^ (power), % (mod) Standard: sqrt(x), exp(x), ln(x), log(x), log10(x), log2(x), log1p(x), expm1(x), abs(x), floor(x), ceil(x), round(x) Min/Max: min(a,b), max(a,b), clip(v,lo,hi) Conditional: if(cond>0, then_val, else_val) Trigonometry: sin(x), cos(x), tan(x), asin(x), acos(x), atan(x) atan2(y,x), sinh(x), cosh(x), tanh(x) Special: erf(x), erfc(x), gamma(x), lgamma(x), sign(x), hypot(a,b) Statistical: norm_cdf(x), norm_pdf(x), norm_ppf(p), t_cdf(x, df), chi2_cdf(x, df), logistic(x), logit(x) Combinatorics: factorial(n), comb(n,k), perm(n,k) Sequences: fibonacci(n), fib(n), fib_ratio(n) = F(n)/F(n-1) Financial: npv(rate,cf0,cf1,...), pmt(rate,n,pv), fv(rate,n,pmt,pv), pv(rate,n,pmt), annuity(rate,n), duration(rate,n) Constants: c (speed of light), G (gravity), g (9.81 m/s²), kB (Boltzmann), NA (Avogadro), R (gas), pi, e, phi Multi-output: separate objectives with | e.g. "net_profit | risk_score | irr" Variables: any variable name from the variables list as a symbol Examples: "revenue - cost" "max(0, sales * margin - fixed_cost)" "npv(0.1, -capex, cf1, cf2, cf3, cf4, cf5)" "norm_cdf((mu - threshold) / sigma)" "mass * g * height" # kinetic/potential energy "fibonacci(growth_stage)" # Fibonacci growth model "revenue - cost | revenue / cost | norm_cdf(revenue - target)" # multi-output
      - `variables` VariableSpec[], required
        - `name` string, required
        - `distribution` 'normal' | 'uniform' | 'triangular' | 'lognormal' | 'fixed' | 'discrete' | 'categorical' | 'beta' | 'exponential' | 'weibull' | 'gamma' | 'pert' | 'bernoulli' | 'poisson' | 'student_t' | 'cauchy' | 'laplace' | 'pareto' | 'gumbel' | 'rayleigh' | 'arcsine' | 'logistic' | 'halfnormal' | 'vonmises' | 'neg_binomial' | 'hypergeometric' | 'negative_binomial', required: Universal distribution library — no restrictions on domain or data type. Applicable to any industry: finance, medical, manufacturing, aerospace, defense, energy, hospitality, insurance, pharma, supply chain, and more.
        - `params` DistributionParams, required
          - `mean` number, nullable
          - `std` number, nullable
          - `low` number, nullable
          - `high` number, nullable
          - `mode` number, nullable
          - `value` number, nullable
          - `alpha` number, nullable
          - `beta` number, nullable
          - `rate` number, nullable
          - `lambda` number, nullable
          - `shape` number, nullable
          - `scale` number, nullable
          - `likely` number, nullable
          - `gamma` number, nullable
          - `p` number, nullable
          - `values` number[], nullable
          - `probabilities` number[], nullable
        - `unit` string, nullable: Short-hand unit string: 'USD', 'BTC', '%', 'bps', 'days', 'Pa', etc.
        - `unit_spec` UnitSpec: Universal unit specification — supports any numeric domain. Short-hand strings also accepted anywhere a UnitSpec is expected: "USD" → currency/USD (2 decimal places) "BTC" → crypto/BTC (8 decimal places, satoshi-aware) "ETH" → crypto/ETH (18 decimals, wei-aware) "%" → percentage (scale × 100 for display) "bps" → basis points (scale × 10,000 for display) "days" → duration in days "Pa" / "kg" → SI unit (scientific notation for tiny/huge values) "probability" → strictly [0,1] validated "count" → non-negative integer-like Full dict form: { "type": "currency", # unit category "code": "USD", # unit identifier "precision": 2, # display decimal places (None = auto) "scale": 1.0, # multiply raw value for display (e.g. 100 for 0→1 % → 0→100%) "format": "compact", # standard | compact | scientific "base_unit": "satoshi", # sub-unit label (informational) "sim_scale": 1.0 # divide input by this before simulation }
          - `type` string: Unit category: currency | crypto | date | duration | percentage | bps | scientific | si | count | probability | custom | raw
          - `code` string: Unit identifier: ISO 4217 currency, crypto ticker, SI symbol, etc.
          - `precision` integer, nullable: Display decimal places. None = auto-inferred from type/code.
          - `scale` number: Multiply raw simulation output by this for display (e.g. 100 for percentage).
          - `format` string: Display format: standard | compact ($1.2M) | scientific (1.23e-9)
          - `base_unit` string: Sub-unit label (informational). E.g. 'satoshi' for BTC, 'wei' for ETH.
          - `sim_scale` number: Divide input params by this before simulation. E.g. sim_scale=1e8 if BTC inputs are in satoshis, converts to whole BTC for Mojo.
        - `description` string, nullable
        - `domain_hint` string, nullable: Optional domain hint e.g. 'time_to_failure', 'patient_recovery_days', 'material_yield_strength'
        - `labels` string[], nullable: For categorical/discrete: human-readable labels for each outcome index
      - `correlations` CorrelationSpec[]
        - `variables` string[], required
        - `coefficient` number, required
      - `objective_function` string, nullable: Expression evaluated each scenario. Supports all math functions. Multi-output: separate with | pipe character. Example: 'revenue - cost | (revenue - cost) / revenue * 100 | min(cash_flow, 0)'
      - `scoring` ScoringWeights
        - `expected_value` number
        - `downside_risk` number
      - `domain` string, nullable: Industry/domain hint: finance, medical, manufacturing, aerospace, defense, etc.
      - `domain_template` string, nullable: Name of predefined domain template used (for reference)
      - `output_labels` string[], nullable: Labels for multi-output objectives (matches | separator count)
      - `output_units` string[], nullable: Physical/currency units for each output. E.g. ['USD', '%', 'years']
      - `output_unit_specs` UnitSpec[], nullable: Full UnitSpec per output objective (matches | separator count). Enables formatted_result in the response with currency symbols, compact notation ($1.2M), scientific notation (1.23e-9 Pa), etc. Example: [{'type':'currency','code':'USD','format':'compact'}, {'type':'percentage'}]
        - `type` string: Unit category: currency | crypto | date | duration | percentage | bps | scientific | si | count | probability | custom | raw
        - `code` string: Unit identifier: ISO 4217 currency, crypto ticker, SI symbol, etc.
        - `precision` integer, nullable: Display decimal places. None = auto-inferred from type/code.
        - `scale` number: Multiply raw simulation output by this for display (e.g. 100 for percentage).
        - `format` string: Display format: standard | compact ($1.2M) | scientific (1.23e-9)
        - `base_unit` string: Sub-unit label (informational). E.g. 'satoshi' for BTC, 'wei' for ETH.
        - `sim_scale` number: Divide input params by this before simulation. E.g. sim_scale=1e8 if BTC inputs are in satoshis, converts to whole BTC for Mojo.
    - `runs` integer
    - `seed` integer, nullable
    - `simulation_model` 'monte_carlo' | 'qmc_sobol' | 'lhs' | 'bootstrap' | 'scenario' | 'sensitivity' | 'mcmc' | 'decision_tree' | 'time_series' | 'compare' | 'importance_sampling': Which simulation algorithm to use. ALL run natively in Mojo — zero Python bottlenecks.
    - `bootstrap_config` BootstrapConfig: Config for engine_type='bootstrap' — non-parametric resampling.
      - `historical_data` number[], required
      - `statistic` string: Statistic to compute on each resample. One of: mean, median, std, variance, sum, min, max, sharpe, percentile_5, percentile_25, percentile_75, percentile_95, range, cv
      - `confidence_level` number
    - `scenario_config` ScenarioConfig: Config for engine_type='scenario' — discrete weighted scenarios.
      - `scenarios` ScenarioItem[], required
        - `name` string, required
        - `probability` number, required
        - `variables` object
        - `objective_function` string, nullable
    - `mcmc_config` MCMCConfig: Config for engine_type='mcmc' — Metropolis-Hastings Bayesian MCMC.
      - `observed_data` number[], required
      - `parameter_priors` object: Dict of param_name → {distribution, params}. Auto-inferred from data if empty. Example: {'mean': {'distribution': 'normal', 'params': {'mean': 500000, 'std': 100000}}}
      - `likelihood` string: Likelihood model: normal | lognormal | poisson
      - `chains` integer
      - `burn_in` integer
    - `sensitivity_config` SensitivityConfig: Config for engine_type='sensitivity' — sensitivity analysis.
      - `method` string: tornado | sobol | both
    - `importance_sampling_config` ImportanceSamplingConfig: Config for engine_type='importance_sampling' — exponential tilting for rare tail events. Use when you need accurate estimates of very low-probability events (e.g. 1-in-10,000 loss scenarios) without running millions of MC trials. The engine shifts sampling mass toward the target tail using exponential tilting (θ optimal tilt), then corrects back with likelihood ratio weights. Reports: tail_probability, tail_probability_se, cvar_tail, ESS, variance_reduction_factor.
      - `target_threshold` number, required: The rare event level. E.g. -500000 for a $500k loss, or 2.5 for an extreme gain.
      - `tail_direction` string: 'lower' for loss events (outcome < threshold), 'upper' for extreme gains (outcome > threshold).
      - `tilt_variable` string, nullable: Name of the normal-distributed variable to apply exponential tilting to. Auto-detects the highest-variance normal variable if omitted.
      - `tilt_sigma` number: Override the tilt parameter θ directly (0 = auto-compute from threshold). Advanced use only.
    - `decision_tree_config` DecisionTreeConfig: Config for engine_type='decision_tree' — multi-layered decisions with branches. Example (2-level tree): nodes: [ { id: "launch_decision", type: "decision", name: "Launch Product?", branches: [ { id: "launch_yes", type: "chance", name: "Launch", probability: 1.0, branches: [ { id: "accept", type: "terminal", name: "Market Accepts", probability: 0.7, objective_function: "revenue - launch_cost" }, { id: "reject", type: "terminal", name: "Market Rejects", probability: 0.3, variables: {"revenue": 0}, objective_function: "-launch_cost" } ] } ] } ]
      - `nodes` DecisionNode[], required: Root nodes of the decision tree. Multiple roots = parallel independent decisions.
        - `id` string, required
        - `type` string: Node type: decision | chance | terminal
        - `name` string
        - `probability` number: Branch probability (for chance nodes). All siblings should sum to 1.0.
        - `condition` string, nullable: Optional expression condition for this branch to be active
        - `variables` object: Variable overrides for this branch. Scalar value → treated as fixed distribution. Dict → full VariableSpec override {distribution, params}.
        - `objective_function` string, nullable: Expression override for this node. Inherits top-level if not set.
        - `branches` DecisionNode[]: Child branches. Empty = terminal node.
      - `max_depth` integer: Maximum allowed tree depth
    - `time_series_config` TimeSeriesConfig: Config for engine_type='time_series' — multi-horizon stochastic path simulation. Supported models: gbm — Geometric Brownian Motion ou — Ornstein-Uhlenbeck mean-reversion arithmetic — Arithmetic Brownian Motion compound — Compound return custom — Expression-driven path Granularities: ms, s, min, h, day, week, month, quarter, year
      - `model` string: Path model: gbm | ou | arithmetic | compound | custom
      - `initial_value` number, required: Starting value of the process (e.g. current stock price, balance, etc.)
      - `horizons` integer[]: Time steps at which to record distributions. E.g. [1,3,6,12] for 1/3/6/12 months.
      - `granularity` string: Time unit per step. One of: ms, s, min, h, day, week, month, quarter, year. All drift/vol parameters assumed annualized unless granularity='custom'.
      - `drift` union: Annualized drift / expected return. Float shorthand or StochasticParam for uncertain drift. GBM: annual log-return. OU: not used (use long_run_mean). Compound: annual return.
        - StochasticParam: A simulation parameter that is itself stochastic (drawn fresh for each path). Use for uncertain drift, volatility, or any time-series parameter.
          - `type` string: fixed | normal | uniform | lognormal
          - `value` number: Fixed value (for type='fixed')
          - `mean` number: Mean (for type='normal' or 'lognormal')
          - `std` number: Std dev (for type='normal' or 'lognormal')
          - `low` number: Lower bound (for type='uniform')
          - `high` number: Upper bound (for type='uniform')
        - number
      - `volatility` union: Annualized volatility (σ). Float or StochasticParam.
        - StochasticParam: A simulation parameter that is itself stochastic (drawn fresh for each path). Use for uncertain drift, volatility, or any time-series parameter.
          - `type` string: fixed | normal | uniform | lognormal
          - `value` number: Fixed value (for type='fixed')
          - `mean` number: Mean (for type='normal' or 'lognormal')
          - `std` number: Std dev (for type='normal' or 'lognormal')
          - `low` number: Lower bound (for type='uniform')
          - `high` number: Upper bound (for type='uniform')
        - number
      - `autocorrelation` number: AR(1) autocorrelation coefficient for innovations (0 = i.i.d., >0 = trending, <0 = mean-reverting noise)
      - `long_run_mean` number, nullable: OU model: long-run mean (μ∞). Defaults to initial_value.
      - `mean_reversion_speed` number: OU model: speed of mean reversion (θ). Higher = faster pull to mean.
      - `path_expression` string, nullable: Custom model: Python expression for next step value. Variables: value, t, dt, drift, vol, z, initial. Example: 'value * exp((drift - 0.5*vol**2)*dt + vol*dt**0.5*z)'
      - `fan_chart_percentiles` integer[]: Percentile levels to include in the fan chart output at each horizon.
      - `output_paths` boolean: Include sample path data in response (for fan chart visualization). Adds ~50 paths.
      - `n_sample_paths` integer: Number of sample paths to include when output_paths=True.
    - `include_charts` boolean: Include pre-computed Vega-Lite chart specs in the response. When true, adds 'charts' dict with histogram, CDF, tornado (if sensitivity), fan_chart (if time_series). Ready to pass to vega-embed for instant rendering. Adds ~5ms to response time.
    - `include_histogram` boolean: Include pre-computed 50-bin histogram data (lighter than full chart spec). Adds 'histogram_data' to response. Useful for quick distribution preview.

## Response `200`

Successful Response

- DecisionEnvelope: Full decision output returned by /v1/simulate, /v1/recommend, and /v1/score.
  - `run_id` string, uuid, required
  - `status` string
  - `engine_version` string, required
  - `recommended_action` string, required
  - `confidence` number, required
  - `rationale` string, required
  - `metrics` MetricsSummary, required
    - `expected_value` number, required
    - `median` number, required
    - `std_deviation` number, required
    - `variance` number, required
    - `probability_of_loss` number, required
    - `var_95` number, nullable
    - `cvar_95` number, nullable
  - `percentiles` PercentileSummary, required
    - `p5` number, required
    - `p10` number, nullable
    - `p25` number, required
    - `p50` number, required
    - `p75` number, required
    - `p90` number, nullable
    - `p95` number, required
    - `p99` number, nullable
  - `scenarios_run` integer, required
  - `execution_ms` integer, required
  - `metadata` RunMetadata, required
    - `mode` string, required
    - `seed` integer, nullable
    - `billing_units` integer, required
    - `engine_version` string, required
  - `simulation_model` string: Which simulation algorithm was used. Possible values: monte_carlo | qmc_sobol | lhs | bootstrap | scenario | sensitivity | mcmc | decision_tree | time_series | compare | importance_sampling
  - `engine_type` string, nullable: Engine that ran the simulation (e.g. 'mojo-native-expr', 'lhs', 'mcmc')
  - `simulation_class` string: High-level simulation contract class. Examples: predictive, scenario_analysis, sensitivity_analysis, decision_tree.
  - `model_revision` string, nullable: Stable engine or model revision used to generate this result.
  - `assumptions_hash` string, nullable: Stable fingerprint of the validated simulation assumptions executed by the engine.
  - `validated_inputs` object, nullable: Normalized summary of the validated request inputs used for execution. Includes mode, runs, variable counts, and model selection.
  - `confidence_interval` object, nullable: Primary outcome confidence interval derived from the simulated distribution.
  - `request_id` string, nullable: Correlation identifier propagated from the API request.
  - `scenario_analysis` object, nullable: Populated for simulation_model='scenario': expected_value, best_case, scenarios list
  - `sensitivity_analysis` object, nullable: Populated for simulation_model='sensitivity': tornado_chart, first_order_sobol, variable_importance
  - `bootstrap_result` object, nullable: Populated for simulation_model='bootstrap': statistic, observed_value, CI, bias, SE
  - `mcmc_result` object, nullable: Populated for simulation_model='mcmc': posterior summaries, R-hat, acceptance_rate
  - `importance_sampling_result` object, nullable: Populated for simulation_model='importance_sampling'. Contains: tail_direction, target_threshold, tail_probability, tail_probability_se, cvar_tail, weighted_mean, weighted_std, theta (tilt parameter), tilt_variable, effective_sample_size, nominal_sample_size, variance_reduction_factor, naive_tail_count.
  - `scenario_ranking` object[], nullable
  - `sensitivity_ranking` object[], nullable
  - `score` number, nullable
  - `score_breakdown` object, nullable
  - `created_at` string, date-time, nullable
  - `decision_tree_result` object, nullable: Populated for simulation_model='decision_tree': n_paths, expected_value, paths[]
  - `time_series_result` object, nullable: Populated for simulation_model='time_series'. Contains: model, granularity, dt_years, initial_value, n_steps, fan_chart (per-horizon p5/p25/p50/p75/p95), terminal distribution, max_drawdown_pct, and optional sample_paths for visualization.
  - `formatted_result` object, nullable: Human-readable formatted output values with units. Populated when output_unit_specs or unit_spec is provided. Contains: mean_formatted, p5_formatted, p95_formatted, unit, unit_type, etc.
  - `unit_context` object, nullable: Unit metadata for all variables and outputs. Contains per-variable unit type, code, precision, and display scale. Use this to reconstruct formatted values client-side.
  - `unit_warnings` string[], nullable: Non-fatal unit validation warnings (e.g. negative currency, out-of-range probability). Simulation still ran — these are advisory only.
  - `charts` object, nullable: Pre-computed Vega-Lite compatible chart specs for instant rendering. Populated when include_charts=true in the request or automatically for sensitivity/time_series engine types. Keys: 'histogram', 'cdf', 'tornado', 'fan_chart', 'scatter'. Each value is a complete Vega-Lite spec that can be passed to vega-embed.
  - `histogram_data` object, nullable: Pre-computed histogram bins (50 bins) for the primary output distribution.
  - `decision_plan` DecisionPlan: Structured, LLM-readable summary of the decision output. This is the headline object — it surfaces all decision-critical fields in a compact, consistent shape regardless of simulation model used. Populate ``options`` with all ranked alternatives when using /v1/recommend.
    - `recommended_action` string, required
    - `confidence` number, required
    - `expected_value` number, required
    - `risk` RiskProfile, required: Quantified downside and upside for a single outcome distribution.
      - `p5` number, required: 5th-percentile outcome (downside risk floor)
      - `p95` number, required: 95th-percentile outcome (upside ceiling)
      - `probability_of_loss` number, required: P(outcome < 0)
      - `var_95` number, nullable: Value-at-Risk at 95% confidence
    - `options` DecisionOption[]: All alternatives ranked by expected value. Single-element for simulate, multi for recommend.
      - `name` string, required
      - `rank` integer, required
      - `expected_value` number, required
      - `risk` RiskProfile, required: Quantified downside and upside for a single outcome distribution.
        - `p5` number, required: 5th-percentile outcome (downside risk floor)
        - `p95` number, required: 95th-percentile outcome (upside ceiling)
        - `probability_of_loss` number, required: P(outcome < 0)
        - `var_95` number, nullable: Value-at-Risk at 95% confidence
      - `score` number, nullable: Composite score (0–1)
    - `rationale` string, required
    - `integrity` object, nullable: Cryptographic proof of inputs/outputs: {request_hash, result_hash}.
    - `calibration` string, nullable: Human-readable calibration summary, e.g. '12 outcomes | bias=-8.3% (over-optimistic) | hit_rate=75%'. Null until MIN_SAMPLES (5) outcomes are recorded for this org.
    - `repository_analysis` RepositoryAnalysis: Repository-intelligence extension block for DecisionPlan.
      - `root_cause` string, required
      - `planner_model_id` string, required
      - `planner_execution_mode` string, required
      - `planner_provider_backend` string, nullable
      - `candidate_fixes` string[]
      - `impacted_services` string[]
      - `impacted_symbols` string[]
      - `likely_failing_tests` string[]
      - `rollback_complexity` string, required
      - `blast_radius` string, required
      - `workspace_evidence_refs` string[]
      - `generated_patch_ref` string, nullable
      - `patch_impact_report_ref` string, nullable
      - `token_reduction_metrics` TokenReductionMetrics, required: Token-budget compression produced by deterministic repository narrowing.
        - `raw_repo_token_estimate` integer, required
        - `evidence_bundle_token_count` integer, required
        - `reduction_ratio` number, required
  - `request_hash` string, nullable: SHA-256 fingerprint of the INPUT payload (variables, distributions, objective function, seed). Cryptographic proof of what data was used to make this decision. Computed at submission time before simulation runs. Format: hex string, 64 chars.
  - `result_hash` string, nullable: SHA-256 fingerprint of this decision OUTPUT (64-char hex). Covers: run_id, request_hash (input binding), recommended_action, confidence, rationale, metrics, percentiles, scenarios_run, engine_version, simulation_model. Binds the decision to both its inputs AND outputs. Use to verify the decision has not been tampered with. Also returned as X-Decision-Hash response header.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/codna/apis/algenta-api.md) · [All operations](https://skmtc.dev/codna/apis/algenta-api/llms.txt) · [OpenAPI document](https://skmtc.dev/codna/apis/algenta-api/revisions/35d30f84a5df?raw)