Simulations
Returns the workspace's simulation runs, newest first, whether they were started via this API, the UI, or an application. Cursor-paginated; pagination.total is the count matching the current filters. Result payloads are omitted — use /simulations/{id}/results or /simulations/{id}/export/{format}. Each run carries exportFormats: the formats /simulations/{id}/export/{format} accepts for it — ["json", "csv"] for a completed forecast-shaped run on a multi-environment (panel) model, ["json"] for any other completed run, [] while a run is unfinished. Single-environment models produce no panel forecast, so they never offer csv. A csv entry means the run is eligible by model and scenario shape; the export additionally requires the panel result artifacts to still be present in the data lake and returns 400 if they are not.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Page size (1-1000, default 50).
1Opaque cursor from a previous response's pagination.cursor.
exampleFilter by run status.
exampleOnly return runs of this digital twin.
123Successful response
Bad Request
Unauthorized
Forbidden
Too Many Requests; the response carries Retry-After
Internal Server Error
GET /api/v1/workspaces/{wsId}/simulations HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": [],
"pagination": {
"cursor": "text",
"hasMore": true,
"total": 1
}
}Runs a digital-twin simulation with a scenario. Body: digitalTwinId, digitalTwinVersionId, scenario (key-value inputs), optional environmentGroupIds, optional webhookUrl. Proxies to data-service POST /api/digital-twin/execute-run. Returns 202 with runId and links (self, results). Simulation runs asynchronously; poll GET /simulations/{runId} for status and GET /simulations/{runId}/results for outputs when ready.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Id of the digital twin to simulate
Id of the trained version to run against
Multi-environment (panel) twins: saved environment groups to scope the run to. The server resolves each group's membership against the version at submit time and narrows the run to it: when the scenario also names environments the two are intersected, never unioned, so a group can only ever shrink a scenario. An empty intersection is a 400. What it resolved is frozen onto the run as environmentGroupSnapshots. Ignored by single-environment twins.
Optional URL called when the run completes
Accepted; poll the linked resource for completion
Bad Request
Unauthorized
Forbidden
Unprocessable Entity
Too Many Requests; the response carries Retry-After
Internal Server Error
POST /api/v1/workspaces/{wsId}/simulations HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 170
{
"digitalTwinId": "text",
"digitalTwinVersionId": "text",
"scenario": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"environmentGroupIds": [
"text"
],
"webhookUrl": "https://example.com"
}{
"data": {
"runId": "text",
"status": "text",
"createdAt": "text",
"links": {
"self": "text",
"results": "text"
}
}
}Returns the simulation run by id. Read from platform MongoDB (digitalTwinRun collection). Must belong to the workspace. Includes status, inputs, metadata, and exportFormats (see the list endpoint); use /simulations/{id}/results for output data. A run submitted with environmentGroupIds also carries environmentGroupSnapshots: one entry per group ({id, name, envKeys, droppedEnvKeys, notice?}) recording the membership the server resolved at submit time. It is a frozen record, not a live read — editing or deleting the group afterwards leaves it untouched, and droppedEnvKeys names members the version could not honour.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Successful response
Unauthorized
Forbidden
Not Found
Too Many Requests; the response carries Retry-After
Internal Server Error
GET /api/v1/workspaces/{wsId}/simulations/{id} HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": {
"id": "text",
"organisationId": "text",
"workspaceId": "text",
"digitalTwinId": "text",
"digitalTwinVersionIds": [
"text"
],
"userQuery": null,
"timeStarted": "text",
"timeCompleted": null,
"status": "pending",
"error": null,
"progress": {
"percentage": 1,
"state": "text",
"eta": null
},
"scenario": {
"type": "text",
"objectives": [
{
"direction": "maximise",
"variable": "text",
"metricSqlQuery": "text",
"unit": {},
"weight": 1,
"variablesRelevantToMetric": [
"text"
],
"target": {
"type": "percentage",
"value": null
},
"conceptId": null,
"conceptEditVersion": 1
}
],
"conditions": [
{
"variable": "text",
"operator": "eq",
"value": 1
}
],
"decisionVars": [
"text"
],
"variableConstraints": [
{
"variable": "text",
"type": "range",
"minValue": null,
"maxValue": null,
"allowedValues": [
"text"
],
"maxChangePercent": 1,
"conditionalAllowedValues": [
{
"condition": {
"variable": "text",
"operator": "eq",
"value": 1
},
"allowedValues": [
"text"
],
"minValue": null,
"maxValue": null
}
]
}
],
"metricConstraints": [
{
"metricName": "text",
"sqlQuery": "text",
"constraintType": "min_value",
"value": null,
"booleanValue": null,
"temporal": {
"startDate": null,
"endDate": null,
"startTimestampMs": null,
"endTimestampMs": null,
"intervalSteps": null
}
}
],
"segmentDefinitions": [
{
"id": "text",
"description": null,
"conditions": [
{
"variable": "text",
"operator": "eq",
"value": 1
}
]
}
],
"enableSegmentInterventions": false,
"interventionTypes": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"interventionCountConfig": {
"maxInterventions": 1,
"optimizeCount": true
}
},
"outputs": {
"ANY_ADDITIONAL_PROPERTY": {
"results": {
"ANY_ADDITIONAL_PROPERTY": [
{
"timestamp": null,
"prediction": null,
"probabilities": [
1
],
"lowerBound": [
1
],
"upperBound": [
1
],
"confidenceLevel": null
}
]
},
"changepoints": {
"ANY_ADDITIONAL_PROPERTY": [
{
"stepIndex": 1,
"timestamp": 1,
"direction": "up",
"magnitude": 1,
"primaryDriver": "text",
"driverContribution": 1
}
]
},
"history": {
"ANY_ADDITIONAL_PROPERTY": {
"timestamps": [
1
],
"values": [
null
]
}
}
}
},
"outputsStorageType": "inline",
"resultsSummary": {
"summary": "text",
"keyPoints": [
"text"
]
},
"environmentGroupSnapshots": [
{
"id": "text",
"name": "text",
"envKeys": [
"text"
],
"droppedEnvKeys": [
"text"
],
"notice": null
}
],
"executedByUserId": null,
"applicationExecutionId": null,
"exportFormats": [
"json"
]
}
}Returns the simulation outputs (run.outputs) from platform MongoDB. 404 if the run has no outputs yet (e.g. still running or failed before producing results). Use after GET /simulations/{id} shows completion.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Successful response
Payload not declared in this repo
Unauthorized
Forbidden
Not Found
Too Many Requests; the response carries Retry-After
Internal Server Error
GET /api/v1/workspaces/{wsId}/simulations/{id}/results HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": "text"
}Reads a completed batch-scoring run back: digest (verdict counts, top drivers, row summaries) plus one page of per-row detail with each row's full change list. Query params: limit (default 50), cursor. 409 while the run is still executing; 404 when the run carries no counterfactual results (it was not a scoring run).
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Page size (1-1000, default 50).
1Opaque cursor from a previous response's pagination.cursor.
exampleSuccessful response
Bad Request
Unauthorized
Forbidden
Not Found
Conflict
Too Many Requests; the response carries Retry-After
Internal Server Error
GET /api/v1/workspaces/{wsId}/simulations/{id}/score HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": [],
"pagination": {
"cursor": "text",
"hasMore": true,
"total": 1
}
}Reads the full dose-response curve of a completed range-intervention (sweep) run, one metric per call. Query param metric selects the curve; omit it to list the available metrics plus the sweep digest. Each point carries the swept value, mean, standard deviation, and confidence interval. 409 while the run is still executing; 404 when the run carries no sweep.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Which metric's curve to return; required when the run carries several.
exampleWhich environment's curve to return on a multi-environment (panel) run. Required there: without it the response lists the available environments instead of picking one.
exampleNarrows the environment listing on a panel run to keys containing this text.
exampleSuccessful response
Payload not declared in this repo
Unauthorized
Forbidden
Not Found
Conflict
Too Many Requests; the response carries Retry-After
Internal Server Error
GET /api/v1/workspaces/{wsId}/simulations/{id}/sweep HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": "text"
}Downloads a completed simulation as a file. format=json returns a self-contained bundle (run metadata, scenario, and full outputs) and works for every scenario type. format=csv streams the server-side wide forecast CSV and is only available for forecast-shaped simulations (forecast, panel_forecast, prediction) that ran against a multi-environment (panel) model with parquet-backed results; anything else gets a 400 pointing at format=json. Check exportFormats on the run to know in advance. 400 if the run has not completed. Requires the exports:read scope.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Export format
csvPossible values: Successful response
Payload not declared in this repo
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests; the response carries Retry-After
Internal Server Error
GET /api/v1/workspaces/{wsId}/simulations/{id}/export/{format} HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": "text"
}Last updated