Econ Report Settings API Reference

The Econ Report Settings API lets you create, read, update, and delete saved economics report aggregation settings. An econ report setting is a small, flat configuration: a name, an ordered list of criteria to aggregate economics reports by, and two aggregation-total toggles.

All endpoints are rooted at:

/v1/econ-report-settings

Key Concepts

Econ report settings are company-scoped, not user- or project-scoped: GET returns every setting in the tenant, and PUT/PATCH/DELETE can target any setting regardless of who created it. createdBy is stamped from the requesting user on create, but it is an audit field only.
headers is an ordered, order-significant list of aggregation criteria, at most 5. Order reflects aggregation priority, matching the priority list in the ComboCurve UI.
Each entry in headers must be one of: a valid well-header key (as listed in Available Header Keys Reference; most are snake_case, but some legacy keys are camelCase like chosenKeyID), one of three special criteria (econ_prms_reserves_category, econ_prms_reserves_sub_category, econ_group), or a project-custom-header key slot (e.g. _project_custom_header, _project_custom_header_1).
allWellsAgg and rollUpEachLevel are optional booleans. If omitted on create, they are not stored; reads always apply defaults: allWellsAgg defaults to true, rollUpEachLevel defaults to false.
name must be unique company-wide for API writes only. POST rejects a duplicate name; PUT/PATCH match an existing setting by name (there is no id in the write body).
This is a flat document: a name, an ordered headers list, and two boolean toggles.

Endpoints

Method	Path	Description	Limit
`HEAD`	`/v1/econ-report-settings`	Return count headers only	–
`GET`	`/v1/econ-report-settings`	List econ report settings (paginated)	200/page
`GET`	`/v1/econ-report-settings/:id`	Get a single econ report setting by ID	–
`POST`	`/v1/econ-report-settings`	Create new econ report settings	100/call
`PUT`	`/v1/econ-report-settings`	Upsert by `name`	100/call
`PATCH`	`/v1/econ-report-settings`	Partial update by `name`	100/call
`DELETE`	`/v1/econ-report-settings/:id`	Delete a single econ report 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)
`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 report 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.
`headers`	array of string	Yes	No	Ordered list of aggregation criteria, at most 5. See `headers`.
`allWellsAgg`	boolean	Yes	No	Include the aggregation grand total. Defaults to `true` when not set.
`rollUpEachLevel`	boolean	Yes	No	Include the aggregation subtotal at each level. Defaults to `false` when not set.
`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.

`headers`

An ordered array of strings identifying the criteria to aggregate the economics report by. Order matters: it reflects aggregation priority, the same as the priority list in the ComboCurve UI.

Each entry must be one of:

Kind	Examples	Notes
Well-header key	`well_name`, `county`, `custom_string_0`	snake_case well-header key; camelCase well field names used elsewhere in the external API are rejected (`wellName` is invalid)
Special criterion	`econ_prms_reserves_category`, `econ_prms_reserves_sub_category`, `econ_group`	Aggregation criteria that are not well-header keys
Project-custom-header slot	`_project_custom_header`, `_project_custom_header_1`, …	Accepted by name pattern only; the API does not verify the slot is configured on any specific project

{
  "headers": ["well_name", "county", "econ_prms_reserves_category"]
}

At most 5 headers

headers accepts at most 5 entries, matching the ComboCurve UI's limit.

Not the same as the UI picker

The API validates that each key is a recognized well-header, special criterion, or custom-header slot. It does not mirror every ComboCurve UI picker restriction, and it does not check whether a project-custom-header slot is actually configured.

Full header key list

For the complete list of every well-header key accepted by this API, grouped by data type, see Available Header Keys Reference at the end of this page.

Verb Semantics (PUT vs PATCH)

