On This Page
> resources > docs > api > API Reference: Simulations

API Reference: Simulations

Simulations allow you to run what-if scenarios on your process models. You can configure processing times, resource allocations, and arrival rates to predict process behavior.

List simulations for a process

Endpoint: GET /v1/tenant/{tenantId}/processes/{processId}/simulations

Auth: Tenant-scoped API key · read scope

Parameters:

Name Type Location Required Description
tenantId string path Yes Format: uuid
processId string path Yes Format: uuid
limit integer query No Maximum number of items to return
offset integer query No Number of items to skip

Response (200):

List of simulations

[
	{
		"id": "00000000-0000-0000-0000-000000000000",
		"displayName": "string",
		"datasetName": "string",
		"startTime": "2024-03-15T16:30:00Z",
		"endTime": "2024-03-15T16:30:00Z",
		"useWarmUp": true
	}
]

Errors:

  • 400 Bad request: e.g. an invalid filter expression, a process without a model, an unsupported upload type or a missing required field
  • 401 Missing, invalid, disabled or expired API key
  • 404 Resource not found

Create a simulation (idempotent when an id is supplied)

Endpoint: POST /v1/tenant/{tenantId}/processes/{processId}/simulations

Auth: Tenant-scoped API key · write scope

Parameters:

Name Type Location Required Description
tenantId string path Yes Format: uuid
processId string path Yes Format: uuid

Request Body:

{
	"id": "00000000-0000-0000-0000-000000000000",
	"displayName": "string",
	"datasetName": "string",
	"startTime": "2024-03-15T16:30:00Z",
	"endTime": "2024-03-15T16:30:00Z",
	"useWarmUp": true
}
Field Type Required Description
id string No Optional id for idempotent retries (must be a UUID)
Format: uuid
displayName string No Simulation name
Default: New Simulation
datasetName string No Name of the dataset the simulation runs on
startTime string No Simulation start time
Format: date-time
endTime string No Simulation end time
Format: date-time
useWarmUp boolean No Whether to discard the warm-up period
Default: false

Response (201):

Simulation created

{
	"simulation": {
		"id": "00000000-0000-0000-0000-000000000000",
		"displayName": "string"
	},
	"message": "string"
}
Field Type Required Description
simulation object Yes
message string Yes

Errors:

  • 400 Bad request: e.g. an invalid filter expression, a process without a model, an unsupported upload type or a missing required field
  • 401 Missing, invalid, disabled or expired API key
  • 404 Resource not found
  • 409 The request conflicts with the current state (e.g. a seat gate or a reused id)

Get a simulation with its element settings, attributes and resources

Endpoint: GET /v1/tenant/{tenantId}/processes/{processId}/simulations/{simulationId}

Auth: Tenant-scoped API key · read scope

Parameters:

Name Type Location Required Description
tenantId string path Yes Format: uuid
processId string path Yes Format: uuid
simulationId string path Yes Format: uuid

Response (200):

Simulation details

