Skip to content
Developers
Get an API token

Compare plans, scenarios or a forecast source

Compares two sides, each a done plan's wells under one design (design, 0 by default) or one scenario's (scenario), in one model set.

Compare plans, scenarios or a forecast source

POST/comparisons

Compares two sides, each a done plan's wells under one design (design, 0 by default) or one scenario's (scenario), in one model set. Both sides may be the same plan. Nothing is stored and no model worker runs.

Send a Novi API token as a bearer token on every request. Authentication
Sides

A plan made with scenarios compares one scenario at a time, since its totals don't add alternatives. Each side echoes what it is and what made it (ComparisonSideEcho); a plan whose stored record can't be read echoes this server's release and the model set the request reached.

Numbers

Every number is one GET /plans/{id} or its stats already serve: a scenario side's EUR equals that plan's totals for its scenario and design, and its cumulative at ip_day the summed forecast curve's value there (BOE: the forecast.boe total GET /plans/{id}?boe=true serves, over the wells with both oil and gas forecasts); its distribution equals GET /plans/{id}/stats' group_by=scenario row for it. Quantiles are of each side's wells' values (q10 the 10th-percentile well), not P-level bands. totals has water's EUR too when both sides fit it, and each row its unit and each side's well count.

  • delta is b − a, rounded to 0.1.
  • delta_pct is (b − a) / a × 100, rounded to 0.01; null when a is 0 or either value is null.
  • Swapping the sides negates every delta exactly, and a side compared with itself gives 0 wherever both sides have a value.
Metric and groups

metric, ip_day and group_by work as ComparisonRequest describes them, and groups as Comparison describes it. An eur_ metric on a side made without eur: true is a 400 naming the side. In a group row, a side without the key is null, and so is the row's delta. Grouping by pad when neither side's plan names pads is a 400 on group_by naming both plans, with details.side a: send wells[].pad.

Curves

include: ["curves"] adds each side's summed curve for the metric's stream by ip_day (BOE over the wells with both oil and gas forecasts), cumulative and each step's average daily rate. With bands too, each side's summed P10 and P90 cumulative where its plan was made with bands (Novi's P10 is the low curve; a sum of per-well bands assumes fully correlated outcomes, so it is not a confidence interval for the plan).

Warnings

warnings give a code and a sentence when the sides differ in model set, in models (the same set with a changed manifest or pins), in release or in EUR settings; when one side has no EUR (the EUR rows are left out); when a side's wells lack forecasts; and when a side has no bands that bands asked for.

Pairing wells

pair pairs the sides' wells and adds pairs: the method used, how many paired, and each side's unpaired wells. ComparisonPairing lists the methods.

  • auto, the default, pairs by name when every well on both sides has a real name (a default label such as Plan well 3 never counts) and no name repeats on a side, else by location.
  • location pairs each well once, the same formation first, so stacked benches pair within their bench. name pairs a repeated name's wells by location within it, with a duplicate_names warning.
  • Location pairing examines at most 64 nearby wells per well. Wells packed closer, as many on one spot, are a 400 naming pair: pair them by index or map.
Paired wells

include: ["wells"] (pairing by auto when pair is absent) adds wells: a page of rows, one per pair, with each side's value, delta and delta_pct, in wells.sort order; and a summary over every pair: the count, each pair's delta_pct (sorted values under 20 pairs, else a histogram), its q10, q50 and q90 (quantiles of pairs, not P-levels) and left_out. When side a's plan has band_eur and the metric is an EUR, each row's band_position places side b's value in side a's P10 to P90 EUR, counted in summary.band; otherwise a no_band_position warning.

Changed inputs

include: ["inputs"] adds inputs.changed: each input that differs on any pair (ComparisonInputChange lists them), how many pairs, and the typical change: b − a, the median among pairs with both values, or for formation the most common change.

Horizon

horizon: { "years": n } (1 to 50, EUR on both sides) adds cumulative oil, gas and BOE rows, with horizon_years, at ip_day the last 30-day step within n × 365 days. Each well counts its forecast, then its EUR curve as eur_curve=month gives it, then past its EUR day its EUR.

Calendar curves

align: "calendar" (with include: ["curves"], and a well with a TIL date on each side) adds curves.calendar: each side's summed curve by month start, as GET /plans/{id} totals.by_date sums a plan's, with each step's average daily rate.

A forecast source

Either side may be { "source": "<id>" } (POST /forecast-sources) when the other is a plan; two sources are a 400.

  • The source is read as you: a private one is a 404 naming the side to another user, a share link's viewer or another tenant. Without a state store a source side is a 409.
  • reserves_category is required on a source holding more than one (a 400 lists them with their curve counts); Novi's P-levels never stand in for one.
  • Each well under it runs through its decline profile (GET /conventions?include=decline_profiles), each stream from day 0 at its curve's start date (a constants ratio at its parent stream's).
  • From those runs come each EUR, to its curve's limit or end date, the cumulatives at ip_day and horizon, the spread over its wells, and its summed curve on the plan side's ip_days.
  • A source has no bands. Its numbers are in bbl, mcf and BOE whatever the file's units.
  • A source whose wells would take more than 120,000,000 steps of decline-curve work (a day a curve steps through, or a day measured) is a 400 on the side naming its wells and curves: save the wells you need as a smaller source.
  • align: "calendar" runs to the first month start on or after its last stream start plus 1,080 days, each well held at its last cumulative. It needs a start date on every well (a Novi arps.csv has none: a 400) and at most 1,200 month starts (a 400 names the earliest and latest start).
Pairing a source

On a source side:

  • auto uses the pairs saved on the source when it links to this plan, else name when that pairs a well, else uwi. saved uses only the saved pairs (a 400 when there are none).
  • name matches a source Well ID to a plan well's real name, trimmed and ignoring case; uwi does the same without dashes, spaces and dots. map takes Well IDs on the source side.
  • location, index, tolerance_ft, group_by, normalize_lateral_ft and include: ["inputs"] are 400s: a source has no locations, order, designs, formations, scenarios, pads, laterals or inputs.
  • Its unpaired wells and rows name Well IDs (a_well_id, b_well_id); band_position applies with the plan as side a.
