Simulation

Run a simulation

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.

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

Request body

OR

Example request

{
  "mode": "auto",
  "runs": 10000,
  "scenario": {
    "name": "Product launch decision",
    "objective": "maximize_net_value",
    "variables": {
      "cost": {
        "high": 90000,
        "low": 40000
      },
      "revenue": {
        "high": 200000,
        "low": 80000
      }
    }
  },
  "simulation_model": "monte_carlo"
}

Response

Successful Response

run_idstring uuid required
statusstring
engine_versionstring required
recommended_actionstring required
confidencenumber required
rationalestring required
scenarios_runinteger required
execution_msinteger required
simulation_modelstring

Which simulation algorithm was used. Possible values: monte_carlo | qmc_sobol | lhs | bootstrap | scenario | sensitivity | mcmc | decision_tree | time_series | compare | importance_sampling

engine_typestring nullable

Engine that ran the simulation (e.g. 'mojo-native-expr', 'lhs', 'mcmc')

simulation_classstring

High-level simulation contract class. Examples: predictive, scenario_analysis, sensitivity_analysis, decision_tree.

model_revisionstring nullable

Stable engine or model revision used to generate this result.

assumptions_hashstring nullable

Stable fingerprint of the validated simulation assumptions executed by the engine.

validated_inputsobject nullable

Normalized summary of the validated request inputs used for execution. Includes mode, runs, variable counts, and model selection.

confidence_intervalobject nullable

Primary outcome confidence interval derived from the simulated distribution.

request_idstring nullable

Correlation identifier propagated from the API request.

scenario_analysisobject nullable

Populated for simulation_model='scenario': expected_value, best_case, scenarios list

sensitivity_analysisobject nullable

Populated for simulation_model='sensitivity': tornado_chart, first_order_sobol, variable_importance

bootstrap_resultobject nullable

Populated for simulation_model='bootstrap': statistic, observed_value, CI, bias, SE

mcmc_resultobject nullable

Populated for simulation_model='mcmc': posterior summaries, R-hat, acceptance_rate

importance_sampling_resultobject 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_rankingobject[] nullable
sensitivity_rankingobject[] nullable
scorenumber nullable
score_breakdownobject nullable
created_atstring date-time nullable
decision_tree_resultobject nullable

Populated for simulation_model='decision_tree': n_paths, expected_value, paths[]

time_series_resultobject 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_resultobject 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_contextobject 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_warningsstring[] nullable

Non-fatal unit validation warnings (e.g. negative currency, out-of-range probability). Simulation still ran — these are advisory only.

chartsobject 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_dataobject nullable

Pre-computed histogram bins (50 bins) for the primary output distribution.

request_hashstring 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_hashstring 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.

Changes

No recorded changes to this operation across all 1 revision of this API.