{
	"simulation": {
		"id": "00000000-0000-0000-0000-000000000000",
		"displayName": "string",
		"datasetName": "string",
		"startTime": "2024-03-15T16:30:00Z",
		"endTime": "2024-03-15T16:30:00Z",
		"useWarmUp": true
	},
	"elementSettings": [
		{
			"simulationId": "00000000-0000-0000-0000-000000000000",
			"modelElementId": "00000000-0000-0000-0000-000000000000",
			"settings": {
				"processingTimeDistribution": [
					{
						"timeslot": {
							"periodicity": "Always"
						},
						"conditions": [
							{
								"type": "Values",
								"attribute": "string",
								"values": [
									"string"
								]
							}
						],
						"distribution": {
							"type": "Fixed",
							"value": 0
						},
						"timeUnit": "seconds",
						"rateUnit": "perTimeSlot"
					}
				],
				"processingTimeUnit": "seconds",
				"updateAttributeRules": [
					{
						"id": "string",
						"attributeId": "00000000-0000-0000-0000-000000000000",
						"timeslot": {
							"periodicity": "Always"
						},
						"conditions": [
							{
								"type": "Values",
								"attribute": "string",
								"values": [
									"string"
								]
							}
						],
						"newValue": "string",
						"isEnabled": true
					}
				],
				"requiredResources": [
					{
						"resourceId": "00000000-0000-0000-0000-000000000000",
						"amount": 0
					}
				],
				"caseStartsDistribution": [
					{
						"timeslot": {
							"periodicity": "Always"
						},
						"conditions": [
							{
								"type": "Values",
								"attribute": "string",
								"values": [
									"string"
								]
							}
						],
						"distribution": {
							"type": "Fixed",
							"value": 0
						},
						"timeUnit": "seconds",
						"rateUnit": "perTimeSlot"
					}
				],
				"caseStartsTimeUnit": "perTimeSlot",
				"capacityInterval": "perHour",
				"skipChanceDistribution": [
					{
						"timeslot": {
							"periodicity": "Always"
						},
						"conditions": [
							{
								"type": "Values",
								"attribute": "string",
								"values": [
									"string"
								]
							}
						],
						"distribution": {
							"type": "Fixed",
							"value": 0
						},
						"timeUnit": "seconds",
						"rateUnit": "perTimeSlot"
					}
				],
				"queueStrategy": "fifo",
				"chanceToTakeDistribution": [
					{
						"timeslot": {
							"periodicity": "Always"
						},
						"conditions": [
							{
								"type": "Values",
								"attribute": "string",
								"values": [
									"string"
								]
							}
						],
						"distribution": {
							"type": "Fixed",
							"value": 0
						},
						"timeUnit": "seconds",
						"rateUnit": "perTimeSlot"
					}
				]
			}
		}
	],
	"attributes": [
		{
			"id": "00000000-0000-0000-0000-000000000000",
			"simulationId": "00000000-0000-0000-0000-000000000000",
			"displayName": "string",
			"valueDistribution": {
				"type": "Number",
				"numberDistributions": [
					{
						"timeslot": {
							"periodicity": "Always"
						},
						"conditions": [
							{
								"type": "Values",
								"attribute": "string",
								"values": [
									"string"
								]
							}
						],
						"distribution": {
							"type": "Fixed",
							"value": 0
						},
						"timeUnit": "seconds",
						"rateUnit": "perTimeSlot",
						"id": "string",
						"isEnabled": true,
						"isDefault": true
					}
				],
				"textDistributions": [
					{
						"id": "string",
						"timeslot": {
							"periodicity": "Always"
						},
						"isEnabled": true,
						"isDefault": true,
						"mode": "list",
						"textValues": [
							{
								"id": "string",
								"value": "string",
								"chance": 0
							}
						]
					}
				]
			},
			"simulationAttributeType": "string"
		}
	],
	"resources": [
		{
			"id": "00000000-0000-0000-0000-000000000000",
			"simulationId": "00000000-0000-0000-0000-000000000000",
			"displayName": "string",
			"levelDistribution": [
				{
					"timeslot": {
						"periodicity": "Always"
					},
					"conditions": [
						{
							"type": "Values",
							"attribute": "string",
							"values": [
								"string"
							]
						}
					],
					"distribution": {
						"type": "Fixed",
						"value": 0
					},
					"timeUnit": "seconds",
					"rateUnit": "perTimeSlot"
				}
			],
			"attributeId": "00000000-0000-0000-0000-000000000000"
		}
	]
}
Field Type Required Description
simulation object Yes Simulation header
elementSettings object[] Yes Per-element simulation settings
attributes object[] Yes Simulated attributes
resources object[] Yes Resource pools

Errors:

  • 400 Bad request: e.g. an invalid filter expression, a process without a model, an unsupported upload type or a missing required field
  • 401 Missing, invalid, disabled or expired API key
  • 404 Resource not found

Update a simulation (fields and/or element settings)

Endpoint: PUT /v1/tenant/{tenantId}/processes/{processId}/simulations/{simulationId}

Auth: Tenant-scoped API key · write scope

Parameters:

Name Type Location Required Description
tenantId string path Yes Format: uuid
processId string path Yes Format: uuid
simulationId string path Yes Format: uuid

Request Body:

{
	"displayName": "string",
	"datasetName": "string",
	"startTime": "2024-03-15T16:30:00Z",
	"endTime": "2024-03-15T16:30:00Z",
	"useWarmUp": true,
	"elementSettings": [
		{
			"modelElementId": "00000000-0000-0000-0000-000000000000",
			"settings": {
				"caseStartsDistribution": [
					{
						"timeslot": {
							"periodicity": "Always"
						},
						"conditions": [
							{
								"type": "Values",
								"attribute": "string",
								"values": [
									"string"
								]
							}
						],
						"distribution": {
							"type": "Fixed",
							"value": 0
						},
						"timeUnit": "seconds",
						"rateUnit": "perTimeSlot"
					}
				],
				"processingTimeDistribution": [
					{
						"timeslot": {
							"periodicity": "Always"
						},
						"conditions": [
							{
								"type": "Values",
								"attribute": "string",
								"values": [
									"string"
								]
							}
						],
						"distribution": {
							"type": "Fixed",
							"value": 0
						},
						"timeUnit": "seconds",
						"rateUnit": "perTimeSlot"
					}
				]
			}
		}
	]
}
Field Type Required Description
displayName string No Simulation name
datasetName string No Name of the dataset the simulation runs on
startTime string No Simulation start time
Format: date-time
endTime string No Simulation end time
Format: date-time
useWarmUp boolean No Whether to discard the warm-up period
elementSettings object[] No Per-element settings overrides

