# Virtual Scenarios

The Virtual Scenarios API provides an optimized, high-volume interface to
the FDPlan evaluation platform.

A virtual scenario is a server-managed way to evaluate a study workflow that
bypasses the interactive decision and choice framing process. Each virtual scenario
starts from a single workflow-input data source that supplies every input node
of the study workflow, and the platform creates it automatically when a
workflow-input data source job succeeds. Virtual scenarios are typically driven
by external controllers and optimization engines to run sensitivity analyses
and other large realization sweeps, and they are not shown in the FDPlan user
interface as regular scenarios.

This API has no POST endpoint. To create virtual scenarios, submit a
workflow-input data source job through the Data Sources API. Use this API to
list virtual scenarios, set the realizations to evaluate, monitor the
per-realization result states, promote a high-performing virtual scenario to a
regular scenario, and remove virtual scenarios.

## Client ID

* prod-nam-services-fdplan.slbservice.com
* prod-eu-services-fdplan.slbservice.com
* prod-au-services-fdplan.slbservice.com
* prod-id-services-fdplan.slbservice.com
* production-services-fdplan.slbservice.com


# Table of contents

* [Get virtual scenarios](#get-virtual-scenarios)
* [Update virtual scenarios](#update-virtual-scenarios)
* [Update a virtual scenario](#update-a-virtual-scenario)
* [Get results states](#get-results-states)


# Get virtual scenarios 

Get a paginated list of virtual scenarios for a study.

The `StudyId` tag is mandatory. Narrow the results further by `state` and
by the `inputDataSourceIds` of the workflow-input data sources that the
virtual scenarios were created from.

**Parameters**

* **slb-partition-id** Data partition identifier.
* **state** The virtual scenario state to filter for.
* **tags** The tags for the virtual scenarios to get. Virtual scenarios whose tags match the provided tags are
returned. The StudyId tag is mandatory, for example StudyId:01JY6FMJMY0F6AJFV05V831SB4.
* **inputDataSourceIds** The identifiers of the workflow-input data sources associated with the virtual scenarios to get. Virtual
scenarios whose input data source identifier matches any of the provided identifiers are returned. Provide a maximum
of 100 identifiers, separated by commas, for example 01JY70N7ZGAQ02RZF2BTHDKRN8,01HKMNGN05NYGWD90BQD9JC6KH.
* **pageNumber** The number of the page in the list of virtual scenarios.
* **pageSize** The number of virtual scenarios per page. The maximum allowed page size is 200.
* **includeCount** Returns the quota and total count alongside the virtual scenarios.
* **onlyCount** Returns the quota, the total count, and an empty list of virtual scenarios.


Example
curl -request GET 
--url 'https://api.delfi.slb.com/planning/virtual-scenarios/v1/virtual-scenarios?tags=value' 
--header 'Authorization: value' 
--header 'appkey: value' 
--header 'content-type: application/json' 
--header 'slb-partition-id: header'

Response: 200
{
"total": 4,
"items": [
{
"id": "01JY70N8TE9DG79NTQZDFMGEW3",
"name": "",
"inputDataSource": {
"id": "01JY70N7ZGAQ02RZF2BTHDKRN8",
"version": 1
},
"state": "Ready",
"tags": [
"StudyId:01JY6FMJMY0F6AJFV05V831SB4",
"Iteration:Iteration1",
"Case:case1",
"EnsembleId:01JY70N8V117GD9G75EP3BP5GW"
],
"lastUpdatedAt": "2025-06-20T15:52:32.000Z"
},
{
"id": "01JY70N8TE64GJ0CZE6M900M99",
"name": "Price sensitivity - Low case",
"inputDataSource": {
"id": "01JY70N7ZGAQ02RZF2BTHDKRN8",
"version": 1
},
"state": "Running",
"tags": [
"StudyId:01JY6FMJMY0F6AJFV05V831SB4",
"Iteration:Iteration1",
"Case:case1",
"EnsembleId:01JY70N8V117GD9G75EP3BP5GW"
],
"realizationFilters": {
"items": [
{
"items": [
{
"name": "Base",
"nodeAddress": "0:2:0"
},
{
"name": "Cost Profile.xlsx",
"nodeAddress": "0:2:1"
},
{
"name": "Base",
"nodeAddress": "0:2:2"
},
{
"name": "Base",
"nodeAddress": "0:2:3"
}
]
},
{
"items": [
{
"name": "Base",
"nodeAddress": "0:2:0"
},
{
"name": "Cost Profile.xlsx",
"nodeAddress": "0:2:1"
},
{
"name": "Low",
"nodeAddress": "0:2:2"
},
{
"name": "Base",
"nodeAddress": "0:2:3"
}
]
}
]
},
"lastUpdatedAt": "2025-06-20T15:55:18.000Z"
},
{
"id": "01JY70N8TE7C2K9F4ZB1RM5QPA",
"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": [
{
"items": [
{
"name": "Base",
"nodeAddress": "0:2:0"
},
{
"name": "Cost Profile.xlsx",
"nodeAddress": "0:2:1"
},
{
"name": "Base",
"nodeAddress": "0:2:2"
},
{
"name": "Base",
"nodeAddress": "0:2:3"
}
]
}
]
},
"lastUpdatedAt": "2025-06-20T15:57:24.000Z"
},
{
"id": "01JY70N8TE8H3D0YJ6P2WQ4XYZ",
"name": "Price sensitivity - High case",
"inputDataSource": {
"id": "01JY70N7ZGAQ02RZF2BTHDKRN8",
"version": 1
},
"state": "CompletedWithErrors",
"tags": [
"StudyId:01JY6FMJMY0F6AJFV05V831SB4",
"Iteration:Iteration1",
"Case:case1",
"EnsembleId:01JY70N8V117GD9G75EP3BP5GW"
],
"realizationFilters": {
"items": [
{
"items": [
{
"name": "Base",
"nodeAddress": "0:2:0"
},
{
"name": "Cost Profile.xlsx",
"nodeAddress": "0:2:1"
},
{
"name": "High",
"nodeAddress": "0:2:2"
},
{
"name": "Base",
"nodeAddress": "0:2:3"
}
]
}
]
},
"errorMessages": [
"data provider name 'Base' is duplicated on address '0:2:0'"
],
"lastUpdatedAt": "2025-06-20T15:58:12.000Z"
}
]
}

[Back to table of contents](#toc)

# Update virtual scenarios 

Update properties of the virtual scenarios specified in the request, using JSON Patch operations against the collection.

- Setting `realizationFilters` triggers an evaluation of the provided realizations and transitions the virtual scenario to `Running` or `Queued`.
- Setting `state` to `Stopping` cancels the evaluation of virtual scenarios that are still `Running`.
- The `replace` operation is allowed with the path `/{virtualScenarioId}/name`, `/{virtualScenarioId}/realizationFilters`, or `/{virtualScenarioId}/state`.
- The `remove` operation is allowed with the path `/{virtualScenarioId}`.
- If any of the supplied virtual scenarios is not found during `replace` or `remove`, then no changes are applied and a not-found response is returned.
- A 400 Bad request response is returned if you:
  - try to replace the value of any property in the path other than name, realization filters, and state; or
  - provide no realization filters for a virtual scenario; or
  - provide realization filters that contain duplicate realizations; or
  - attempt to update a virtual scenario that is not in the `Ready` state; or
  - provide more than 200 virtual scenario identifiers in the request payload; or
  - provide more than 100 realization filters for a single virtual scenario; or
  - provide both state and realization filters for the same virtual scenario; or
  - provide an illegal value to cancel or stop a virtual scenario, where only `Stopping` is allowed; or
  - mix `replace` operations with `remove` operations.


**Parameters**

* **slb-partition-id** Data partition identifier.
* **tags** The tags for the virtual scenarios to patch. Virtual scenarios whose tags match the provided tags are
patched. The StudyId tag is mandatory, for example StudyId:01JY6FMJMY0F6AJFV05V831SB4.
* **patchVirtualScenariosParams** The parameters to update virtual scenarios.


Example
curl -request PATCH 
--url 'https://api.delfi.slb.com/planning/virtual-scenarios/v1/virtual-scenarios?tags=value' 
--header 'Authorization: value' 
--header 'appkey: value' 
--header 'content-type: application/json' 
--header 'slb-partition-id: header' 
--data '[
{
"op": "replace",
"path": "/01JY70N8TE9DG79NTQZDFMGEW3/name",
"value": "Price sensitivity - Base case"
},
{
"op": "replace",
"path": "/01JY70N8TE9DG79NTQZDFMGEW3/realizationFilters",
"value": {
"items": [
{
"items": [
{
"name": "Base",
"nodeAddress": "0:2:0"
},
{
"name": "Cost Profile.xlsx",
"nodeAddress": "0:2:1"
},
{
"name": "Base",
"nodeAddress": "0:2:2"
},
{
"name": "Base",
"nodeAddress": "0:2:3"
}
]
},
{
"items": [
{
"name": "Base",
"nodeAddress": "0:2:0"
},
{
"name": "Cost Profile.xlsx",
"nodeAddress": "0:2:1"
},
{
"name": "Low",
"nodeAddress": "0:2:2"
},
{
"name": "Base",
"nodeAddress": "0:2:3"
}
]
}
]
}
},
{
"op": "replace",
"path": "/01JY70N8TE64GJ0CZE6M900M99/name",
"value": "Price sensitivity - Low case"
},
{
"op": "replace",
"path": "/01JY70N8TE9DG79NTQZDFMGEW3/state",
"value": "Stopping"
},
{
"op": "remove",
"path": "/01JY70N8TE9DG79NTQZDFMGEW3"
}
]'

Response: 200
{
"total": 4,
"items": [
{
"id": "01JY70N8TE9DG79NTQZDFMGEW3",
"name": "",
"inputDataSource": {
"id": "01JY70N7ZGAQ02RZF2BTHDKRN8",
"version": 1
},
"state": "Ready",
"tags": [
"StudyId:01JY6FMJMY0F6AJFV05V831SB4",
"Iteration:Iteration1",
"Case:case1",
"EnsembleId:01JY70N8V117GD9G75EP3BP5GW"
],
"lastUpdatedAt": "2025-06-20T15:52:32.000Z"
},
{
"id": "01JY70N8TE64GJ0CZE6M900M99",
"name": "Price sensitivity - Low case",
"inputDataSource": {
"id": "01JY70N7ZGAQ02RZF2BTHDKRN8",
"version": 1
},
"state": "Running",
"tags": [
"StudyId:01JY6FMJMY0F6AJFV05V831SB4",
"Iteration:Iteration1",
"Case:case1",
"EnsembleId:01JY70N8V117GD9G75EP3BP5GW"
],
"realizationFilters": {
"items": [
{
"items": [
{
"name": "Base",
"nodeAddress": "0:2:0"
},
{
"name": "Cost Profile.xlsx",
"nodeAddress": "0:2:1"
},
{
"name": "Base",
"nodeAddress": "0:2:2"
},
{
"name": "Base",
"nodeAddress": "0:2:3"
}
]
},
{
"items": [
{
"name": "Base",
"nodeAddress": "0:2:0"
},
{
"name": "Cost Profile.xlsx",
"nodeAddress": "0:2:1"
},
{
"name": "Low",
"nodeAddress": "0:2:2"
},
{
"name": "Base",
"nodeAddress": "0:2:3"
}
]
}
]
},
"lastUpdatedAt": "2025-06-20T15:55:18.000Z"
},
{
"id": "01JY70N8TE7C2K9F4ZB1RM5QPA",
"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": [
{
"items": [
{
"name": "Base",
"nodeAddress": "0:2:0"
},
{
"name": "Cost Profile.xlsx",
"nodeAddress": "0:2:1"
},
{
"name": "Base",
"nodeAddress": "0:2:2"
},
{
"name": "Base",
"nodeAddress": "0:2:3"
}
]
}
]
},
"lastUpdatedAt": "2025-06-20T15:57:24.000Z"
},
{
"id": "01JY70N8TE8H3D0YJ6P2WQ4XYZ",
"name": "Price sensitivity - High case",
"inputDataSource": {
"id": "01JY70N7ZGAQ02RZF2BTHDKRN8",
"version": 1
},
"state": "CompletedWithErrors",
"tags": [
"StudyId:01JY6FMJMY0F6AJFV05V831SB4",
"Iteration:Iteration1",
"Case:case1",
"EnsembleId:01JY70N8V117GD9G75EP3BP5GW"
],
"realizationFilters": {
"items": [
{
"items": [
{
"name": "Base",
"nodeAddress": "0:2:0"
},
{
"name": "Cost Profile.xlsx",
"nodeAddress": "0:2:1"
},
{
"name": "High",
"nodeAddress": "0:2:2"
},
{
"name": "Base",
"nodeAddress": "0:2:3"
}
]
}
]
},
"errorMessages": [
"data provider name 'Base' is duplicated on address '0:2:0'"
],
"lastUpdatedAt": "2025-06-20T15:58:12.000Z"
}
]
}

[Back to table of contents](#toc)

# Update a virtual scenario 

Promote a single virtual scenario to a regular scenario.

Promotion turns a high-performing virtual scenario into a regular scenario that is visible in the FDPlan user interface, with its data sources materialized from the realization inputs. The only allowed operation is to `replace` the path `/promotion/state` with the value `Running`. While promotion runs, the `promotion` field is present on the virtual scenario resource.

**Parameters**

* **slb-partition-id** Data partition identifier.
* **virtualScenarioId** The identifier of the virtual scenario to patch.
* **tags** The tags of the virtual scenario to patch. The StudyId tag is mandatory, for example StudyId:01JY6FMJMY0F6AJFV05V831SB4.
* **patchParams** The parameters to update a single virtual scenario.


Example
curl -request PATCH 
--url 'https://api.delfi.slb.com/planning/virtual-scenarios/v1/virtual-scenarios/{virtualScenarioId}?tags=value' 
--header 'Authorization: value' 
--header 'appkey: value' 
--header 'content-type: application/json' 
--header 'slb-partition-id: header' 
--data '[
{
"op": "replace",
"path": "/promotion/state",
"value": "Running"
}
]'

Response: 200
{
"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": [
{
"items": [
{
"name": "Base",
"nodeAddress": "0:2:0"
},
{
"name": "Cost Profile.xlsx",
"nodeAddress": "0:2:1"
},
{
"name": "Base",
"nodeAddress": "0:2:2"
},
{
"name": "Base",
"nodeAddress": "0:2:3"
}
]
},
{
"items": [
{
"name": "Base",
"nodeAddress": "0:2:0"
},
{
"name": "Cost Profile.xlsx",
"nodeAddress": "0:2:1"
},
{
"name": "Low",
"nodeAddress": "0:2:2"
},
{
"name": "Base",
"nodeAddress": "0:2:3"
}
]
}
]
},
"errorMessages": [
],
"lastUpdatedAt": "2025-06-20T15:57:24.000Z",
"promotion": {
"state": "Running"
}
}

[Back to table of contents](#toc)

# Get results states 

Get the per-realization result states for the specified virtual scenarios.

Use this endpoint to monitor the evaluation progress of each realization in `realizationStates` and the result-processing progress in `dataSourceProcessingState`. The ensemble-results data source is returned in `dataSource` once `dataSourceProcessingState` reaches `CompletedSuccessfully`.

**Parameters**

* **slb-partition-id** Data partition identifier.
* **tags** The tags of the virtual scenarios. The StudyId tag is mandatory, for example StudyId:01JY6FMJMY0F6AJFV05V831SB4.
* **virtualScenarioIds** The identifiers of the virtual scenarios. Provide a maximum of 100 identifiers in a comma-separated
list.


Example
curl -request GET 
--url 'https://api.delfi.slb.com/planning/virtual-scenarios/v1/virtual-scenarios/results-states?tags=value&virtualScenarioIds=value' 
--header 'Authorization: value' 
--header 'appkey: value' 
--header 'content-type: application/json' 
--header 'slb-partition-id: header'

Response: 200
{
"items": [
{
"virtualScenarioId": "01JY70N8TE9DG79NTQZDFMGEW3",
"dataSource": {
"id": "01JY70ZMBEECJH58ZQ1K9K19DH",
"version": 1
},
"dataSourceProcessingErrors": [
],
"dataSourceProcessingState": "CompletedSuccessfully",
"tags": [
"StudyId:01JY6FMJMY0F6AJFV05V831SB4",
"Iteration:Iteration1",
"Case:case1",
"EnsembleId:01JY70N8V117GD9G75EP3BP5GW"
],
"realizationStates": {
"items": [
{
"uri": "01JY6FMJMY0F6AJFV05V831SB4/realizations/01JY70TF3Q64GJ0CZE6M900M99",
"version": 5,
"state": "CompletedSuccessfully",
"computationStates": {
"items": [
{
"address": "0:1:0",
"runState": "CompletedSuccessfully"
},
{
"address": "1:1:0",
"runState": "CompletedSuccessfully"
}
]
},
"lastUpdatedAt": "2025-06-20T15:57:24.000Z"
}
]
}
},
{
"virtualScenarioId": "01JY70N8TE64GJ0CZE6M900M99",
"dataSource": {
"id": "01JY70ZMBEECJH58ZQ1K9K19DH",
"version": 1
},
"dataSourceProcessingErrors": [
"first error message",
"second error message"
],
"dataSourceProcessingState": "CompletedWithErrors",
"tags": [
"StudyId:01JY6FMJMY0F6AJFV05V831SB4",
"Iteration:Iteration1",
"Case:case1",
"EnsembleId:01JY70N8V117GD9G75EP3BP5GW"
],
"realizationStates": {
"items": [
{
"uri": "01JY6FMJMY0F6AJFV05V831SB4/realizations/01JY70TF3Q5957VSF9Q7MG0B3D",
"version": 2,
"state": "CompletedWithErrors",
"computationStates": {
"items": [
{
"address": "0:1:0",
"runState": "CompletedSuccessfully"
},
{
"address": "1:1:0",
"runState": "CompletedWithErrors",
"errors": {
"items": [
{
"message": "first error message",
"addresses": [
"1:2:0",
"1:1:0"
]
},
{
"message": "second error message",
"addresses": [
"1:2:1",
"1:1:0"
]
}
]
}
}
]
},
"lastUpdatedAt": "2025-06-20T15:57:24.000Z"
},
{
"uri": "01JY6FMJMY0F6AJFV05V831SB4/realizations/01JY70TF3Q5957VSF9Q7MG0B3E",
"version": 2,
"state": "Running",
"computationStates": {
"items": [
{
"address": "0:1:0",
"runState": "Running"
},
{
"address": "1:1:0",
"runState": "Running"
}
]
},
"lastUpdatedAt": "2025-06-20T15:55:24.000Z"
}
]
}
}
]
}

[Back to table of contents](#toc)