Scenario Run API Reference

The Scenario Run API lets you trigger an economics run on an existing scenario and poll for the result. All run operations are asynchronous: the POST endpoint returns immediately with a jobId, and you use the GET endpoint to track progress.

Endpoints are nested under a project's scenario:

POST /v1/projects/:projectId/scenarios/:scenarioId/run
GET  /v1/projects/:projectId/scenarios/:scenarioId/run/:jobId

The results of a completed run are read through the existing Econ Runs endpoints (one-liners, monthly exports, monthly econ results) using the econRunId returned in the run status result.

Triggering a Run

POST /v1/projects/:projectId/scenarios/:scenarioId/run

Submits an asynchronous economics run. Returns 202 Accepted immediately with a jobId.

Path Parameters

Parameter	Description
`projectId`	ObjectId of the project containing the scenario
`scenarioId`	ObjectId of the scenario to run

Request Body

The request body is optional. When omitted, the run uses the default settings and includes every well in the scenario (base assignments only).

Field	Type	Required	Description
`wellIds`	string[]	No	ObjectIds of wells to include. Each resolves to its base scenario well assignment. See Well Selection.
`econSettingId`	string \| null	No	ObjectId of a saved econ setting whose columns drive the run output. Omit for default columns.
`econReportSettingId`	string \| null	No	ObjectId of a saved econ report setting supplying report headers and aggregation flags. Omit for defaults.
`comboSettingId`	string \| null	No	ObjectId of a saved combo group for this project and scenario. Omit to run the default combo.
`runModels`	string	No	Which models to run. Only `"economics_only"` is supported. Defaults to `"economics_only"`.
`runMode`	string	No	Economics run mode. One of `"full"`, `"fast"`. Defaults to `"full"`.
`suggestedHeaders`	boolean	No	When `true`, includes suggested headers in the report output. Defaults to `false`.
`prodAnalyticsType`	string	No	Production analytics basis. One of `"calendar"`, `"daysOn"`. Defaults to `"calendar"`.
`timeZone`	string	No	IANA time zone used for monthly date bucketing. Defaults to `"UTC"`.

Unknown fields are rejected with 400 Bad Request.

Well Selection

Body	Wells included
`wellIds` omitted	Every well on the scenario, resolved to its base assignment only
`wellIds` provided	The listed wells, each resolved to its base scenario well assignment (`index` unset)

Only base assignments are included. Incremental scenario well assignments cannot be selected through this endpoint.

A wellId must belong to the scenario; an unknown well returns 400 Bad Request.
If a well has no resolvable base assignment, the request returns 404 Not Found.
A run that resolves to zero assignments returns 400 Bad Request.

Settings Resolution

Each setting slice is independent. Any subset of ids may be supplied; omitted ids fall back to the same defaults the run dialog uses when no saved setting is selected.

Slice	When id provided	When id omitted
Columns (`econSettingId`)	Loads the saved econ setting and reconciles its columns against the current column template.	Full default column set.
Report (`econReportSettingId`)	Loads the saved report setting; maps `headers`, `allWellsAgg`, and `rollUpEachLevel`.	Default report: `headers: ["econ_prms_reserves_category", "econ_prms_reserves_sub_category"]`, `allWellsAgg: true`, `rollUpEachLevel: true`.
Combos (`comboSettingId`)	Loads the combo group scoped to this project and scenario; requires at least one selected combo.	The scenario's default combo.

A combo group with no selected combos returns 400 Bad Request.

Response

202 Accepted

{
  "jobId": "64b3c2f1a9e34d0012abc123"
}

Use the jobId to poll for run status.

Polling Run Status

GET /v1/projects/:projectId/scenarios/:scenarioId/run/:jobId

Returns the current status of an economics run. The jobId is scoped to the scenarioId in the URL — you cannot poll a job that belongs to a different scenario.

Path Parameters

Parameter	Description
`projectId`	ObjectId of the project
`scenarioId`	ObjectId of the scenario
`jobId`	Job ID returned by the POST endpoint

Response

200 OK

Field	Type	Description
`jobId`	string	The job identifier
`status`	string	Current run status. See Status Values.
`progress`	number	Completion percentage, 0–100
`createdAt`	string \| null	ISO datetime when the job was created
`startedAt`	string \| null	ISO datetime when execution began
`completedAt`	string \| null	ISO datetime when the job completed (success or failure)
`result`	object \| null	Result payload when the run completed successfully. See Result Payload.
`error`	string \| null	Error message when the run failed

Status Values

`status`	Meaning
`"pending"`	The job is queued and waiting to start
`"running"`	The job is actively processing
`"successful"`	The run completed without errors
`"failed"`	The run encountered an error (see `error` field)

Result Payload

When status is "successful", result contains references you can use to read the run output:

Field	Type	Description
`runModels`	string	The models that ran (`"economics_only"`)
`project`	string	ObjectId of the project
`scenario`	string	ObjectId of the scenario
`econRunId`	string	ObjectId of the resulting econ run. Use it with the Econ Runs read endpoints.

Limitations and Constraints

Concurrent Run Limit

A maximum of 5 economics runs submitted by the API may be in progress simultaneously per tenant. Submitting a run when this limit is reached returns 429 Too Many Requests.

One Run Per Scenario

