Start simulation runs

POST/api/v1/simulations/runs

Authorization
Permission	`simulations.runs.dispatch`
Workspace scope	required
Scope target	workspace

Request body

Request body fields
Field	Type	Required	Nullable	Default
inputSnapshotId	string	required	non-null	—
releaseAlias	string	required	non-null	—
scenarioRevisionId	string	optional	non-null	—
seed	integer	optional	non-null	—
trials	integer	optional	non-null	—
horizonDays	integer	optional	non-null	—
variants	integer	optional	non-null	—
parameterOverrides	object	optional	non-null	—
requestKey	string	optional	non-null	—

Response

201

Response fields
Field	Type	Required	Nullable	Default
data	object	required	non-null	—
data.runId	string	required	non-null	—
data.companyId	string	required	non-null	—
data.workspaceId	string	required	non-null	—
data.workUnitId	string	required	non-null	—
data.status	"requested" \| "waiting_capacity" \| "preparing" \| "running" \| "cancel_requested" \| "succeeded" \| "failed" \| "cancelled" \| "blocked"	required	non-null	—
data.revision	integer	required	non-null	—
data.refs	object	required	non-null	—
data.refs.releaseId	string	required	non-null	—
data.refs.releaseAlias	string	required	non-null	—
data.refs.packageVersionId	string	required	non-null	—
data.refs.packageKey	string	required	non-null	—
data.refs.packageVersion	integer	required	non-null	—
data.refs.configurationVersionId	string	required	non-null	—
data.refs.configKey	string	required	non-null	—
data.refs.configVersion	integer	required	non-null	—
data.refs.inputSnapshotId	string	required	non-null	—
data.refs.scenarioRevisionId	string	optional	non-null	—
data.refs.sandboxRevisionRef	string	optional	non-null	—
data.refs.seed	integer	required	non-null	—
data.refs.trials	integer	required	non-null	—
data.refs.horizonDays	integer	required	non-null	—
data.refs.variants	integer	required	non-null	—
data.refs.parameters	object	required	non-null	{}
data.refs.maxComputeUsdMicros	integer	required	non-null	—
data.refs.executorKind	string	required	non-null	—
data.refs.resourceClass	string	required	non-null	—
data.refs.runtimeKey	string	required	non-null	—
data.refs.runtimeVersion	integer	required	non-null	—
data.refs.outputProtocolKey	string	required	non-null	—
data.refs.outputProtocolVersion	integer	required	non-null	—
data.refs.inputProtocolKey	string	required	non-null	—
data.refs.inputProtocolVersion	integer	required	non-null	—
data.requestedBy	string	required	non-null	—
data.admissionAttempt	integer	required	non-null	—
data.receipt	object	optional	non-null	—
data.receipt.workUnitId	string	required	non-null	—
data.receipt.revision	string	required	non-null	—
data.receipt.pools	array	required	non-null	—
data.receipt.expiresAtEpochSeconds	integer	required	non-null	—
data.reservationExpiresAt	string	optional	non-null	—
data.providerExecutionId	string	optional	non-null	—
data.inputManifest	object	optional	non-null	—
data.inputManifest.s3Key	string	required	non-null	—
data.inputManifest.contentDigest	string	required	non-null	—
data.inputManifest.sizeBytes	integer	optional	non-null	—
data.outputManifest	object	optional	non-null	—
data.outputManifest.s3Key	string	required	non-null	—
data.outputManifest.contentDigest	string	required	non-null	—
data.outputManifest.sizeBytes	integer	optional	non-null	—
data.settlement	object	optional	non-null	—
data.settlement.actualComputeUsdMicros	integer	required	non-null	—
data.settlement.settledAt	string	required	non-null	—
data.settlement.reservationsReleased	boolean	required	non-null	—
data.blockedReason	string	optional	non-null	—
data.supervisorKey	string	optional	non-null	—
data.createdAt	string	required	non-null	—
data.updatedAt	string	required	non-null	—
data.statusUpdatedAt	string	required	non-null	—

Declared failures

Declared failures
ACCESS_DENIED	403 — not retryable
CORE_ERROR	500 — not retryable
GOVERNANCE_DENIED	403 — not retryable
QUOTA_DENIED	429 — retryable
REQUEST_IDENTITY_INTENT_CONFLICT	409 — not retryable
VALIDATION_ERROR	400 — not retryable
VALIDATION_INPUT_ERROR	400 — not retryable

Durable identity

Durable identity
Kind	request-identity
Request fields	requestKey
Conflict	REQUEST_IDENTITY_INTENT_CONFLICT

Readback

The effect completes asynchronously; reacquire the result with:

simulations.runs.read

Request example

Schematic only. Replace placeholders with real values and include all required nested fields.

POST /api/v1/simulations/runs HTTP/1.1
Authorization: Bearer <token>
x-merulan-workspace-id: <workspace-id>
Content-Type: application/json

{
  "inputSnapshotId": "<inputSnapshotId>",
  "releaseAlias": "<releaseAlias>"
}