Skip to content
Cloud APIs
/
/
/
VirtualScenario

VirtualScenario

A server-managed evaluation of a study workflow, created from a single workflow-input data source.

idstringrequired

The identifier of the virtual scenario.

Example:"01JY70N8TE9DG79NTQZDFMGEW3"
namestringrequired

The display name of the virtual scenario. It is optional and empty by default.

Example:"Price sensitivity - Base case"
inputDataSourceobject(VersionId)required

An identifier and version pair.

Example:
{
  "id": "01JY70N7ZGAQ02RZF2BTHDKRN8",
  "version": 1
}
resultDataSourceobject(VersionId)

An identifier and version pair.

Example:
{
  "id": "01JY70N7ZGAQ02RZF2BTHDKRN8",
  "version": 1
}
statestringrequired

The state of the virtual scenario.

  • Unknown - State is invalid or unknown.
  • Ready - The virtual scenario is ready to run an evaluation.
  • Running - The evaluation of the virtual scenario is running. The Running state is set when the virtual scenario is assigned realization filters with PATCH /v1/virtual-scenarios.
  • CompletedSuccessfully - The evaluation of the virtual scenario has completed successfully. Results are provided in the associated resultDataSource.
  • CompletedWithErrors - The evaluation of the virtual scenario has completed with errors.
  • Stopping - The evaluation of the virtual scenario is being stopped.
  • Stopped - The evaluation of the virtual scenario has been stopped.
  • Queued - The evaluation of the virtual scenario has been queued and runs when resources become available. The Queued state is set when the virtual scenario is assigned realization filters with PATCH /v1/virtual-scenarios and too many virtual scenario realizations are already running.
Enum:"Unknown""Ready""Running""CompletedSuccessfully""CompletedWithErrors""Stopping""Stopped""Queued"
Example:"Ready"
tagsArray of stringsrequired

List of tags associated with the virtual scenario. The StudyId tag is mandatory on every query. The platform also adds an EnsembleId tag for the ensemble that holds the realizations, and the workflow-input job typically propagates Iteration and Case tags.

Example:
[
  "StudyId:01JY6FMJMY0F6AJFV05V831SB4",
  "Iteration:Iteration1",
  "Case:case1",
  "EnsembleId:01JY70N8V117GD9G75EP3BP5GW"
]
realizationFiltersobject

The realizations to evaluate. Each outer item is one realization, and each inner item selects one data-provider outcome for one workflow-input node address. Setting realization filters transitions the virtual scenario to Running or Queued.

Example:
{
  "items": [
    { … },
    { … }
  ]
}
errorMessagesArray of strings

List of error messages associated with the virtual scenario, populated when the state is CompletedWithErrors.

Example:
[
  "data provider name 'Base' is duplicated on address '0:2:0'"
]
lastUpdatedAtstring or null, (date-time)required

The time when the virtual scenario was last updated.

Example:"2025-06-20T15:52:32.000Z"
promotionobject(VirtualScenarioPromotion)

The promotion of a virtual scenario into a regular scenario.

Example:
{
  "state": "Running"
}
{
  "id": "01JY70N8TE9DG79NTQZDFMGEW3",
  "name": "Price sensitivity - Base case",
  "inputDataSource": {
    "id": "01JY70N7ZGAQ02RZF2BTHDKRN8",
    "version": 1
  },
  "resultDataSource": {
    "id": "01JY70ZMBEECJH58ZQ1K9K19DH",
    "version": 1
  },
  "state": "CompletedSuccessfully",
  "tags": [
    "StudyId:01JY6FMJMY0F6AJFV05V831SB4",
    "Iteration:Iteration1",
    "Case:case1",
    "EnsembleId:01JY70N8V117GD9G75EP3BP5GW"
  ],
  "realizationFilters": {
    "items": [ … ]
  },
  "errorMessages": [],
  "lastUpdatedAt": "2025-06-20T15:57:24.000Z",
  "promotion": {
    "state": "Running"
  }
}