A scenario may only have one API-submitted run in progress at a time. Attempting to start a second run while one is already running returns 409 Conflict.

Wells Required

The run must resolve to at least one scenario well assignment. Running a scenario that resolves to no assignments returns 400 Bad Request.

Group Economics Not Supported

Econ groups are not supported via this endpoint. If any selected well belongs to an econ group, the request is rejected with 400 Bad Request. Remove wells that belong to econ groups and retry.

Incremental Assignments Not Supported

Well selection is by wellIds only and always resolves to base scenario well assignments. Incremental assignments cannot be targeted because the API does not expose scenario well assignment ids for discovery. Passing an unknown field such as scenarioWellAssignmentIds returns 400 Bad Request.

Carbon Runs Not Supported

Only runModels: "economics_only" is accepted. Carbon (carbon_only, carbon_and_economics) runs are not exposed because the API has no endpoint to read carbon (GHG) results. Requesting a carbon model returns 400 Bad Request.

Setting Ownership

Runs are owned by the tenant's API user. Results are readable only through the external API's Econ Runs endpoints, not the ComboCurve UI.

Error Reference

HTTP Status	Condition
`400`	Validation error in request body (see field-level error details in response)
`400`	A `wellId` does not belong to the scenario
`400`	The run resolved to no scenario well assignments
`400`	A selected well belongs to an econ group
`400`	The combo group has no selected combos
`400`	`runModels` is a carbon model (not exposed via the API)
`404`	`projectId` or `scenarioId` not found
`404`	No base assignment found for a supplied `wellId`
`404`	`econSettingId`, `econReportSettingId`, or `comboSettingId` not found
`404`	`jobId` not found, or does not belong to the specified `scenarioId`
`409`	The scenario already has a run in progress
`429`	Tenant concurrent economics run limit (5) reached

Examples

Run every well with default settings (no body)

POST /v1/projects/5e5981b9e23dae0012624d72/scenarios/64a1b2c3d4e5f6a7b8c9d0e1/run

Run selected wells with default settings

POST /v1/projects/5e5981b9e23dae0012624d72/scenarios/64a1b2c3d4e5f6a7b8c9d0e1/run
{
  "wellIds": ["5e6f8a3b1c9d420012ab34cd", "5e6f8a3b1c9d420012ab34ce"]
}

Run with saved settings

POST /v1/projects/5e5981b9e23dae0012624d72/scenarios/64a1b2c3d4e5f6a7b8c9d0e1/run
{
  "wellIds": ["5e6f8a3b1c9d420012ab34cd"],
  "econSettingId": "64b1c0faa9e34d0012a11111",
  "econReportSettingId": "64b1c0faa9e34d0012a22222",
  "comboSettingId": "64b1c0faa9e34d0012a33333"
}

Run with run options

POST /v1/projects/5e5981b9e23dae0012624d72/scenarios/64a1b2c3d4e5f6a7b8c9d0e1/run
{
  "wellIds": ["5e6f8a3b1c9d420012ab34cd"],
  "runMode": "fast",
  "prodAnalyticsType": "daysOn",
  "suggestedHeaders": true,
  "timeZone": "America/Denver"
}

Poll for status

GET /v1/projects/5e5981b9e23dae0012624d72/scenarios/64a1b2c3d4e5f6a7b8c9d0e1/run/64b3c2f1a9e34d0012abc123

Response (running):

{
  "jobId": "64b3c2f1a9e34d0012abc123",
  "status": "running",
  "progress": 42,
  "createdAt": "2024-07-16T14:00:00.000Z",
  "startedAt": "2024-07-16T14:00:05.000Z"
}

Response (successful):

{
  "jobId": "64b3c2f1a9e34d0012abc123",
  "status": "successful",
  "progress": 100,
  "createdAt": "2024-07-16T14:00:00.000Z",
  "startedAt": "2024-07-16T14:00:05.000Z",
  "completedAt": "2024-07-16T14:02:37.000Z",
  "result": {
    "runModels": "economics_only",
    "project": "5e5981b9e23dae0012624d72",
    "scenario": "64a1b2c3d4e5f6a7b8c9d0e1",
    "econRunId": "64b3d0119c2a4b0012def456"
  }
}

Triggering a Run​

Path Parameters​

Request Body​

Well Selection​

Settings Resolution​

Response​

Polling Run Status​

Path Parameters​

Response​

Status Values​

Result Payload​

Limitations and Constraints​

Concurrent Run Limit​

One Run Per Scenario​

Wells Required​

Group Economics Not Supported​

Incremental Assignments Not Supported​

Carbon Runs Not Supported​

Setting Ownership​

Error Reference​

Examples​

Run every well with default settings (no body)​

Run selected wells with default settings​

Run with saved settings​

Run with run options​

Poll for status​

Triggering a Run

Path Parameters

Request Body

Well Selection

Settings Resolution

Response

Polling Run Status

Path Parameters

Response

Status Values

Result Payload

Limitations and Constraints

Concurrent Run Limit

One Run Per Scenario

Wells Required

Group Economics Not Supported

Incremental Assignments Not Supported

Carbon Runs Not Supported

Setting Ownership

Error Reference

Examples

Run every well with default settings (no body)

Run selected wells with default settings

Run with saved settings

Run with run options

Poll for status