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