Econ Settings API Reference
The Econ Settings API lets you create, read, update, and delete saved economics run settings. An econ setting controls which output columns appear in an economics run, grouped by category, with independent toggles for the one-line summary, monthly, and cumulative views.
All endpoints are rooted at:
/v1/econ-settings
Key Concepts
- Econ settings are company-scoped, not user- or project-scoped:
GETreturns every setting in the tenant, andPUT/PATCH/DELETEcan target any setting regardless of who created it.createdByis stamped from the requesting user on create, but it is an audit field only, not an ownership boundary. - The wire format is sparse and grouped by category. The API only returns categories that have at least one selected column, and within a category only the columns that have at least one view selected. A column absent from the response is fully unselected.
- Each column can independently enable up to three views:
oneLiner(one-line summary),monthly, andaggregate(labeled "Cumulative" in the ComboCurve UI). Not every column supports every view; selecting an unsupported view is rejected. - Company custom streams (configured per tenant) appear as their own
"Company Custom Streams"category, positioned after the standard template categories. Project-scoped custom streams are not supported on this endpoint; econ settings have no project context. namemust be unique company-wide for API writes only.POSTrejects a duplicate name;PUT/PATCHmatch an existing setting byname(there is noidin the write body). If two settings share a name,PUT/PATCHagainst that name returns a collision error instead of guessing.
Endpoints
| Method | Path | Description | Limit |
|---|---|---|---|
HEAD | /v1/econ-settings | Return count headers only | – |
GET | /v1/econ-settings | List econ settings (paginated) | 200/page |
GET | /v1/econ-settings/:id | Get a single econ setting by ID | – |
POST | /v1/econ-settings | Create new econ settings | 100/call |
PUT | /v1/econ-settings | Upsert by name | 100/call |
PATCH | /v1/econ-settings | Partial update by name | 100/call |
DELETE | /v1/econ-settings | Delete by filter | 100/call |
DELETE | /v1/econ-settings/:id | Delete a single econ setting by ID | – |
Query Parameters (GET / HEAD)
| Parameter | Type | Description |
|---|---|---|
skip | number | Records to skip for pagination (default: 0) |
take | number | Records to return per page (default: 25, max: 200) |
sort | string | Sort field and direction (e.g. id, -id) |
cursor | string | Cursor token from a previous response for cursor pagination |
id | string | Filter by one or more IDs (comma-separated) |
name | string | Filter by name |
createdAt | string | Filter by creation date |
updatedAt | string | Filter by last-updated date |
Top-Level Fields
| Field | Type | Writable | Required | Description |
|---|---|---|---|---|
id | string | No | – | ID of this econ setting (read-only) |
name | string | Yes | Yes | Display name. Must contain at least one non-whitespace character. No max length. Unique company-wide for API writes. |
categories | array | Yes | No | Sparse, category-grouped column selections. See categories. |
createdBy | string | No | – | ID of the user who created this record (read-only) |
createdAt | string (ISO) | No | – | Creation timestamp (read-only) |
updatedAt | string (ISO) | No | – | Last-updated timestamp (read-only) |
There is no createdByName field: the API returns the raw createdBy user ID only.
categories
An array of category groups. Each group lists the columns in that category that have at least one view selected.
| Field | Type | Required | Description |
|---|---|---|---|
category | string | Yes | The category name (e.g. "Gross Volumes", "Net Volumes", "Company Custom Streams") |
columns | array | Yes | Non-empty array of column selections in this category. See below. |
Column object
| Field | Type | Required | Description |
|---|---|---|---|
key | string | Yes | The column's identifier (snake_case, e.g. gross_oil_sales_volume) |
selected | array of string | Yes | Non-empty, unique subset of "oneLiner", "monthly", "aggregate" |
{
"category": "Gross Volumes",
"columns": [
{ "key": "gross_oil_sales_volume", "selected": ["oneLiner"] },
{ "key": "gross_gas_sales_volume", "selected": ["oneLiner", "monthly"] }
]
}
oneLiner and monthly map directly to their ComboCurve UI labels. aggregate is the API value for what the UI displays as "Cumulative."
- A category with no selected columns is omitted entirely from
GETresponses. - A column absent from its category's
columnsarray is fully unselected (nooneLiner,monthly, oraggregate). categoriesmay be an empty array (nothing selected) or omitted entirely.- Not every column supports every view. A column's allowed views are fixed by its definition; requesting a view a column does not support returns a 400.
Company Custom Streams
A tenant can configure up to 20 company-level custom production streams. Each configured stream is identified by company_custom_stream_0 through company_custom_stream_19 and expands into 15 column keys, grouped under the "Company Custom Streams" category, positioned after the standard template categories. These keys can be selected the same way as any other column. Project-level custom streams are not supported; a project-scoped custom-stream key (project_custom_stream_*) is rejected as an unrecognized column.
The 15 keys generated for a stream company_custom_stream_<i> follow a fixed template:
| # | Key template | oneLiner | monthly | aggregate |
|---|---|---|---|---|
| 1 | gross_company_custom_stream_<i>_well_head_volume | ✓ | ✓ | – |
| 2 | gross_company_custom_stream_<i>_sales_volume | ✓ | ✓ | – |
| 3 | wi_company_custom_stream_<i> | ✓ | ✓ | – |
| 4 | first_reversion_wi_company_custom_stream_<i> | ✓ | – | – |
| 5 | nri_company_custom_stream_<i> | ✓ | ✓ | – |
| 6 | first_reversion_nri_company_custom_stream_<i> | ✓ | – | – |
| 7 | wi_company_custom_stream_<i>_sales_volume | ✓ | ✓ | – |
| 8 | net_company_custom_stream_<i>_sales_volume | ✓ | ✓ | – |
| 9 | company_custom_stream_<i>_shrinkage | ✓ | ✓ | – |
| 10 | input_company_custom_stream_<i>_price | ✓ | ✓ | – |
| 11 | company_custom_stream_<i>_differential | ✓ | ✓ | – |
| 12 | company_custom_stream_<i>_price | ✓ | ✓ | – |
| 13 | company_custom_stream_<i>_revenue | ✓ | ✓ | – |
| 14 | total_company_custom_stream_<i>_variable_expense | ✓ | ✓ | – |
| 15 | company_custom_stream_<i>_severance_tax | ✓ | ✓ | ✓ |
monthlyis disabled only on the twofirst_reversion_*keys (#4, #6).aggregateis enabled only oncompany_custom_stream_<i>_severance_tax(#15); every other custom-stream key supports onlyoneLinerandmonthly.- The column's
labelon read reflects the tenant's configured stream name (e.g."Gross <Stream Name> Well Head Volume"), but the wirekeyalways uses the literalcompany_custom_stream_<i>form shown above, regardless of what the tenant named the stream.
If a tenant has configured its first company custom stream, the following 15 keys become selectable under "Company Custom Streams": gross_company_custom_stream_0_well_head_volume, gross_company_custom_stream_0_sales_volume, wi_company_custom_stream_0, first_reversion_wi_company_custom_stream_0, nri_company_custom_stream_0, first_reversion_nri_company_custom_stream_0, wi_company_custom_stream_0_sales_volume, net_company_custom_stream_0_sales_volume, company_custom_stream_0_shrinkage, input_company_custom_stream_0_price, company_custom_stream_0_differential, company_custom_stream_0_price, company_custom_stream_0_revenue, total_company_custom_stream_0_variable_expense, and company_custom_stream_0_severance_tax. A second configured stream adds the same 15 keys with company_custom_stream_1 in place of company_custom_stream_0, and so on through company_custom_stream_19.
Only streams the tenant has actually configured produce selectable keys; an unconfigured slot does not appear at all (there is no way to select company_custom_stream_<i> for an unconfigured stream).
Columns without a category
A small number of columns (for example date) have no category and are not representable in this API: they are omitted on read and cannot be selected on write.
For the complete list of every static key accepted by this API, grouped by category with the exact views each one supports, see Available Economics Columns Reference at the end of this page.
Verb Semantics (PUT vs PATCH)
| Verb | categories absent from body | categories present in body |
|---|---|---|
POST/PUT | Treated as an empty selection (all columns unselected) | Full replace: the entire selection becomes exactly what was provided |
PATCH | Stored selection is left untouched | Full replace: the entire selection becomes exactly what was provided (there is no per-column merge) |
PUT and PATCH both match the target record by name (there is no id in the write body). PUT inserts if no match is found; PATCH returns a 404 result entry if no match is found.
Validation Rules Summary
| Rule | Detail |
|---|---|
name | Required, must contain at least one non-whitespace character, no max length |
| Unknown top-level fields | Rejected. If present, id is silently ignored; createdBy, createdAt, and updatedAt are not writable. |
categories[].columns | Non-empty array |
categories[].columns[].selected | Non-empty, unique, only "oneLiner" / "monthly" / "aggregate" |
Column key must exist | Recognized template key or resolved company-custom-stream key with a non-empty category |
Column's group category must match | The group's category must equal the column's actual category |
No duplicate category | Within one document |
No duplicate key | Across the whole document (all groups) |
| View must be allowed for the column | e.g. monthly is disallowed on some custom-stream columns; aggregate is only allowed on certain columns |
name uniqueness (create) | POST rejects a name that already exists in the tenant, and rejects duplicate names within the same batch |
name match count (upsert/patch) | If a name matches more than one existing record, PUT/PATCH return a collision error for that record instead of guessing |
Examples
Create an econ setting
POST /v1/econ-settings
[
{
"name": "My Econ Setting",
"categories": [
{
"category": "Gross Volumes",
"columns": [
{ "key": "gross_oil_sales_volume", "selected": ["oneLiner"] },
{ "key": "gross_gas_sales_volume", "selected": ["oneLiner", "monthly"] }
]
},
{
"category": "Net Volumes",
"columns": [{ "key": "net_oil_sales_volume", "selected": ["aggregate"] }]
}
]
}
]
Response (207 Multi-Status):
{
"results": [
{ "code": 201, "status": "Created", "message": "Successfully created econ setting" }
],
"successCount": 1,
"failedCount": 0
}
Get an econ setting
GET /v1/econ-settings/6650a1b2c3d4e5f6a7b8c9d0
Response:
{
"id": "6650a1b2c3d4e5f6a7b8c9d0",
"name": "My Econ Setting",
"categories": [
{
"category": "Gross Volumes",
"columns": [
{ "key": "gross_oil_sales_volume", "selected": ["oneLiner"] },
{ "key": "gross_gas_sales_volume", "selected": ["oneLiner", "monthly"] }
]
},
{
"category": "Net Volumes",
"columns": [{ "key": "net_oil_sales_volume", "selected": ["aggregate"] }]
}
],
"createdBy": "65fe1a2b3c4d5e6f7a8b9c0d",
"createdAt": "2026-05-11T15:00:00.000Z",
"updatedAt": "2026-05-11T15:00:00.000Z"
}
Clear all column selections (PUT)
PUT /v1/econ-settings
[
{ "name": "My Econ Setting" }
]
Because categories is omitted, this replaces the setting's selection with nothing selected. The record is matched by name; only the selection is reset.
Partial update (PATCH)
PATCH /v1/econ-settings
[
{
"name": "My Econ Setting",
"categories": [
{
"category": "Net Volumes",
"columns": [{ "key": "net_oil_sales_volume", "selected": ["oneLiner", "aggregate"] }]
}
]
}
]
Only the selection is replaced (whole-selection replace, no per-column merge). If categories were omitted here instead, the stored selection would be left untouched.
Error Responses
400 Bad Request
{
"results": [
{
"errors": [
{
"message": "Econ column `not_a_real_key` is not recognized",
"field": "categories",
"location": "[0].categories[0].columns[0]"
}
]
}
],
"successCount": 0,
"failedCount": 1
}
404 Not Found
{
"message": "Econ setting not found",
"code": 404
}
Known Limitations
- Project-level custom streams are not supported. Only company-level custom streams are resolved; project-scoped custom-stream columns are dropped on read and rejected on write.
- Name uniqueness is enforced only on API writes. Settings created through the ComboCurve UI can still share a name; a
PUT/PATCHagainst a duplicated name returns a collision error rather than guessing which record to update. GETreturns every company-shared setting in the tenant, including ones created in the UI. This is the intended scope, not a filtering gap.- Columns without a category (like
date) are invisible to this API. A setting that has one of these columns selected outside the API loses that selection if it is later replaced viaPUT/PATCH. PATCHis partial only at the top level. Omittingcategoriesleaves the whole selection untouched, but providingcategoriesreplaces the entire selection (there is no per-column merge within aPATCH).
Available Economics Columns Reference
Every valid static key for the economics columns template, grouped by category exactly as the API groups them on read, with checkmarks (✓) showing which views (oneLiner / monthly / aggregate) are supported for that column. Large categories are further split (for example by hydrocarbon component, or Net vs Gross) for readability only; the wire format itself only groups by top-level category.
This list is the complete static-template key universe (824 keys across 17 categories). It does not include the "Company Custom Streams" category: those keys are generated per tenant from each company's configured custom streams and cannot be enumerated statically (see Company Custom Streams above).
Gross Volumes (11 columns)
| Key | Label | Unit | oneLiner | monthly | aggregate |
|---|---|---|---|---|---|
gross_oil_well_head_volume | Gross Oil Well Head Volume | – | ✓ | ✓ | ✓ |
gross_gas_well_head_volume | Gross Gas Well Head Volume | – | ✓ | ✓ | ✓ |
gross_boe_well_head_volume | Gross BOE Well Head Volume | – | ✓ | ✓ | ✓ |
gross_mcfe_well_head_volume | Gross MCFE Well Head Volume | – | ✓ | ✓ | ✓ |
gross_water_well_head_volume | Gross Water Well Head Volume | – | ✓ | ✓ | ✓ |
gross_oil_sales_volume | Gross Oil Sales Volume | – | ✓ | ✓ | ✓ |
gross_gas_sales_volume | Gross Gas Sales Volume | – | ✓ | ✓ | ✓ |
gross_ngl_sales_volume | Gross NGL Sales Volume | – | ✓ | ✓ | ✓ |
gross_drip_condensate_sales_volume | Gross Drip Condensate Sales Volume | – | ✓ | ✓ | ✓ |
gross_boe_sales_volume | Gross BOE Sales Volume | – |