Response (200):

Simulation updated

{
	"message": "string"
}
Field Type Required Description
message string Yes

Errors:

  • 400 Bad request: e.g. an invalid filter expression, a process without a model, an unsupported upload type or a missing required field
  • 401 Missing, invalid, disabled or expired API key
  • 404 Resource not found

Hard-delete a simulation

Endpoint: DELETE /v1/tenant/{tenantId}/processes/{processId}/simulations/{simulationId}

Auth: Tenant-scoped API key · write scope

Parameters:

Name Type Location Required Description
tenantId string path Yes Format: uuid
processId string path Yes Format: uuid
simulationId string path Yes Format: uuid

Response (200):

Simulation deleted

{
	"message": "string"
}
Field Type Required Description
message string Yes

Errors:

  • 400 Bad request: e.g. an invalid filter expression, a process without a model, an unsupported upload type or a missing required field
  • 401 Missing, invalid, disabled or expired API key
  • 404 Resource not found

These endpoints use AI to automatically generate simulation settings based on the process model.

Generate simulation settings via AI (async; poll the status endpoint)

Endpoint: POST /v1/tenant/{tenantId}/processes/{processId}/simulations/{simulationId}/generate-settings

Auth: Tenant-scoped API key · write scope · rate limit 2 req/s (burst 4)

Parameters:

Name Type Location Required Description
tenantId string path Yes Format: uuid
processId string path Yes Format: uuid
simulationId string path Yes Format: uuid

Request Body:

{
	"processDescription": "string",
	"additionalContext": "string"
}
Field Type Required Description
processDescription string No
additionalContext string No

Response (200):

Generation started / result

{
	"message": "string"
}
Field Type Required Description
message string Yes

Errors:

  • 400 Bad request: e.g. an invalid filter expression, a process without a model, an unsupported upload type or a missing required field
  • 401 Missing, invalid, disabled or expired API key
  • 404 Resource not found

Poll simulation settings generation status

Endpoint: GET /v1/tenant/{tenantId}/processes/{processId}/simulations/{simulationId}/generate-settings/status

Auth: Tenant-scoped API key · write scope

Parameters:

Name Type Location Required Description
tenantId string path Yes Format: uuid
processId string path Yes Format: uuid
simulationId string path Yes Format: uuid

Response (200):

Generation status

{
	"message": "string"
}
Field Type Required Description
message string Yes

Errors:

  • 400 Bad request: e.g. an invalid filter expression, a process without a model, an unsupported upload type or a missing required field
  • 401 Missing, invalid, disabled or expired API key
  • 404 Resource not found

Start a simulation run (async; results land in the process datatables)

Endpoint: POST /v1/tenant/{tenantId}/processes/{processId}/simulations/{simulationId}/run

Auth: Tenant-scoped API key · write scope · rate limit 5 req/s (burst 10)

Parameters:

Name Type Location Required Description
tenantId string path Yes Format: uuid
processId string path Yes Format: uuid
simulationId string path Yes Format: uuid

Response (200):

Simulation started

{
	"message": "string"
}
Field Type Required Description
message string Yes

Errors:

  • 400 Bad request: e.g. an invalid filter expression, a process without a model, an unsupported upload type or a missing required field
  • 401 Missing, invalid, disabled or expired API key
  • 404 Resource not found

Get the status of the last simulation run (derived from the output datatable)

Endpoint: GET /v1/tenant/{tenantId}/processes/{processId}/simulations/{simulationId}/run/status

Auth: Tenant-scoped API key · read scope

Parameters:

Name Type Location Required Description
tenantId string path Yes Format: uuid
processId string path Yes Format: uuid
simulationId string path Yes Format: uuid

Response (200):

Run status

{
	"state": "notStarted",
	"startedAt": "2024-03-15T16:30:00Z",
	"completedAt": "2024-03-15T16:30:00Z",
	"step": "string",
	"casesSimulated": 0,
	"targetCases": 0,
	"eventsGenerated": 0,
	"errorMessage": "string",
	"simulationId": "00000000-0000-0000-0000-000000000000"
}
Field Type Required Description
state notStarted | running | processing | ready | error Yes Allowed values: notStarted, running, processing, ready, error
startedAt string No Format: date-time
completedAt string No Format: date-time
step string No
casesSimulated number No
targetCases number No
eventsGenerated number No
errorMessage string No
simulationId string Yes Format: uuid

Errors:

  • 400 Bad request: e.g. an invalid filter expression, a process without a model, an unsupported upload type or a missing required field
  • 401 Missing, invalid, disabled or expired API key
  • 404 Resource not found

Related Documentation