Verb	Field absent from body	Field present in body
`POST`/`PUT`	`headers` treated as an empty list; `allWellsAgg`/`rollUpEachLevel` not stored (read defaults apply)	Value is set exactly as provided
`PATCH`	Stored value is left untouched	Value is set exactly as provided (each field updates independently)

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 and never inserts.

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.
`headers`	Optional array of non-empty strings, at most 5 items
Each `headers[i]`	Must be a valid well-header key, one of the three special criteria, or a project-custom-header key slot
`allWellsAgg` / `rollUpEachLevel`	Optional booleans
`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
`PATCH` on unmatched `name`	Returns a 404 result entry; never inserts

Examples

Create an econ report setting

POST /v1/econ-report-settings
[
  {
    "name": "My Report Setting",
    "headers": ["well_name", "county", "econ_prms_reserves_category"],
    "allWellsAgg": true,
    "rollUpEachLevel": false
  }
]

Response (207 Multi-Status):

{
  "results": [
    { "code": 201, "status": "Created", "message": "Successfully created econ report setting" }
  ],
  "successCount": 1,
  "failedCount": 0
}

Get an econ report setting

GET /v1/econ-report-settings/6650a1b2c3d4e5f6a7b8c9d0

Response:

{
  "id": "6650a1b2c3d4e5f6a7b8c9d0",
  "name": "My Report Setting",
  "headers": ["well_name", "county", "econ_prms_reserves_category"],
  "allWellsAgg": true,
  "rollUpEachLevel": false,
  "createdBy": "65fe1a2b3c4d5e6f7a8b9c0d",
  "createdAt": "2026-05-11T15:00:00.000Z",
  "updatedAt": "2026-05-11T15:00:00.000Z"
}

Partial update (PATCH)

PATCH /v1/econ-report-settings
[
  { "name": "My Report Setting", "rollUpEachLevel": true }
]

Only rollUpEachLevel changes; headers and allWellsAgg are left untouched.

Replace headers entirely (PUT)

PUT /v1/econ-report-settings
[
  { "name": "My Report Setting", "headers": ["econ_group"] }
]

Because allWellsAgg/rollUpEachLevel are omitted, they are not stored by this write; reads fall back to the defaults (true / false) unless a previous write had set them.

Error Responses

400 Bad Request

{
  "results": [
    {
      "errors": [
        {
          "message": "'not_a_real_header' is not a valid report header key",
          "field": "headers",
          "location": "[0].headers[0]"
        }
      ]
    }
  ],
  "successCount": 0,
  "failedCount": 1
}

404 Not Found

{
  "message": "Econ report setting not found",
  "code": 404
}

Known Limitations

Header-key validation is membership-only, not full UI parity. The API checks that each headers[] entry is a recognized well-header key, special criterion, or custom-header slot; it does not mirror every ComboCurve UI picker restriction, or verify that a custom-header slot is actually configured on any project.
Name uniqueness is enforced only on API writes. Settings created through the ComboCurve UI can still share a name; a PUT/PATCH against a duplicated name returns a collision error rather than guessing which record to update.
GET returns every company-shared setting in the tenant, including ones created in the UI. This is the intended scope, not a filtering gap.
allWellsAgg / rollUpEachLevel defaults are applied only on read. A setting created without them is returned with the defaults applied, but those defaults are not written back unless you set the fields explicitly.
PUT and PATCH match by name; DELETE is by ID only. There is no bulk delete.

Available Header Keys Reference

Every key accepted by headers[] validation, across all three accepted kinds (well-header keys, special criteria, and project-custom-header slots). This is the complete accepted key universe: 425 keys (372 well-header keys + 3 special criteria + 50 project-custom-header slots).

Membership only, not UI parity

A key appearing here means it will pass validation, not that it is a meaningful or commonly used report criterion. Some accepted well-header keys are rarely useful for aggregation; see Known Limitations #1.

Special criteria

Aggregation criteria accepted by name that are not well-header fields:

Key	Meaning
`econ_prms_reserves_category`	PRMS reserves category assigned to the well's econ run
`econ_prms_reserves_sub_category`	PRMS reserves sub-category assigned to the well's econ run
`econ_group`	The well's econ group (scenario/combo grouping)

Project-custom-header slots

Every _project_custom_header* slot name is accepted by name pattern only; the API does not verify the slot is configured on any specific project. There are 50 slots, following one naming pattern:

Pattern	Range	Count
`_project_custom_header`	the base slot, no suffix	1
`_project_custom_header_<n>`	`<n>` = `1` through `49`	49

Well-header keys

Every well-header key accepted by headers[] validation, grouped by data type (372 keys).

String headers (string, 78 keys)

Key	Label
`abstract`	Abstract
`allocation_type`	Allocation Type
`api10`	API 10
`api12`	API 12
`api14`	API 14
`aries_id`	ARIES ID
`basin`	Basin
`block`	Block
`chosenKeyID`	Chosen ID Key
`combo_name`	Econ Scenario & Combo
`completion_design`	Completion Design
`country`	Country
`county`	County/Parish
`current_operator`	Current Operator
`current_operator_alias`	Current Operator Alias
`current_operator_code`	Current Operator Code
`current_operator_ticker`	Current Operator Ticker
`dataPool`	Data Pool
`dataSource`	Data Source
`dataSourceCustomName`	Custom Data Source
`district`	District
`drillinginfo_id`	DI ID
`elevation_type`	Elevation Type
`field`	Field
`first_frac_vendor`	Frac Vendor (1st Job)
`first_treatment_type`	Treatment Type (1st Job)
`flow_path`	Flow Path
`fluid_type`	Fluid Type
`gas_gatherer`	Gas Gatherer
`geohash`	(no display label)
`hole_direction`	Hole Direction
`ihs_id`	IHS ID
`inptID`	INPT ID
`landing_zone`	Landing Zone
`lease_name`	Lease Name
`lease_number`	Lease Number
`monthly_or_daily`	(no display label)
`mostRecentImportDesc`	Import Name
`mostRecentImportType`	Import Type
`ngl_gatherer`	(no display label)
`oil_gatherer`	Oil Gatherer
`pad_name`	Pad Name
`parent_child_any_zone`	Parent Child Any Zone
`parent_child_same_zone`	Parent Child Same Zone
`phdwin_id`	PhdWin ID
`play`	Play
`previous_operator`	Previous Operator
`previous_operator_alias`	Previous Operator Alias
`previous_operator_code`	Previous Operator Code
`previous_operator_ticker`	Previous Operator Ticker
`primary_product`	Primary Product
`prms_reserves_category`	PRMS Reserves Category
`prms_reserves_sub_category`	PRMS Reserves Sub Category
`prms_resources_class`	PRMS Reserves Class
`production_method`	Production Method
`proppant_mesh_size`	Prop Mesh Size
`proppant_type`	Prop Type
`range`	Range
`recovery_method`	Recovery Method
`refrac_frac_vendor`	Frac Vendor (Refrac)
`refrac_treatment_type`	Treatment Type (Refrac)
`rig`	Rig Name
`rseg_id`	RSEG ID
`section`	Section
`spgci_id`	SPGCI ID
`state`	State
`status`	Status
`subplay`	Subplay
`survey`	Survey
`target_formation`	Target Formation
`tgs_id`	TGS ID
`toe_in_landing_zone`	Toe In Landing Zone
`toe_up`	Toe Up
`township`	Township
`type_curve_area`	Type Curve Area
`well_name`	Well Name
`well_number`	Well Number
`well_type`	Well Type

Numeric headers (number, 180 keys)

Key	Label
`acre_spacing`	Acre Same Zone Spacing
`azimuth`	Azimuth
`before_income_tax_cash_flow`	Before Income Tax Cash Flow
`bg`	(no display label)
`bo`	(no display label)
`bubble_point_press`	(no display label)
`casing_id`	Casing ID
`choke_size`	Choke Size
`cum_boe`	Cum BOE
`cum_boe_per_perforated_interval`	Cum BOE/Perf LL
`cum_gas`	Cum Gas
`cum_gas_per_perforated_interval`	Cum Gas/Perf LL
`cum_gor`	Cum GOR
`cum_mmcfge`	Cum MMCFGE
`cum_mmcfge_per_perforated_interval`	Cum MMCFGE/Perf LL
`cum_oil`	Cum Oil
`cum_oil_per_perforated_interval`	Cum Oil/Perf LL
`cum_water`	Cum Water
`cum_water_per_perforated_interval`	Cum Water/Perf LL
`dew_point_press`	(no display label)
`distance_from_base_of_zone`	Distance From Base Of Zone
`distance_from_top_of_zone`	Distance From Top Of Zone
`drainage_area`	Drainage Area
`elevation`	Elevation
`first_12_boe`	First 12 BOE
`first_12_boe_per_perforated_interval`	First 12 BOE/Perf LL
`first_12_gas`	First 12 Gas
`first_12_gas_per_perforated_interval`	First 12 Gas/Perf LL
`first_12_gor`	First 12 GOR
`first_12_mmcfge`	First 12 MMCFGE
`first_12_mmcfge_per_perforated_interval`	First 12 MMCFGE/Perf LL
`first_12_oil`	First 12 Oil
`first_12_oil_per_perforated_interval`	First 12 Oil/Perf LL
`first_12_water`	First 12 Water
`first_12_water_per_perforated_interval`	First 12 Water/Perf LL
`first_6_boe`	First 6 BOE
`first_6_boe_per_perforated_interval`	First 6 BOE/Perf LL
`first_6_gas`	First 6 Gas
`first_6_gas_per_perforated_interval`	First 6 Gas/Perf LL
`first_6_gor`	First 6 GOR
`first_6_mmcfge`	First 6 MMCFGE
`first_6_mmcfge_per_perforated_interval`	First 6 MMCFGE/Perf LL
`first_6_oil`	First 6 Oil
`first_6_oil_per_perforated_interval`	First 6 Oil/Perf LL
`first_6_water`	First 6 Water
`first_6_water_per_perforated_interval`	First 6 Water/Perf LL
`first_additive_volume`	Additive Vol (1st Job)
`first_cluster_count`	Cluster Count (1st Job)
`first_discount_cash_flow`	First Discount Cash Flow
`first_fluid_per_perforated_interval`	Total Fluid/Perf LL (1st Job)
`first_fluid_volume`	Total Fluid (1st Job)
`first_max_injection_pressure`	Max Injection Pressure (1st Job)
`first_max_injection_rate`	Max Injection Rate (1st Job)
`first_prop_weight`	Total Prop (1st Job)
`first_proppant_per_fluid`	Total Prop/Fluid (1st Job)
`first_proppant_per_perforated_interval`	Total Prop/Perf LL (1st Job)
`first_stage_count`	Stage Count (1st Job)
`first_test_flow_tbg_press`	First Test Flow TBG Press
`first_test_gas_vol`	First Test Gas Vol
`first_test_gor`	First Test Gor
`first_test_oil_vol`	First Test Oil Vol
`first_test_water_vol`	First Test Water Vol
`footage_in_landing_zone`	Footage In Landing Zone
`formation_thickness_mean`	Formation Thickness Mean
`fracture_conductivity`	(no display label)
`gas_breakeven`	Gas Break Even
`gas_c1`	(no display label)
`gas_c2`	(no display label)
`gas_c3`	(no display label)
`gas_co2`	(no display label)
`gas_h2`	(no display label)
`gas_h2o`	(no display label)
`gas_h2s`	(no display label)
`gas_he`	(no display label)
`gas_ic4`	(no display label)
`gas_ic5`	(no display label)
`gas_n2`	(no display label)
`gas_nc10`	(no display label)
`gas_nc4`	(no display label)
`gas_nc5`	(no display label)
`gas_nc6`	(no display label)
`gas_nc7`	(no display label)
`gas_nc8`	(no display label)
`gas_nc9`	(no display label)
`gas_o2`	(no display label)
`gas_shrunk_eur`	Gas Shrunk EUR
`gas_shrunk_eur_over_pll`	Gas Shrunk EUR/PLL
`gas_specific_gravity`	Gas Specific Gravity
`gross_perforated_interval`	Gross Perforated Interval
`ground_elevation`	Ground Elevation
`heelLatitude`	Heel Latitude
`heelLongitude`	Heel Longitude
`horizontal_spacing`	Horizontal Spacing
`hz_well_spacing_any_zone`	Hz Well Spacing Any Zone
`hz_well_spacing_same_zone`	Hz Well Spacing Same Zone
`initial_respress`	Initial Respress
`initial_restemp`	Initial Restemp
`irr`	IRR
`landing_zone_base`	Landing Zone Base
`landing_zone_top`	Landing Zone Top
`last_12_boe`	Last 12 BOE
`last_12_boe_per_perforated_interval`	Last 12 BOE/Perf LL
`last_12_gas`	Last 12 Gas
`last_12_gas_per_perforated_interval`	Last 12 Gas/Perf LL
`last_12_gor`	Last 12 GOR
`last_12_mmcfge`	Last 12 MMCFGE
`last_12_mmcfge_per_perforated_interval`	Last 12 MMCFGE/Perf LL
`last_12_oil`	Last 12 Oil
`last_12_oil_per_perforated_interval`	Last 12 Oil/Perf LL
`last_12_water`	Last 12 Water
`last_12_water_per_perforated_interval`	Last 12 Water/Perf LL
`last_month_boe`	Last Month BOE
`last_month_boe_per_perforated_interval`	Last Month BOE/Perf LL
`last_month_gas`	Last Month Gas
`last_month_gas_per_perforated_interval`	Last Month Gas/Perf LL
`last_month_gor`	Last Month GOR
`last_month_mmcfge`	Last Month MMCFGE
`last_month_mmcfge_per_perforated_interval`	Last Month MMCFGE/Perf LL
`last_month_oil`	Last Month Oil
`last_month_oil_per_perforated_interval`	Last Month Oil/Perf LL
`last_month_water`	Last Month Water
`last_month_water_per_perforated_interval`	Last Month Water/Perf LL
`lateral_length`	Lateral Length
`lower_perforation`	Lower Perforation
`matrix_permeability`	Matrix Permeability
`measured_depth`	Measured Depth
`midpointLatitude`	Midpoint Latitude
`midpointLongitude`	Midpoint Longitude
`month_produced`	Months Produced
`ngl_shrunk_eur`	NGL EUR
`ngl_shrunk_eur_over_pll`	NGL EUR/PLL
`nri_oil`	NRI Oil
`num_treatment_records`	Num Treatment Records
`oil_api_gravity`	Oil API Gravity
`oil_breakeven`	Oil Break Even
`oil_shrunk_eur`	Oil Shrunk EUR
`oil_shrunk_eur_over_pll`	Oil Shrunk EUR/PLL
`oil_specific_gravity`	Oil Specific Gravity
`payout_duration`	Payout Duration
`percent_in_zone`	Percent In Zone
`perf_lateral_length`	Perf Lateral Length
`porosity`	Porosity
`refrac_additive_volume`	Additive Vol (Refrac)
`refrac_cluster_count`	Cluster Count (Refrac)
`refrac_fluid_per_perforated_interval`	Total Fluid/Perf LL (Refrac)
`refrac_fluid_volume`	Total Fluid (Refrac)
`refrac_max_injection_pressure`	Max Injection Pressure (Refrac)
`refrac_max_injection_rate`	Max Injection Rate (Refrac)
`refrac_prop_weight`	Total Prop (Refrac)
`refrac_proppant_per_fluid`	Total Prop/Fluid (Refrac)
`refrac_proppant_per_perforated_interval`	Total Prop/Perf LL (Refrac)
`refrac_stage_count`	Stage Count (Refrac)
`rs`	(no display label)
`sg`	Gas Saturation
`so`	Oil Saturation
`stage_spacing`	Stage Spacing
`surfaceLatitude`	Surface Latitude
`surfaceLongitude`	Surface Longitude
`sw`	Water Saturation
`thickness`	Thickness
`toeLatitude`	Toe Latitude
`toeLongitude`	Toe Longitude
`total_additive_volume`	Additive Vol (All Jobs)
`total_cluster_count`	Total Cluster (All Jobs)
`total_fluid_per_perforated_interval`	Total Fluid/Perf LL (All Jobs)
`total_fluid_volume`	Total Fluid (All Jobs)
`total_prop_weight`	Total Prop (All Jobs)
`total_proppant_per_fluid`	Total Prop/Fluid (All Jobs)
`total_proppant_per_perforated_interval`	Total Prop/Perf LL (All Jobs)
`total_stage_count`	Total Stages (All Jobs)
`true_vertical_depth`	True Vertical Depth
`tubing_depth`	Tubing Depth
`tubing_id`	Tubing ID
`undiscounted_roi`	Undisc ROI
`upper_perforation`	Upper Perforation
`vertical_spacing`	Vertical Spacing
`vt_well_spacing_any_zone`	Vt Well Spacing Any Zone
`vt_well_spacing_same_zone`	Vt Well Spacing Same Zone
`wi_oil`	WI Oil
`zi`	(no display label)

Date headers (date, 18 keys)

Key	Label
`completion_end_date`	Completion End Date
`completion_start_date`	Completion Start Date
`date_rig_release`	Date Rig Release
`drill_end_date`	Drill End Date
`drill_start_date`	Drill Start Date
`econ_first_production_date`	Econ First Prod Date
`econ_run_date`	Econ Run Date
`first_prod_date`	First Prod Date
`first_prod_date_daily_calc`	First Prod Date Daily
`first_prod_date_monthly_calc`	First Prod Date Monthly
`gas_analysis_date`	(no display label)
`last_prod_date_daily`	Last Prod Date Daily
`last_prod_date_monthly`	Last Prod Date Monthly
`mostRecentImportDate`	Import Date
`permit_date`	Permit Date
`refrac_date`	Refrac Date
`spud_date`	Spud Date
`til`	TIL

Boolean headers (boolean, 5 keys)

Key	Label
`copied`	Copied Well
`generic`	Created Well
`has_daily`	Has Daily Data
`has_directional_survey`	Has Directional Survey
`has_monthly`	Has Monthly Data

Company custom headers (slot keys are always valid, regardless of whether a tenant has renamed them)

Key range	Count	Type
`custom_string_0` – `custom_string_34`	35	string
`custom_number_0` – `custom_number_19`	20	number
`custom_date_0` – `custom_date_19`	20	date
`custom_bool_0` – `custom_bool_4`	5	boolean

Other accepted keys (rarely useful as report criteria) (mixed, 11 keys)

Key	Label
`chosenID`	Chosen ID
`closest_well_any_zone`	Closest Well ID Any Zone
`closest_well_same_zone`	Closest Well ID Same Zone
`copiedFrom`	(no display label)
`heelLocation`	(no display label)
`location`	(no display label)
`midpointLocation`	(no display label)
`mostRecentImport`	(no display label)
`project`	(no display label)
`toeLocation`	(no display label)
`wells_collection_items`	(no display label)

Key Concepts​

Endpoints​

Query Parameters (GET / HEAD)​

Top-Level Fields​

headers​

Verb Semantics (PUT vs PATCH)​

Validation Rules Summary​

Examples​

Create an econ report setting​

Get an econ report setting​

Partial update (PATCH)​

Replace headers entirely (PUT)​

Error Responses​

400 Bad Request​

404 Not Found​

Known Limitations​

Available Header Keys Reference​

Special criteria​

Project-custom-header slots​

Well-header keys​