{"data":{"markdownRemark":{"html":"
\nNote: if you wish to modify variables in Globals please make sure any inputs are prefaced with system. or are contained within a system object.\n
\n

POST

\n

Creates and runs a scenario simulation and returns an object with its various attributes.

\n

Request

\n

Example request body

\n
curl -X POST \\\n  http://localhost:8080/api/simulations/scenario \\\n  -H 'Cache-Control: no-cache' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n  \"modelName\": \"Simple Credit Card\", \n  \"output\": {\"uri\": \"scenarioFolder\" },\n  \"scenarios\":[{\n    \"name\": \"myScenario\", \n    \"runs\": 3,\n    \"seeds\": [1234, 2314, 4213]\n    \"scenarioData\": {\n        \"0\": {\"spending\": 200},\n        \"4\": {\"spending\": 100, \"interest\": 0.04}\n      }\n  }]\n}'
\n
\n

Windows user File

\n Characters need to be escaped when using scenarios in windows on cmd.\n

'{"name": "Game of Life"}' must become '{\\"name\\": \\"Game of Life\\"}'

\n
\n

Body Schema

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ParameterTypeRequiredDescription
modelNamestringtrueName of model to run a scenario for. This is the name that the model is registered with when starting the server.
scenarios[object]List of objects describing scenarios to run for this model
>nameobjectA user specified name for the scenario. If not provided, scenario_{id} will be used as the name, where id is the index of this scenario in the array of scenarios
>runsintegerNumber of times to run this scenario.
>seeds[long]A list of seeds to set for the runs of this simulation.
>scenarioDataobjecttrueKey value pairs of ticks to the inputs to set for those ticks. The tick `0` corrspond to the mode setup
inputobject\n

Details of input files to read the scenario data from. The name of the file will be used as the name of the scenarios.

\n \n

Required if scenarios field isn't present. If scenarios' fields are present, input will be ignored.

\n
>uristringtruePath to the files containing the scenario data
outputobjecttrueDetails of the simulation's output
>uristringtrueThis is the root directory that the files generated by the model will be output to. Within this directory, a folder will be created for the entire run named using the uuid of the run (which is returned in the POST response, and a folder will be created for each run of the scenario
customExportMetadataobjectAn object containing custom fields that will be included in the metadata.json file as part of the data output.
configobjectKey value object of config keys to update with values to update to.
\n
\n

The parameters runs and seeds both controls the number of runs per defined scenarios. However, runs offer no control over the seeds generation.\nThe seeds will be generated using an internal prng. If you wish to control the specific seeds used, then provide the SDK with the seeds parameter.

\n

Only one should be provided. If both are provided but runs does not match seeds' size, an error will be thrown.

\n
\n

Example request body with inline scenario definition

\n
{\"modelName\": \"Simple Credit Card\", \n  \"output\": {\"uri\": \"scenarioFolder\" },\n  \"scenarios\":[{\n    \"name\": \"myScenario\", \n    \"runs\": 10, \n    \"ticks\": 20,\n    \"scenarioData\": {\n      {\n        \"0\": {\"spending\": 200},\n        \"4\": {\"spending\": 100, \"interest\": 0.04}\n      }\n    }\n  }]\n}
\n

Example request body with scenario from input

\n
{\"modelName\": \"Simple Credit Card\", \n  \"output\": {\"uri\": \"scenarioFolder\" },\n  \"input\":{\"uri\": \"/path/to/inputFiles\"}\n}
\n
\nIf a request body has both inline scenario definition and and input path, the input path will be ignored.\n
\n

Response

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
StatusMeaningDescription
200OKSuccessfully created. The session ID is returned in a cookie named simudyneSessionID. You need to include this cookie in subsequent get requests.
404Not FoundSimulation not found.
\n

Response Schema

\n

Status Code 200

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
NameTypeRequiredDescription
idstring(uuid)true
namestringtrue
descriptionstringtrue
publicbooleantrue
sessionstring(uuid)truesimudyneSessionID cookie
kindstringtrue
\n

Example 200 response body

\n
{\n  \"id\": \"d7558ad9-3405-4a4c-972a-531a87fdcd27\",\n  \"name\": \"Game of Life\",\n  \"description\":\n    \"The Game of Life, also known simply as Life, is a cellular automaton devised by the British mathematician John Horton Conway in 1970.\",\n  \"public\": false,\n  \"session\": \"760b2d3e-20b2-42e6-9655-58e662e79e73\",\n  \"kind\": \"pojo\"\n}
\n
\n

Status Code 404

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
NameTypeRequired
messagestringtrue
\n

Example 404 response body

\n
{\n    \"message\": \"SimulationRegistry: Could not find requested simulation default.\"\n}
","headings":[{"value":"POST","depth":1},{"value":"Request","depth":2},{"value":"Body Schema","depth":3},{"value":"Response","depth":2},{"value":"Response Schema","depth":3}],"frontmatter":{"title":"/api/simulations/scenario","toc":null,"experimental":null}},"site":{"siteMetadata":{"title":"Simudyne Docs","latestVersion":"2.6"}}},"pageContext":{"absolutePath":"/home/vsts/work/1/s/content/2.5/rest_api/scenario/api_simulations_scenario.md","versioned":true,"version":"2.5","kind":"rest_api","pagePath":"/rest_api/scenario/api_simulations_scenario","chronology":{"prev":{"name":"Scenario Rest API","path":"/rest_api/scenario"},"next":{"name":"/api/simulations/scenario/{id}","path":"/rest_api/scenario/api_simulations_scenario_id"}},"lastUpdated":"2026-04-21T13:56:54.864Z"}}