Source warnings

gas_basis_differs (a sales-gas source), conventions_differ (any profile but novi's), horizons_differ (the EURs end at different days) and source_unpaired.

Value

include: ["value"] prices each side as POST /economics prices one scenario, under one deck and conventions (deck_id, deck and conventions, each a 400 without it), and adds value with the difference.

  • A plan side prices its wells under its design as a plan reference does: its economics and breakeven equal POST /economics with scenarios: [{"plan": {id, design, scenario}}] and include: ["breakeven"].
  • A plan side needs a plan made with eur: true (a 400 naming the side); more than 50 wells are priced as one pad.
  • A forecast source side prices only its wells that pair with a plan well (by auto when pair is absent): the plan well's lateral and completions under the plan side's design, with the source well's own cumulatives on the plan side's ip_days and its EURs, to the later EUR day (eur_days).
  • An unpaired source well is listed in unpriced with a reason. When both sides price different counts, a value_wells_differ warning names them.
  • A side with any priced well it can't give a cash flow (a source well without water, say) has economics null and a reason naming the first.
  • delta is b − a for capex, npv, irr_pct, payback_months and each breakeven price, to 0.01; null where either side has none.
Value limits

Both sides together may hold at most 5,000 wells (a source side's under its reserves category) and 5,000,000 well-months: each well's 30-day months to its EUR day (a source well's eur_days may pass POST /economics' 60 years), or to its curve's last ip_day if later. Past either is a 400 on include naming each side's count, before anything is priced: price larger sides with POST /economics in scenarios of up to 50 wells, or compare fewer wells.

Errors

A request whose sides are plans of two model sets is a 400 naming each side's set: compare plans of one set. A missing plan, another tenant's or one on a model set you can't use is a 404, as GET /plans/{id} answers; a running or failed plan is a 409.

Parameters

Query parameters

  • model_setstringOptional

    pattern ^[a-z0-9][a-z0-9-]{0,62}$

    The model set to answer from, an id from GET /model-sets. Absent: the set GET /model-sets names as default, the base dataset unless the server answers from a published set.

    • model_set=default reaches the base dataset; once the server retires it, a 400 naming the set answering instead.
    • An unknown id, or a set scoped to other tenants, is a 400 listing the ids the caller may use in details.allowed (published sets only once default is retired); a set that can't load, a 503 with the reason.
    • Plans and exports stay in their set: a call naming them (by path, plan, ids, source.plan, a scenario's plan.id, or a comparison's a.plan and b.plan, also under source.comparison) reaches it without model_set.
    • An explicit model_set wins; naming resources of two sets in one request is a 400.

Request bodyRequired

application/json

The two sides and what to measure.

  • aobjectRequired

    Side a, the base: delta is b − a and delta_pct is relative to it. A plan side, or a forecast source side when side b is a plan.

    ShowHide 2 variants

    Any of

    • ComparisonSide object

      One side: a plan's wells under one design, or one scenario's.

      • planstringRequired

        Format uuid

        A done plan's id, as POST /plans returns it.

      • scenariostringOptional

        1 to 60 characters

        On a plan made with scenarios, the scenario to compare, exactly as its scenarios list it; required there, and a 400 on a plan without scenarios. A name it doesn't have is a 400 whose details.scenarios lists them.

      • designintegerOptional

        Default 0≥ 0

        The design, as its index in the plan's designs; 0 by default. One past the last is a 400.

    • ComparisonSourceSide object

      A forecast source as one side; the other side is a plan. Any other field is a 400 listing these.

      • sourcestringRequired

        Format uuid

        A forecast source's id, as POST /forecast-sources returns it; one you can read.

      • reserves_categorystringOptional

        at least 1 characters

        The reserves category to compare, exactly as GET /forecast-sources/{id} reserves_categories lists it; required when the source holds more than one.

  • bobjectRequired

    Side b. It may be the plan of side a, with another scenario or design, or a forecast source when side a is a plan.

    ShowHide 2 variants

    Any of

    • ComparisonSide object

      One side: a plan's wells under one design, or one scenario's.

      • planstringRequired

        Format uuid

        A done plan's id, as POST /plans returns it.

      • scenariostringOptional

        1 to 60 characters

        On a plan made with scenarios, the scenario to compare, exactly as its scenarios list it; required there, and a 400 on a plan without scenarios. A name it doesn't have is a 400 whose details.scenarios lists them.

      • designintegerOptional

        Default 0≥ 0

        The design, as its index in the plan's designs; 0 by default. One past the last is a 400.

    • ComparisonSourceSide object

      A forecast source as one side; the other side is a plan. Any other field is a 400 listing these.

      • sourcestringRequired

        Format uuid

        A forecast source's id, as POST /forecast-sources returns it; one you can read.

      • reserves_categorystringOptional

        at least 1 characters

        The reserves category to compare, exactly as GET /forecast-sources/{id} reserves_categories lists it; required when the source holds more than one.

  • metricstringOptional

    The per-well metric distribution, groups and curves measure: eur_boe by default when both sides have EUR, else cum_boe.

    Per-well metrics: eur_oil (bbl), eur_gas (mcf) and eur_boe (BOE) are each well's EUR and need a plan made with eur: true (400 otherwise); cum_oil, cum_gas and cum_boe are the forecast's cumulative volume at ip_day. BOE is oil + gas / 6, only for wells with both.

    "eur_boe""eur_oil""eur_gas""cum_boe""cum_oil""cum_gas"
  • ip_dayintegerOptional

    ≥ 1

    For a cum_ metric, the ip_day to measure, one of the forecast ip_days GET /dataset lists; 1080 by default. With an eur_ metric it is a 400.

  • normalize_lateral_ftnumberOptional

    ≥ 100, ≤ 20000

    Scale each well's value to this lateral length in distribution and groups, as GET /plans/{id}/stats does: value × normalize_lateral_ft / its lateral_length_ft. Totals and curves stay unscaled. 100 to 20,000.

  • group_bystringOptional

    Also compare each group of wells: design (every design index either side has), formation (each well's target formation, null for none), scenario (a 400 when neither side's plan has scenarios), or pad (the pad key, null for wells without one; 400 when neither plan has keys). Pads pair by key in side a plan order then new side b keys, null last, without a cap or Other row.

    "design""formation""scenario""pad"
  • includearray of stringsOptional

    Optional parts. Any other value is a 400 listing these.

    "curves""bands""wells""inputs""value"
  • pairobjectOptional

    How to pair the sides' wells; adds pairs to the answer.

    ShowHide 3 child fields
    • bystringOptional

      Default "auto"

      auto (default): name when every well on both sides has a real name and none repeats on a side, else location; with a forecast source side, saved, else name, else uwi.

      • name: names found once on each side; a repeated name's wells pair by location within it.
      • location: heel and bottom hole each within tolerance_ft; same formation first, then closest, then nearest TVD; one to one.
      • index: by position, with a warning.
      • map: the pairs in map.
      • uwi and saved: forecast source sides only; location and index: plan sides only.
      "auto""name""location""index""map""uwi""saved"
    • tolerance_ftnumberOptional

      Default 300≥ 1, ≤ 5280

      With auto or location: how far apart, ft, a pair's heels (else surface holes) and bottom holes may each be; 300 by default. With another by it is a 400.

    • maparray of arraysOptional

      Items 2 items

      With by map, and only then: the pairs, each well once; an index or Well ID outside its side's wells or used twice is a 400 naming the entry (pair.map[k]).

  • wellsobjectOptional

    Paging for the per-well rows; needs include wells (a 400 without).

    ShowHide 4 child fields
    • limitintegerOptional

      Default 100≥ 1, ≤ 1000

      Rows a page: 1 to 1,000, 100 by default.

    • cursorstringOptional

      wells.next_cursor from the previous page, with the same request otherwise.

    • sortstringOptional

      Default "abs_delta"

      abs_delta (default): the size of delta; delta: delta itself; a_index: side a's well index (a forecast source side a: its file order). Rows without the value go last; ties in side a's order.

      "abs_delta""delta""a_index"
    • orderstringOptional

      desc by default for abs_delta and delta, asc for a_index.

      "asc""desc"
  • horizonstring or objectOptional

    Each side's cumulative at a common horizon beside its EUR; needs EUR on both sides (a 400 naming the side without).

    ShowHide 2 variants

    Any of

    • own: each side's EUR only, the default string

      own: each side's EUR only, the default.

      "own"
    • Option 2 object

      A common horizon: cumulative rows at that many years.

      • yearsintegerRequired

        ≥ 1, ≤ 50

        Years.

  • alignstringOptional

    calendar adds curves.calendar, each side's curve by calendar month (needs include curves and a well with a TIL date on each side, or a start date on every well of a forecast source side); months_on, the default, adds nothing.

    "months_on""calendar"
  • deck_idstringOptional

    With include value (a 400 without it): the deck to price both sides with, as POST /economics takes it; left out, the set's default deck.

    "prototype-midland-flat""house-70-3""illustrative-haynesville-gas"
  • deckobjectOptional

    With include value (a 400 without it): overrides of the deck's values, each within its range, as POST /economics takes them.

    ShowHide 20 child fields
    • oil_pricenumberOptional

      ≥ 0, ≤ 300

      $/bbl; 75 in the illustrative Midland deck.

    • oil_differentialnumberOptional

      ≥ -50, ≤ 50

      $/bbl; 4 in the illustrative Midland deck.

    • gas_pricenumberOptional

      ≥ 0, ≤ 50

      $/mcf; 3.5 in the illustrative Midland deck.

    • gas_differentialnumberOptional

      ≥ -10, ≤ 10

      $/mcf; 1 in the illustrative Midland deck.

    • ngl_pricenumberOptional

      ≥ 0, ≤ 200

      $/bbl; 26 in the illustrative Midland deck.

    • ngl_yield_bbl_per_mmcfnumberOptional

      ≥ 0, ≤ 300

      bbl/MMcf; 130 in the illustrative Midland deck.

    • shrinknumberOptional

      ≥ 0, ≤ 1

      fraction; 0.8 in the illustrative Midland deck.

    • opex_oilnumberOptional

      ≥ 0, ≤ 100

      $/bbl; 5.5 in the illustrative Midland deck.

    • opex_gasnumberOptional

      ≥ 0, ≤ 20

      $/mcf; 0.5 in the illustrative Midland deck.

    • opex_waternumberOptional

      ≥ 0, ≤ 20

      $/bbl; 0.6 in the illustrative Midland deck.

    • royaltynumberOptional

      ≥ 0, ≤ 0.5

      fraction; 0.25 in the illustrative Midland deck.

    • severance_oilnumberOptional

      ≥ 0, ≤ 0.5

      fraction; 0.046 in the illustrative Midland deck.

    Show all 20 fields
    • severance_gasnumberOptional

      ≥ 0, ≤ 0.5

      fraction; 0.075 in the illustrative Midland deck.

    • ad_valoremnumberOptional

      ≥ 0, ≤ 0.2

      fraction; 0.025 in the illustrative Midland deck.

    • capex_per_wellnumberOptional

      ≥ 0, ≤ 50000000

      $; 2500000 in the illustrative Midland deck.

    • capex_drilling_per_ftnumberOptional

      ≥ 0, ≤ 2000

      $/ft; 150 in the illustrative Midland deck.

    • capex_stimulation_per_ftnumberOptional

      ≥ 0, ≤ 2000

      $/ft; 125 in the illustrative Midland deck.

    • capex_proppant_per_lbnumberOptional

      ≥ 0, ≤ 2

      $/lb; 0.08 in the illustrative Midland deck.

    • capex_fluid_per_bblnumberOptional

      ≥ 0, ≤ 50

      $/bbl; 3 in the illustrative Midland deck.

    • discount_ratenumberOptional

      ≥ 0, ≤ 1

      fraction per year; 0.25 in the illustrative Midland deck.

  • conventionsstringOptional

    Default "prototype"

    With include value (a 400 without it): how NPV and payback are counted, as POST /economics takes it.

    "prototype""fe"

Responses

200 OK

Both sides' echoes, totals, distribution and warnings, with groups, curves, pairs, per-well rows, changed inputs and value when asked.

  • aobjectRequired

    Side a's echo: a plan side's, or a forecast source side's.

    ShowHide 2 variants

    One of

    • ComparisonSideEcho object

      What one side is and what made it.

      • kindstringRequired

        What the side is: plan. A forecast source side's echo is a SourceSideEcho, whose kind is source.

        "plan""source"
      • planobjectRequired

        The plan.

        ShowHide 2 child fields
        • idstringRequired

          Format uuid

          Plan id.

        • namestring or nullRequired

          Plan name.

      • scenariostring or nullRequired

        The scenario compared; null for a plan without scenarios.

      • designobjectRequired

        The design compared.

        ShowHide 2 child fields
        • indexintegerRequired

          ≥ 0

          The design, as its index in designs.

        • namestringRequired

          The design's name.

      • model_setstringRequired

        The model set that ran the plan: a stored plan's record names it; a plan kept in this server's memory is on the set the request reached.

      • releasestringRequired

        The app version that ran the plan, as GET /health app_version: a stored plan's record names it; a plan kept in memory ran on this server's; unknown when the server has no VERSION.

      • run_atstringRequired

        Format date-time

        When the plan was created, UTC.

      • declineobject or nullRequired

        The EUR settings the plan was fit with, as GET /plans/{id} decline (per_well when one of the side's wells has its own); null without EUR.

        ShowHide 8 child fields
        • eur_yearsintegerRequired

          ≥ 10, ≤ 50

          Years to EUR: the extension runs to the last 30-day step within eur_years × 365 days.

        • terminal_declinenumberRequired

          ≥ 0.01, ≤ 0.2

          Terminal decline, a fraction per year: the hyperbolic switches to exponential at this rate.

        • b_minnumberRequired

          ≥ 0, ≤ 2.5

          Lowest hyperbolic b the fit may use; below b_max.

        • b_maxnumberRequired

          ≥ 0, ≤ 2.5

          Highest hyperbolic b the fit may use; above b_min.

        • oilobjectOptional

          With per-stream settings, the settings oil was fit with.

          ShowHide 3 child fields
          • terminal_declinenumberRequired

            ≥ 0.01, ≤ 0.2

            Terminal decline, a fraction per year: the hyperbolic switches to exponential at this rate.

          • b_minnumberRequired

            ≥ 0, ≤ 2.5

            Lowest hyperbolic b the fit may use; below b_max.

          • b_maxnumberRequired

            ≥ 0, ≤ 2.5

            Highest hyperbolic b the fit may use; above b_min.

        • gasobjectOptional

          With per-stream settings, the settings gas was fit with.

          Same fields as StreamDecline.

        • waterobjectOptional

          Only with eur_water: true: the settings water was fit with. Its presence is the echo of the flag.

          Same fields as StreamDecline.

        • per_wellbooleanOptional

          Only when a well has its own settings: these are the request's or plan's, not every well's; inputs.resolved.decline gives each well's.

          true
      • bandsobject or nullRequired

        The plan's bands, as GET /plans/{id} bands; null when it was made without them.

        ShowHide 3 child fields
        • percentiles[integer, integer]Required

          The bands' percentiles: 10 (low) and 90 (high).

        • methodstringRequired

          How the bands are made: Novi's predrill bands (split conformal, safe variant).

        • eurbooleanRequired

          Whether each oil and gas band, and water's with eur_water, has its EUR (band_eur).

      • wellsintegerRequired

        ≥ 0

        The side's wells: the scenario's, else the plan's.

      • wells_with_forecastintegerRequired

        ≥ 0

        Of them, wells with a forecast under the design, as the matching GET /plans/{id} totals row counts them.

      • unplacedobjectRequired

        Wells the plan couldn't place.

        ShowHide 2 child fields
        • countintegerRequired

          ≥ 0

          The side's wells that couldn't be placed (per_well_errors).

        • messagestring or nullRequired

          The first one's reason; null when none.

    • SourceSideEcho object

      What a forecast source side is and how its numbers were made.

      • kindstringRequired

        A forecast source side.

        "source"
      • sourceobjectRequired

        The forecast source.

        ShowHide 2 child fields
        • idstringRequired

          Format uuid

          Forecast source id.

        • namestringRequired

          Its name.

      • formatstringRequired

        The file's format, as GET /forecast-sources/{id} format.

      • fileobjectRequired

        The file the source was read from.

        ShowHide 3 child fields
        • namestring or nullRequired

          The file's name; null when none was sent.

        • bytesintegerRequired

          ≥ 0

          Its size.

        • read_atstringRequired

          Format date-time

          When it was read and saved, UTC.

      • conventionsobjectRequired

        The profile's conventions, as GET /conventions?include=decline_profiles lists them.

        ShowHide 4 child fields
        • profilestringRequired

          The decline profile its curves ran under.

          "valnav""mosaic""combocurve""novi""aries"
        • declinesarray of stringsRequired

          The decline bases the profile reads.

          "nominal""secant""tangent"
        • year_daysnumberRequired

          Days in the profile's year.

        • monthsstringRequired

          calendar, or 30-day months from ip day 0.

          "calendar""30-day"
      • unitsstringRequired

        The units the file was in; every number here is converted to bbl, mcf and BOE.

        "imperial""metric"
      • gas_basisstringRequired

        raw or sales gas, as the source states it; Novi forecasts raw gas.

        "raw""sales"
      • reserves_categorystringRequired

        The reserves category compared.

      • wellsintegerRequired

        ≥ 0

        The source's wells under the category.

      • wells_with_forecastintegerRequired

        ≥ 0

        Of them, wells with a stream Novi's Arps decline calculation could run.

      • curvesintegerRequired

        ≥ 0

        The source's curves under the category.

  • bobjectRequired

    Side b's echo: a plan side's, or a forecast source side's.

    ShowHide 2 variants

    One of

    • ComparisonSideEcho object

      What one side is and what made it.

      • kindstringRequired

        What the side is: plan. A forecast source side's echo is a SourceSideEcho, whose kind is source.

        "plan""source"
      • planobjectRequired

        The plan.

        ShowHide 2 child fields
        • idstringRequired

          Format uuid

          Plan id.

        • namestring or nullRequired

          Plan name.

      • scenariostring or nullRequired

        The scenario compared; null for a plan without scenarios.

      • designobjectRequired

        The design compared.

        ShowHide 2 child fields
        • indexintegerRequired

          ≥ 0

          The design, as its index in designs.

        • namestringRequired

          The design's name.

      • model_setstringRequired

        The model set that ran the plan: a stored plan's record names it; a plan kept in this server's memory is on the set the request reached.

      • releasestringRequired

        The app version that ran the plan, as GET /health app_version: a stored plan's record names it; a plan kept in memory ran on this server's; unknown when the server has no VERSION.

      • run_atstringRequired

        Format date-time

        When the plan was created, UTC.

      • declineobject or nullRequired

        The EUR settings the plan was fit with, as GET /plans/{id} decline (per_well when one of the side's wells has its own); null without EUR.

        Same fields as Decline.

      • bandsobject or nullRequired

        The plan's bands, as GET /plans/{id} bands; null when it was made without them.

        Same fields as BandsEcho.

      • wellsintegerRequired

        ≥ 0

        The side's wells: the scenario's, else the plan's.

      • wells_with_forecastintegerRequired

        ≥ 0

        Of them, wells with a forecast under the design, as the matching GET /plans/{id} totals row counts them.

      • unplacedobjectRequired

        Wells the plan couldn't place.

        ShowHide 2 child fields
        • countintegerRequired

          ≥ 0

          The side's wells that couldn't be placed (per_well_errors).

        • messagestring or nullRequired

          The first one's reason; null when none.

    • SourceSideEcho object

      What a forecast source side is and how its numbers were made.

      • kindstringRequired

        A forecast source side.

        "source"
      • sourceobjectRequired

        The forecast source.

        ShowHide 2 child fields
        • idstringRequired

          Format uuid

          Forecast source id.

        • namestringRequired

          Its name.

      • formatstringRequired

        The file's format, as GET /forecast-sources/{id} format.

      • fileobjectRequired

        The file the source was read from.

        ShowHide 3 child fields
        • namestring or nullRequired

          The file's name; null when none was sent.

        • bytesintegerRequired

          ≥ 0

          Its size.

        • read_atstringRequired

          Format date-time

          When it was read and saved, UTC.

      • conventionsobjectRequired

        The profile's conventions, as GET /conventions?include=decline_profiles lists them.

        ShowHide 4 child fields
        • profilestringRequired

          The decline profile its curves ran under.

          "valnav""mosaic""combocurve""novi""aries"
        • declinesarray of stringsRequired

          The decline bases the profile reads.

          "nominal""secant""tangent"
        • year_daysnumberRequired

          Days in the profile's year.

        • monthsstringRequired

          calendar, or 30-day months from ip day 0.

          "calendar""30-day"
      • unitsstringRequired

        The units the file was in; every number here is converted to bbl, mcf and BOE.

        "imperial""metric"
      • gas_basisstringRequired

        raw or sales gas, as the source states it; Novi forecasts raw gas.

        "raw""sales"
      • reserves_categorystringRequired

        The reserves category compared.

      • wellsintegerRequired

        ≥ 0

        The source's wells under the category.

      • wells_with_forecastintegerRequired

        ≥ 0

        Of them, wells with a stream Novi's Arps decline calculation could run.

      • curvesintegerRequired

        ≥ 0

        The source's curves under the category.

  • totalsarray of objectsRequired

    EUR rows when both sides have EUR, then with horizon the cumulative rows at its day (horizon_years set), then cumulative rows at ip_day for a cum_ metric. A forecast source side's EUR runs each curve to its own limit or end date.

    ShowHide 10 child fields in each item
    • metricstringRequired

      What the row totals.

      • eur_<stream>: EUR summed over the side's wells with that EUR (BOE over those with both oil and gas).
      • cum_<stream>: the summed forecast's cumulative at ip_day (BOE: the forecast.boe total GET /plans/{id}?boe=true serves, over the wells with both oil and gas forecasts); on a horizon row (horizon_years set), at that horizon's day (BOE over those with both).
      "eur_oil""eur_gas""eur_water""eur_boe""cum_oil""cum_gas""cum_boe"
    • unitstringRequired

      The unit of a, b and delta: bbl (oil, water), mcf (gas) or BOE.

      "bbl""mcf""BOE"
    • ip_dayinteger or nullRequired

      For a cum_ row, the ip_day; null for an EUR row.

    • anumber or nullRequired

      Side a's total; null when no well has it.

    • bnumber or nullRequired

      Side b's total; null when no well has it.

    • deltanumber or nullRequired

      b − a, rounded to 0.1; null when either is null.

    • delta_pctnumber or nullRequired

      (b − a) / a × 100, relative to side a, rounded to 0.01; null when a is 0 or either is null.

    • a_wellsintegerRequired

      ≥ 0

      Side a's wells the total covers.

    • b_wellsintegerRequired

      ≥ 0

      Side b's wells the total covers.

    • horizon_yearsintegerOptional

      ≥ 1

      On a horizon row only: the years asked; ip_day is that horizon's day.

  • distributionobjectRequired

    Each side's distribution of the metric over its wells, and how it moved.

    ShowHide 8 child fields
    • metricstringRequired

      The metric measured.

      "eur_boe""eur_oil""eur_gas""cum_boe""cum_oil""cum_gas"
    • unitstringRequired

      The unit of every value: bbl (oil), mcf (gas) or BOE.

      "bbl""mcf""BOE"
    • ip_dayinteger or nullRequired

      For a cum_ metric, the ip_day measured; null for an eur_ metric.

    • aobjectRequired

      One side's distribution of the metric over its wells, as GET /plans/{id}/stats gives it, in distribution.unit.

      ShowHide 8 child fields
      • wellsintegerRequired

        ≥ 0

        Wells with a value; every figure describes them.

      • missingintegerRequired

        ≥ 0

        Wells without one: no forecast, a failed EUR fit, or BOE without both oil and gas.

      • minnumber or nullRequired

        Smallest value; null when no well has one.

      • maxnumber or nullRequired

        Largest value; null when no well has one.

      • meannumber or nullRequired

        Mean value per well; null when no well has one.

      • quantilesobjectRequired

        q10, q50 and q90 of the wells' values (linear interpolation between the closest ranks), not P-level bands; each null when no well has a value.

      • namestringOptional

        In a pad group, this side's name for the pad when its plan gives one in pads[].name; absent otherwise. The sides are paired by key and may name it differently.

      • othersintegerOptional

        ≥ 1

        On a group's Other row only: how many of the side's groups it sums.

    • bobjectRequired

      One side's distribution of the metric over its wells, as GET /plans/{id}/stats gives it, in distribution.unit.

      Same fields as ComparisonSpread.

    • deltaobjectRequired

      b − a (rounded to 0.1), or (b − a) / a × 100 relative to side a (rounded to 0.01) as delta_pct.

      ShowHide 2 child fields
      • meannumber or nullRequired

        Of the mean per well; null when either side has none.

      • q50number or nullRequired

        Of the median well; null when either side has none.

    • delta_pctobjectRequired

      b − a (rounded to 0.1), or (b − a) / a × 100 relative to side a (rounded to 0.01) as delta_pct.

      Same fields as ComparisonDelta.

    • normalize_lateral_ftnumberOptional

      With normalize_lateral_ft: the lateral every value was scaled to, ft.

  • warningsarray of objectsRequired

    Reasons a difference may not come from the plans, in a fixed order; empty when there are none.

    ShowHide 2 child fields in each item
    • codestringRequired

      Stable code; more may come.

      • Any sides: different_model_sets, models_changed, different_releases, different_eur_settings, side_without_eur, wells_without_forecast, side_without_bands, index_pairing, duplicate_names, no_band_position.
      • With a forecast source side: gas_basis_differs, conventions_differ, horizons_differ, source_unpaired, and with include value, value_wells_differ.
    • messagestringRequired

      One sentence to show beside the numbers.

  • group_bystringOptional

    With group_by: what groups is by.

    "design""formation""scenario""pad"
  • groupsarray of objectsOptional

    With group_by: one row per key on either side, in GET /plans/{id}/stats order (scenarios: side a's plan's order, then any only side b's plan has); pad keys use side a plan order then new side b keys, null last, with no cap or Other row. For other groupings, at most 50, the rest in one Other row.

    ShowHide 5 child fields in each item
    • keystring or integer or nullRequired

      The design index, the formation (null for wells without one), the scenario, the pad key (null for wells without one), or Other on the summed row. Pads never fold into Other.

    • aobject or nullRequired

      Side a's wells in the group; null when it has none.

      Same fields as ComparisonSpread.

    • bobject or nullRequired

      Side b's wells in the group; null when it has none.

      Same fields as ComparisonSpread.

    • deltaobject or nullRequired

      b − a; null when a side has no wells in the group.

      Same fields as ComparisonDelta.

    • delta_pctobject or nullRequired

      Relative to side a; null when a side has no wells in the group.

      Same fields as ComparisonDelta.

  • curvesobjectOptional

    Each side's summed curve for the metric's stream, with include curves.

    ShowHide 7 child fields
    • axisstringRequired

      Curves run by days since TIL (ip_days), not calendar dates.

      "ip_days"
    • streamstringRequired

      The metric's stream.

      "oil""gas""boe"
    • unitstringRequired

      The cumulative's unit.

      "bbl""mcf""BOE"
    • rate_unitstringRequired

      The rate's unit: the volume per day.

      "bbl/d""mcf/d""BOE/d"
    • aobject or nullRequired

      Side a's; null when none of its wells has the stream (BOE: both oil and gas).

      ShowHide 4 child fields
      • ip_daysarray of integersRequired

        Items ≥ 1

        The forecast's days.

      • cumarray of numbersRequired

        The side's summed cumulative, as GET /plans/{id} totals forecast (BOE: its forecast.boe with boe=true, over the wells with both oil and gas forecasts).

      • ratearray of numbersRequired

        Each step's rate: the cumulative's rise from the day before (from 0 on day 0) over the days between.

      • bandsobjectOptional

        With include bands, where the side's plan was made with bands and every well has them; a sum of per-well bands assumes fully correlated outcomes, so it is not a confidence interval for the plan.

        ShowHide 2 child fields
        • p10array of numbersRequired

          The summed P10 cumulative (Novi's P10 is the low curve).

        • p90array of numbersRequired

          The summed P90 cumulative.

    • bobject or nullRequired

      Side b's; null when none of its wells has the stream (BOE: both oil and gas).

      Same fields as ComparisonCurve.

    • calendarobjectOptional

      With align calendar: each side's summed curve by calendar month.

      ShowHide 2 child fields
      • aobject or nullRequired

        Side a's; null when none of its wells has the stream (BOE: both oil and gas).

        ShowHide 4 child fields
        • datesarray of stringsRequired

          Each month start from the side's first TIL month, as GET /plans/{id} totals.by_date.dates.

        • cumarray of numbersRequired

          The side's cumulative, as totals.by_date; BOE over the wells with both oil and gas, as GET /plans/{id}?boe=true totals count them (each well's oil plus gas / 6, summed, to 0.1).

        • ratearray of numbersRequired

          Each month's rate: the cumulative's rise over the calendar days between month starts; null for the first.

        • bandsobjectOptional

          With include bands, where every well of the side has bands; a sum of per-well bands assumes fully correlated outcomes, so it is not a confidence interval for the plan.

          ShowHide 2 child fields
          • p10array of numbersRequired

            The summed P10 (Novi's P10 is the low curve).

          • p90array of numbersRequired

            The summed P90.

      • bobject or nullRequired

        Side b's; null when none of its wells has the stream (BOE: both oil and gas).

        Same fields as ComparisonDateCurve.

  • pairsobjectOptional

    With pair, include wells or include inputs: how the wells paired.

    ShowHide 5 child fields
    • bystringRequired

      The method that paired them: what pair.by asked, or for auto, name or location.

      "name""location""index""map""uwi""saved"
    • pairedintegerRequired

      ≥ 0

      Pairs.

    • a_onlyarray of integer or stringRequired

      Side a's wells left unpaired, ascending; a forecast source side's in its file order.

    • b_onlyarray of integer or stringRequired

      Side b's wells left unpaired, ascending; a forecast source side's in its file order.

    • tolerance_ftnumberOptional

      By location only: the tolerance used, ft.

  • wellsobjectOptional

    With include wells.

    ShowHide 3 child fields
    • summaryobjectRequired

      Over every pair, so the same on every page.

      ShowHide 6 child fields
      • pairedintegerRequired

        ≥ 0

        Pairs.

      • metricstringRequired

        The metric measured.

        "eur_boe""eur_oil""eur_gas""cum_boe""cum_oil""cum_gas"
      • unitstringRequired

        The unit of a, b and delta: bbl, mcf or BOE.

        "bbl""mcf""BOE"
      • delta_pctobjectRequired

        Each pair's percent change, relative to side a.

        ShowHide 5 child fields
        • q10number or nullRequired

          Of the pairs' delta_pct (linear between closest ranks), to 0.01; quantiles of pairs, not P-levels.

        • q50number or nullRequired

          The median pair's.

        • q90number or nullRequired

          Of the pairs' delta_pct.

        • valuesarray of numbersOptional

          Under 20 pairs: every delta_pct, ascending.

        • histogramobjectOptional

          At 20 pairs or more.

          ShowHide 2 child fields
          • edgesarray of numbersRequired

            Equal-width bins from the smallest to the largest delta_pct; ceil(log2 n) + 1 bins (Sturges, n the pairs with a delta_pct), one when all are equal, none when no pair has one.

          • countsarray of integersRequired

            Items ≥ 0

            They add up to the pairs with a delta_pct; the last bin is closed.

      • left_outintegerRequired

        ≥ 0

        Pairs with no delta_pct: side a's value 0, or either value missing.

      • bandobjectOptional

        With band_eur on side a and an eur_ metric: the four add up to paired.

        ShowHide 4 child fields
        • below_p10integerRequired

          ≥ 0

          Pairs whose b is below side a's P10.

        • p10_p90integerRequired

          ≥ 0

          Inside, edges included.

        • above_p90integerRequired

          ≥ 0

          Above side a's P90.

        • noneintegerRequired

          ≥ 0

          Without a position: b or the band missing.

    • rowsarray of objectsRequired

      This page of the pairs, in wells.sort order.

      ShowHide 11 child fields in each item
      • labelstringRequired

        Side a's well name, else Plan well N; a forecast source side a's Well ID.

      • anumber or nullRequired

        Side a's value of the metric, as distribution measures it, to 0.1; null without one.

      • bnumber or nullRequired

        Side b's value, likewise.

      • deltanumber or nullRequired

        b − a, rounded to 0.1; null when either is null.

      • delta_pctnumber or nullRequired

        (b − a) / a × 100, relative to side a, rounded to 0.01; null when a is 0 or either is null.

      • a_indexintegerOptional

        ≥ 0

        Side a's plan well index; a forecast source side a has a_well_id instead.

      • b_indexintegerOptional

        ≥ 0

        Side b's plan well index; a forecast source side b has b_well_id instead.

      • a_well_idstringOptional

        Side a's Well ID when side a is a forecast source.

      • b_well_idstringOptional

        Side b's Well ID when side b is a forecast source.

      • b_labelstringOptional

        When side b is a plan: its well's name, else Plan well N, as label names side a's; a forecast source side b has b_well_id instead.

      • band_positionstring or nullOptional

        With band_eur on side a and an eur_ metric: where b falls in side a's P10 to P90 EUR (below_p10, p10_p90 with the edges inside, above_p90); null when b or the band is missing.

        "below_p10""p10_p90""above_p90"
    • next_cursorstring or nullRequired

      Send as wells.cursor for the next page; null on the last.

  • inputsobjectOptional

    With include inputs.

    ShowHide 1 child field
    • changedarray of objectsRequired

      Only inputs that differ on at least one pair, in a fixed order; empty when none do.

      ShowHide 4 child fields in each item
      • fieldstringRequired

        The input: formation, tvd_ft (as landed), lateral_length_ft, fluid_bbl_per_ft, proppant_lb_per_ft (as run under each side's design), til_date, or with EUR on both sides decline.eur_years and decline.<stream>.terminal_decline, b_min or b_max.

      • unitstring or nullRequired

        The unit of typical_change: ft, bbl/ft, lb/ft, days, years or fraction per year; null for formation and the b exponents.

      • wellsintegerRequired

        ≥ 1

        Pairs where it differs, at the precision it is shown to.

      • typical_changenumber or object or nullRequired

        null when no differing pair has both values.

        ShowHide 2 variants

        Any of

        • number number

          b − a: the median among the pairs that differ with both values.

        • For formation: the most common change object

          For formation: the most common change.

          • fromstring or nullRequired

            Side a's.

          • tostring or nullRequired

            Side b's.

  • valueobjectOptional

    With include value: each side priced as one POST /economics scenario under one deck and conventions, and the difference.

    ShowHide 6 child fields
    • labelstringRequired

      What to show beside the numbers: Simulated half-cycle economics, deck <name>.

    • deckobjectRequired

      The effective deck.

      ShowHide 6 child fields
      • deck_idstringRequired

        The deck's id.

      • versionintegerRequired

        ≥ 1

        Its version.

      • namestringRequired

        Its display name, as GET /economics/decks lists it; name results by it.

      • overridesarray of stringsRequired

        The fields this request overrode.

        "oil_price""oil_differential""gas_price""gas_differential""ngl_price""ngl_yield_bbl_per_mmcf""shrink""opex_oil""opex_gas""opex_water""royalty""severance_oil""severance_gas""ad_valorem""capex_per_well""capex_drilling_per_ft""capex_stimulation_per_ft""capex_proppant_per_lb""capex_fluid_per_bbl""discount_rate"
      • discount_ratenumberRequired

        The effective annual discount rate used for npv.

      • valuesobjectRequired

        The values priced with.

        ShowHide 20 child fields
        • oil_pricenumberRequired

          $/bbl

        • oil_differentialnumberRequired

          $/bbl

        • gas_pricenumberRequired

          $/mcf

        • gas_differentialnumberRequired

          $/mcf

        • ngl_pricenumberRequired

          $/bbl

        • ngl_yield_bbl_per_mmcfnumberRequired

          bbl/MMcf

        • shrinknumberRequired

          fraction

        • opex_oilnumberRequired

          $/bbl

        • opex_gasnumberRequired

          $/mcf

        • opex_waternumberRequired

          $/bbl

        • royaltynumberRequired

          fraction

        • severance_oilnumberRequired

          fraction

        Show all 20 fields
        • severance_gasnumberRequired

          fraction

        • ad_valoremnumberRequired

          fraction

        • capex_per_wellnumberRequired

          $

        • capex_drilling_per_ftnumberRequired

          $/ft

        • capex_stimulation_per_ftnumberRequired

          $/ft

        • capex_proppant_per_lbnumberRequired

          $/lb

        • capex_fluid_per_bblnumberRequired

          $/bbl

        • discount_ratenumberRequired

          fraction per year

    • conventionsstringRequired

      The conventions priced under.

      "prototype""fe"
    • aobjectRequired

      One side priced.

      ShowHide 6 child fields
      • economicsobject or nullRequired

        The side's economics, as POST /economics gives a scenario's, or null.

        ShowHide 4 child fields
        • capexnumberRequired

          Capex, $, all at month 0.

        • irr_pctnumber or nullRequired

          IRR, % a year, annualized from the monthly rate (capped at 100% a month); null when the flows never return their capex.

        • payback_monthsnumber or nullRequired

          Months until the running total turns non-negative: interpolated within the month, or whole months under fe; null when it never does.

        • npvnumberRequired

          NPV, $, at the effective deck discount_rate, discounted as conventions says.

      • reasonstring or nullRequired

        Why economics is null: the first well without a cash flow and why, as POST /economics names it, or that none of a forecast source side's wells paired.

      • breakevenobject or nullRequired

        As POST /economics include breakeven gives a scenario's: the flat oil and gas prices at which the side's npv is 0, every other deck value and override held; null when economics is null.

        ShowHide 3 child fields
        • oil_pricenumber or nullRequired

          WTI, $/bbl: the flat oil price at which npv is 0, to within $0.000001; null when npv doesn't cross 0 between oil_price's min and max (GET /economics/deck).

        • gas_pricenumber or nullRequired

          Henry Hub, $/mcf: the flat gas price at which npv is 0, to within $0.000001; null when npv doesn't cross 0 between gas_price's min and max.

        • discount_ratenumberRequired

          The effective annual discount rate npv was taken at, as deck.discount_rate.

      • wellsintegerRequired

        ≥ 1

        The side's wells: a plan side's, or every well of a forecast source side under its reserves category.

      • pricedintegerRequired

        ≥ 0

        Wells with a cash flow.

      • unpricedarray of objectsRequired

        On a forecast source side, each well that didn't pair with a plan well, in the source's order; empty on a plan side.

        ShowHide 2 child fields in each item
        • well_idstringRequired

          The forecast source's Well ID.

        • reasonstringRequired

          Why it isn't priced.

    • bobjectRequired

      One side priced.

      Same fields as ComparisonValueSide.

    • deltaobjectRequired

      b − a, rounded half away from 0 to 0.01: swapping the sides negates every value, and a side against itself gives 0.

      ShowHide 5 child fields
      • capexnumber or nullRequired

        b − a, $, to 0.01; null when a side has no economics.

      • npvnumber or nullRequired

        b − a, $, to 0.01; null when a side has no economics.

      • irr_pctnumber or nullRequired

        b − a, percentage points, to 0.01; null when a side has no economics or no IRR.

      • payback_monthsnumber or nullRequired

        b − a, months, to 0.01; null when a side has no economics or never pays back.

      • breakevenobjectRequired

        b − a of each breakeven price.

        ShowHide 2 child fields
        • oil_pricenumber or nullRequired

          b − a, $/bbl, to 0.01; null when a side has no breakeven oil price.

        • gas_pricenumber or nullRequired

          b − a, $/mcf, to 0.01; null when a side has no breakeven gas price.

Errors

StatusWhen
404

No such well, grid, plan or route.

409

The request conflicts with the state of the plan or resource it names, and message says how: for example a plan still running or failed, a stale If-Match, an Idempotency-Key reused with another body, or a server without a state store.

413

The request body is over 10 MB.

Shared errors400401403500503What they mean