Skip to content
Developers
Get an API token

Price scenarios' economics

Prices scenarios as the Pad Optimizer ranks them: simulated half-cycle economics on each well's forecast and EUR under a deck (GET /economics/deck).

Price scenarios' economics

POST/economics

Prices scenarios as the Pad Optimizer ranks them: simulated half-cycle economics on each well's forecast and EUR under a deck (GET /economics/deck). Send scenarios of wells you have forecast, or a forecast for the server to run and price (not both: 400).

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

A scenario is a pad of 1 to 50 wells online together, or a done plan's wells; a request takes 1 to 250 scenarios and at most as many wells as a plan (GET /dataset limits.plan_wells). Without forecast, no model worker runs, so it answers in milliseconds.

  • Each well sends its lateral, its completion design, its oil, gas and water cumulative curves every 30 days from 30, as POST /forecasts returns them without ip_days (other days are a 400), and its oil and gas EUR with the EUR's ip_day.
  • On a plan made with scenarios, a scenario prices one of them, by scenario or by wells all in it.
A forecast

forecast prices drawn wells under several designs in one call, one scenario per design, in design order (see forecast).

  • Each well is priced as a plan's well is: its formation's completions under the design (else the design's own), its lateral from its ends, its curves and EUR as forecast.
  • A well whose forecast or EUR failed leaves its design's scenario unpriced, and reason names it (Drawn well N) and why.
  • The answer adds forecast (pdp, wells, the designs as run, the layout) and each scenario's forecast.design.
  • Wells × designs count toward the well limit, field paths start forecast., and a worker or layout error answers as POST /forecasts answers it.
Cash flows

Monthly: capex at month 0, the forecast's months, then each stream declines exponentially from its last month's rate to its EUR. Water follows oil at the forecast's last-year ratio. Wells are priced on the streams their model set serves: an unserved stream adds nothing, and on a set without oil, water follows gas.

What you get

Each scenario's economics (capex, IRR as a percent, payback in months, and NPV at the deck's discount_rate), or null with a reason: the first well without a cash flow (by its label, else wells[i]) and why, or the pad's. Each well without a cash flow has its own reason.

Deck and conventions

deck_id picks the deck and deck overrides its numbers for this request, each within its range; the answer echoes the effective deck with its id, version and overridden fields. conventions picks how NPV and payback are counted: prototype (the default and the app's) discounts years 2 on a whole year at a time with fractional payback, and fe discounts monthly with whole-month payback, matching Novi's earlier Forecast Engine. IRR is the same under both, and capex is all at month 0, since scenarios have no spud or completion dates.

Extras

include adds:

  • flows: each well's and the pad's monthly cash flows; scenario_flows: each scenario's only.
  • totals: scenarios, priced, wells, npv and capex over the priced scenarios, and their cash flow by month with flows; IRR and payback don't add. It sums a plan priced in batches; with it, two of one plan's scenarios (different scenario names) are a 400.
  • summary: each scenario's wells, priced wells, lateral, EUR and completions (ScenarioSummary).
  • breakeven: the flat oil_price (WTI) and gas_price (Henry Hub) at which NPV at discount_rate is 0 under the request's conventions, every other deck value held, each to within $0.000001 a bbl or mcf.

A breakeven price is null when NPV doesn't cross 0 between that key's min and max (GET /economics/deck), as when oil alone pays a pad back with gas at $0. breakeven is null on a scenario without economics, and totals has none.

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

Scenarios to price, or a forecast to run and price, and optional deck overrides.

  • scenariosarray of objectsOptional

    1 to 250 items

    Scenarios, 1 to 250; required unless forecast is sent.

    ShowHide 3 child fields in each item
    • keystringOptional

      1 to 200 characters

      Your id for the scenario, echoed.

    • wellsarray of objectsOptional

      1 to 50 items

      The pad's wells, online together (required unless plan is sent).

      ShowHide 6 child fields in each item
      • lateral_ftnumberRequired

        ≥ 100, ≤ 50000

        Lateral length, ft.

      • designobjectRequired

        The completion design, for capex.

        ShowHide 2 child fields
        • proppant_lb_per_ftnumberRequired

          > 0, < 20000

          Proppant, lb/ft.

        • fluid_bbl_per_ftnumberRequired

          > 0, < 1000

          Fluid, bbl/ft.

      • curvesobjectRequired

        The forecast's curves.

        ShowHide 3 child fields
        • oilobjectRequired

          A cumulative curve, as a forecast stream returns it without ip_days.

          ShowHide 2 child fields
          • ip_daysarray of integersRequired

            1 to 400 itemsItems ≥ 1, ≤ 18250

            ip_days 30, 60, 90 and so on, every 30 days from 30 with none skipped; any other days are a 400 on this field, and oil, gas and water must share them or the well has no cash flow (its reason says why). A forecast returns them this way when it is asked for no ip_days, and each point is priced as one 30-day month.

          • valuesarray of numbersRequired

            Cumulative volumes, one per ip_day; a null leaves the well without a cash flow.

        • gasobjectRequired

          A cumulative curve, as a forecast stream returns it without ip_days.

          Same fields as EconomicsCurve.

        • waterobjectOptional

          Water, for its opex; without it the well has no cash flow.

          Same fields as EconomicsCurve.

      • eurobjectRequired

        EUR per stream, as a decline fit returned it.

        ShowHide 2 child fields
        • oilnumberRequired

          Oil EUR, bbl.

        • gasnumberRequired

          Gas EUR, mcf.

      • eur_daysnumberRequired

        ≥ 0, ≤ 21900

        The EUR's ip_day (oil's days): the cash flow runs to it.

      • labelstringOptional

        1 to 200 characters

        Names the well in its scenario's reason; else wells[i].

    • planobjectOptional

      Instead of wells: a done plan's wells, by its id, a design and well indexes.

      ShowHide 4 child fields
      • idstringRequired

        Format uuid

        A done plan's id, from POST /plans.

      • designintegerOptional

        Default 0≥ 0, ≤ 9

        The plan design whose forecasts and completions are priced, its index from 0.

      • wellsarray of integersOptional

        1 to 50 itemsunique itemsItems ≥ 0

        The plan wells to price, by index; absent prices every well of a plan of up to 50.

      • scenariostringOptional

        1 to 60 characters

        On a plan made with scenarios: price this scenario's wells (up to 50, else send wells). A scenario prices one development, so on such a plan send scenario or wells all in one scenario (400 otherwise); on a plan without scenarios it is a 400.

  • forecastobjectOptional

    Instead of scenarios: wells or a layout the server forecasts, one scenario per design. Send scenarios or forecast, not both.

    ShowHide 5 child fields
    • designsarray of objectsRequired

      1 to 25 items

      Completion designs, 1 to 25: each prices every well as one scenario, in this order. Blank values are estimated, as in POST /forecasts.

      ShowHide 7 child fields in each item
      • namestring or nullOptional

        up to 60 characters

        Your name for the design; defaults to Design 1, Design 2, ….

      • fluid_bbl_per_ftnumber or nullOptional

        > 0, < 1000

        Completion fluid in bbl per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.

      • proppant_lb_per_ftnumber or nullOptional

        > 0, < 20000

        Proppant in lb per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.

      • stage_length_ftnumber or nullOptional

        > 0, < 2000

        Stage length in ft.

        Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

      • clusters_per_stagenumber or nullOptional

        > 0, < 100

        Perforation clusters per stage; fractions are accepted.

        Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

      • frac_rate_bbl_per_minnumber or nullOptional

        > 0, < 500

        Frac pump rate in bbl per minute.

        Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

      • formationsarray of objectsOptional

        Per-formation overrides, each formation at most once.

        ShowHide 6 child fields in each item
        • formationstringRequired

          Formation (case-insensitive).

        • fluid_bbl_per_ftnumber or nullOptional

          > 0, < 1000

          Completion fluid in bbl per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.

        • proppant_lb_per_ftnumber or nullOptional

          > 0, < 20000

          Proppant in lb per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.

        • stage_length_ftnumber or nullOptional

          > 0, < 2000

          Stage length in ft.

          Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

        • clusters_per_stagenumber or nullOptional

          > 0, < 100

          Perforation clusters per stage; fractions are accepted.

          Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

        • frac_rate_bbl_per_minnumber or nullOptional

          > 0, < 500

          Frac pump rate in bbl per minute.

          Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

    • wellsarray of objectsOptional

      1 to 50 items

      Drawn wells, as POST /forecasts takes them, without a scenario, name or decline (each is a 400; required unless layout is sent).

      ShowHide 22 child fields in each item
      • shl[number, number]Required

        Surface hole location, [lng, lat].

      • bhl[number, number]Required

        Bottom hole (toe) location, [lng, lat]. The lateral runs from heel, else shl, to bhl and must be 100 to 50,000 ft long.

      • formationstring or nullOptional

        Target formation (case-insensitive; GET /formations lists them). Needed to forecast and to estimate TVD.

      • tvd_ftnumber or nullOptional

        > 0, < 40000

        True vertical depth in ft. Blank estimates it from the structure grid and nearby wells.

      • landing_below_top_ftnumber or nullOptional

        > -40000, < 40000

        Instead of tvd_ft: how far below the formation top to land, ft. TVD is the formation top at the well plus this, the top in the set's TVD datum as POST /tvd-estimates' formation_top_ft gives it; needs formation and a grid there. The top is averaged over the well's surface and bottom hole, whatever the set's subsurface_sampling (GET /model-sets).

      • heel[number, number] or nullOptional

        Where the lateral starts, [lng, lat], when not at shl, the surface hole; absent or null, it starts at shl. shl must be within 50,000 ft of it.

        With it, the lateral length and its 100 to 50,000 ft check, spacing, gun barrel laterals, PDP wells and model analogs run from heel to bhl. Subsurface grids still sample at shl and bhl as the set's subsurface_sampling says, and structure tops, landing, TVD estimates, the KB elevation and the model's surface hole inputs stay at shl.

      • typed_lateralobject or nullOptional

        A lateral length typed for the well, as an inventory file gives it: length_ft, and the heel (the well's heel, else its shl) and bhl it was typed for.

        The model gets length_ft as novi_lateral_length, and spacing, the completion totals, analogs, normalize_lateral_ft and pricing use it, while the well's heel (else shl) and bhl equal those two exactly and it is within 5% of the length measured between them or within 100 to 50,000 ft; otherwise the measured length. A client that moves an end can send it unchanged: the well then uses the measured length.

        Reads give the length used as lateral_length_ft, with lateral_length_source. Optional: absent or null, the measured length.

        POST /inventories/read sets it from a file's stated length unless that is both more than 5% off the drawn one and outside 100 to 50,000 ft, with an issue when it is more than 5% off.

        ShowHide 3 child fields
        • length_ftnumberRequired

          ≥ 0, ≤ 1000000

          The typed length, ft.

        • heel[number, number]Required

          Where the lateral started when the length was typed: the well's heel, else its shl, [lng, lat].

        • bhl[number, number]Required

          The bottom hole the length was typed for, [lng, lat].

      • lateral_outsidestring or nullOptional

        Ignored; accepted so POST /layouts/fill wells with lateral_check can be sent as they are.

        "above""below"
      • landing_fractionnumber or nullOptional

        ≥ 0, ≤ 1

        Instead of tvd_ft or landing_below_top_ft: where to land as a fraction of the formation's thickness, 0 at its top to 1 at its base (0.5 the middle). TVD is top + landing_fraction × (base − top), to the foot.

        The top is the formation's structure grid: the set's own, else a TVD-only one in its depth pack. The base is the top of the next formation down the rock column with a grid at an end of the well (shl, bhl) the formation's own grid reaches.

        The rock column ranks the set's structure grids and its depth pack's TVD-only ones from the grids, not GET /formations order: at sample points spread over the grids' lattices, one lies below another when its top is a foot or more deeper at more of the points both reach than the reverse, or by median depth when they share none. Grids are ordered by how many others each lies below, less how many lie below it, ties by median depth. A grid with no value at any sample point is left out. Grids within a foot of each other wherever both reach are one surface: neither is the other's base, and both take the next surface below.

        Top and base are each averaged over the ends both grids reach, in the set's TVD datum as POST /tvd-estimates' formation_top_ft, and tvd_source names the base's formation. When the set's depth pack names a thickness grid, the base is the top plus that grid instead, and tvd_source names it. With a depth pack, a formation with no gridded formation below it at the well (as the deepest one) takes its base from its novi_thickness_avg grid.

        Needs formation. The well is refused as landing_below_top_ft is, naming landing_fraction, when:

        • its formation has no grid there or no place in the column;
        • no formation below it has a grid at an end its own grid reaches and, with a depth pack, it has no novi_thickness_avg grid there either (the error says when the grids reach different ends);
        • the base's top is a foot or more above the formation's at either end: the grids cross, the error names shl or bhl, and no deeper formation is tried;
        • top and base averaged over the ends are under a foot apart: the zone pinches out.

        A well's inputs echo it when it was sent.

      • lateral_length_ftnumber or nullOptional

        Ignored: the lateral runs from heel, else shl, to bhl, unless typed_lateral applies. Accepted so POST /layouts/fill wells can be sent as they are.

      • til_datestring or nullOptional

        Format date

        TIL (turn-in-line, first production) date, YYYY-MM-DD: ip_day 1 is this day.

        From GET /dataset as_of to 30 years from today. Blank takes the next wider layer's date, the request's til_date last, else today. In spacing it orders parents and children (a well online at least 90 days before a neighbor is its parent, and the parent's days online count from it) and dates every spacing feature row.

      • partinteger or nullOptional

        Ignored, as is bench: accepted so POST /layouts/fill wells can be sent as they are.

      Show all 22 fields
      • benchinteger or nullOptional

        Ignored.

      • padnumber or string or nullOptional

        The pad the well is on: a whole number, as POST /layouts/fill numbers them, or text of 1 to 60 characters, trimmed; 1 and "1" are one pad.

        POST /plans keeps a valid key whenever sent, for group_by=pad and the pad= filter, and doesn't echo it on wells; other requests read it only with pads. It is checked (a 400 on a bad value) only with pads; without pads, a value that isn't a pad is ignored.

      • scenariostringOptional

        1 to 60 characters

        The alternative the well is in: a scenario's wells space against only each other and existing wells, never another scenario's. A name of 1 to 60 characters, trimmed.

        Equal names (exact, case-sensitive) are one scenario; with pdp false its wells space against only each other. Give every well a scenario, or none (400 at the first without one). At most 10 scenarios on POST /forecasts, each its own spacing run, and 20 on POST /plans (400 at the first well past it, with details.max and details.count). Designs and pdp apply to every scenario unless scenarios sets its own.

      • fluid_bbl_per_ftnumber or nullOptional

        > 0, < 1000

        This well's fluid in bbl per lateral ft.

        Each field takes the narrowest layer that sets it, on its own: the well, its pad's entry in pads or its layout (the bench or formation entry, then overall), its entry in scenarios (formation entry, then overall), the design's formations entry for its formation, the design, then the default: the recent-completions median of the well's formation, else the play's.

        Needs one design or none; with more, the request is a 400 naming the well. POST /gun-barrels refuses it. Sending one adds resolved to every well's inputs in the request.

      • proppant_lb_per_ftnumber or nullOptional

        > 0, < 20000

        This well's proppant in lb per lateral ft.

        Each field takes the narrowest layer that sets it, on its own: the well, its pad's entry in pads or its layout (the bench or formation entry, then overall), its entry in scenarios (formation entry, then overall), the design's formations entry for its formation, the design, then the default: the recent-completions median of the well's formation, else the play's.

        Needs one design or none; with more, the request is a 400 naming the well. POST /gun-barrels refuses it. Sending one adds resolved to every well's inputs in the request.

      • stage_length_ftnumber or nullOptional

        > 0, < 2000

        Stage length in ft.

        Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

      • clusters_per_stagenumber or nullOptional

        > 0, < 100

        Perforation clusters per stage; fractions are accepted.

        Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

      • frac_rate_bbl_per_minnumber or nullOptional

        > 0, < 500

        Frac pump rate in bbl per minute.

        Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

      • declineobjectOptional

        EUR settings for this well; needs eur on.

        With eur off, a decline on any layer is a 400, even {} or one that reaches no well, though either sets nothing. POST /exports source turns eur on when it is left out.

        Each field takes the narrowest value set: the well's; its pad's or layout's, formations entry or bench first; its scenario's, formations entry first; the request's formations entry; the request's decline; Novi's defaults. The narrower layer wins first; within a layer, a stream's value beats the base: a well's b_max beats a plan's oil.b_max. Once a value reaches a well, every well's inputs.resolved.decline gives each value and its layer, and the export's wells table adds them.

        A well whose b_min resolves at or above its b_max is a 400 naming the well and both layers. The ARIES export refuses a scope whose wells differ. POST /gun-barrels and POST /economics forecast refuse a decline.

        ShowHide 7 child fields
        • eur_yearsintegerOptional

          ≥ 10, ≤ 50

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

        • terminal_declinenumberOptional

          ≥ 0.01, ≤ 0.2

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

        • b_minnumberOptional

          ≥ 0, ≤ 2.5

          Lowest hyperbolic b the fit may use; below b_max.

        • b_maxnumberOptional

          ≥ 0, ≤ 2.5

          Highest hyperbolic b the fit may use; above b_min.

        • oilobjectOptional

          Oil's own settings over these.

          ShowHide 3 child fields
          • terminal_declinenumberOptional

            ≥ 0.01, ≤ 0.2

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

          • b_minnumberOptional

            ≥ 0, ≤ 2.5

            Lowest hyperbolic b the fit may use; below b_max.

          • b_maxnumberOptional

            ≥ 0, ≤ 2.5

            Highest hyperbolic b the fit may use; above b_min.

        • gasobjectOptional

          Gas's own settings over these.

          Same fields as StreamDeclineSettings.

        • waterobjectOptional

          Water's own settings over these, only with eur_water: true, else a 400. Unlike oil and gas it doesn't set per-stream settings: oil and gas keep theirs and their calls.

          Same fields as StreamDeclineSettings.

      • namestring or nullOptional

        up to 60 characters

        Your name for the well, 1 to 60 characters once trimmed, on POST /plans, POST /forecasts and POST /inventories/write; other routes that take wells answer 400. null is none; a blank name is a 400.

        Names needn't be unique. Reads show it beside label, which stays Plan well N (Drawn well N on POST /forecasts). A plan's export tables put it in their well column, keeping their row order, with a leading quote where a spreadsheet would read it as a formula. ARIES heads the well with it, unquoted, and sorts by header, so wells with one name share a header: send aries.well_key: id to keep them apart.

    • layoutobjectOptional

      Instead of wells: a fill boundary the server lays 1 to 50 wells out in, as POST /forecasts takes it.

      ShowHide 22 child fields

      Send exactly one of: area or polygon.

      Send exactly one of: spacing_ft and formation or benches.

      • polygonarray of [number, number]sOptional

        3 to 500 items

        Area corners, in order (closing point optional). Edges that cross are a 400.

      • azimuth_degnumberOptional

        Default 0≥ -360, ≤ 360

        Direction wells are drilled, degrees clockwise from north.

      • spacing_ftnumberOptional

        ≥ 100, ≤ 10000

        Distance between wells, ft.

      • lateral_length_ftnumber or nullOptional

        ≥ 1000, ≤ 30000

        Lateral length, ft; null or absent runs each well edge to edge.

      • setback_ftnumber or nullOptional

        Default 0≥ 0, ≤ 2640

        Feet the wells keep from the unit's outline and holes, from every point of a well in any direction; with setback_end_ft, measured across the well (square to the azimuth).

      • areaobjectOptional

        Instead of polygon: the unit as a GeoJSON Polygon or MultiPolygon in WGS 84, an area's geometry from POST /areas or what POST /units/summary takes. Holes are left out and each part is filled on its own; rings follow the unit scope's rules (POST /units/summary). Every edge costs work on every line, so a detailed outline may be too complex to fill: simplify it (as POST /areas' fill.polygon is).

        ShowHide 2 variants

        One of

        • A polygon object

          A polygon.

          • typeanyRequired

            Always "Polygon"

            One part.

          • coordinatesarray of arraysRequired

            at least 1 itemsItems at least 3 items

            The outer ring, then its holes.

        • A multipolygon object

          A multipolygon.

          • typeanyRequired

            Always "MultiPolygon"

            Several parts, taken together.

          • coordinatesarray of arraysRequired

            at least 1 itemsItems at least 1 items

            The parts.

      • setback_end_ftnumber or nullOptional

        ≥ 0, ≤ 2640

        Feet each well's heel and toe keep from the outline and holes, in a straight line; the rest of the well may pass closer as long as setback_ft holds across it. With lateral_length_ft, a piece whose heel or toe would fall closer is left out. Every edge gets both rules, whatever its angle.

      • min_lateral_ftnumber or nullOptional

        ≥ 1000, ≤ 30000

        Shortest well, ft: every edge-to-edge chord at least this long is a well, instead of those within 95% of the longest. Not with lateral_length_ft.

        A kept chord longer than 30,000 ft between the rounded ends splits into the fewest equal wells of at most 30,000 ft, toe meeting heel; a split piece shorter than min_lateral_ft is left out, so such a chord may give no well.

      • standoff_ftnumber or nullOptional

        ≥ 0, ≤ 5280

        Least distance from every lateral to the existing laterals (heel, else surface hole, to bottom hole) in its formation that lie in the unit or within standoff_ft of it, ft. Needs a formation for every bench.

      • wells_per_padinteger or nullOptional

        ≥ 1, ≤ 50

        Groups the wells into pads of this many, numbered from 0 in each well's pad; a pad never spans two parts or tiers, so the last of each may hold fewer.

        A fill's pads only label wells: each well keeps its surface hole and the request's TIL date. To set a pad's values, post the fill's wells with pads. POST /plans keeps pad keys: with layout, the 1-based pad number as text; with layouts, the 1-based layout number, a hyphen, then the 1-based pad number. Without wells_per_pad, laid-out wells have no pad key. To price a pad, send its wells (a plan's layout echo pads) as a plan scenario's wells in POST /economics.

      • benchesarray of objectsOptional

        1 to 10 items

        Instead of spacing_ft: benches laid out together, each landed in its own formation, at its own tvd_ft, landing_below_top_ft or landing_fraction. Not with the layout's formation, tvd_ft, landing_below_top_ft or landing_fraction.

        ShowHide 13 child fields in each item

        Send exactly one of: spacing_ft or wells_per_section.

        • formationstringRequired

          The bench's formation (case-insensitive): its wells land in it, and standoff_ft stands off its laterals.

        • spacing_ftnumberOptional

          ≥ 100, ≤ 10000

          Distance between the bench's wells, ft. Not with wells_per_section.

        • wells_per_sectionnumberOptional

          ≥ 0.528, ≤ 52.8

          Instead of spacing_ft: wells per section, so spacing is 5,280 ft / wells_per_section (within spacing_ft's bounds).

        • offset_ftnumber or nullOptional

          Default 0≥ -10000, ≤ 10000

          Shifts the bench's lines across the azimuth, ft (+ to the right looking along it), to stagger benches; 0, null or absent is no shift.

          Lines pushed outside the area less setback_ft are dropped, not wrapped round, so a half-spacing stagger often holds one well fewer. A part with a non-zero offset isn't evened out, and in POST /plans' layouts no layout of the plan is, so a stagger set across layouts holds.

        • tvd_ftnumber or nullOptional

          > 0, < 40000

          True vertical depth in ft. Blank estimates it from the structure grid and nearby wells.

        • landing_below_top_ftnumber or nullOptional

          > -40000, < 40000

          Instead of tvd_ft: how far below the formation top to land, ft. TVD is the formation top at the well plus this, the top in the set's TVD datum as POST /tvd-estimates' formation_top_ft gives it; needs formation and a grid there. The top is averaged over the well's surface and bottom hole, whatever the set's subsurface_sampling (GET /model-sets).

        • landing_fractionnumber or nullOptional

          ≥ 0, ≤ 1

          Instead of tvd_ft or landing_below_top_ft: where to land as a fraction of the formation's thickness, 0 at its top to 1 at its base (0.5 the middle). TVD is top + landing_fraction × (base − top), to the foot.

          The top is the formation's structure grid: the set's own, else a TVD-only one in its depth pack. The base is the top of the next formation down the rock column with a grid at an end of the well (shl, bhl) the formation's own grid reaches.

          The rock column ranks the set's structure grids and its depth pack's TVD-only ones from the grids, not GET /formations order: at sample points spread over the grids' lattices, one lies below another when its top is a foot or more deeper at more of the points both reach than the reverse, or by median depth when they share none. Grids are ordered by how many others each lies below, less how many lie below it, ties by median depth. A grid with no value at any sample point is left out. Grids within a foot of each other wherever both reach are one surface: neither is the other's base, and both take the next surface below.

          Top and base are each averaged over the ends both grids reach, in the set's TVD datum as POST /tvd-estimates' formation_top_ft, and tvd_source names the base's formation. When the set's depth pack names a thickness grid, the base is the top plus that grid instead, and tvd_source names it. With a depth pack, a formation with no gridded formation below it at the well (as the deepest one) takes its base from its novi_thickness_avg grid.

          Needs formation. The well is refused as landing_below_top_ft is, naming landing_fraction, when:

          • its formation has no grid there or no place in the column;
          • no formation below it has a grid at an end its own grid reaches and, with a depth pack, it has no novi_thickness_avg grid there either (the error says when the grids reach different ends);
          • the base's top is a foot or more above the formation's at either end: the grids cross, the error names shl or bhl, and no deeper formation is tried;
          • top and base averaged over the ends are under a foot apart: the zone pinches out.

          A well's inputs echo it when it was sent.

        • fluid_bbl_per_ftnumber or nullOptional

          > 0, < 1000

          Fluid in bbl per lateral ft for the bench's wells: over the layout's, echoed as layer pad_formation. Needs one design, or none.

        • proppant_lb_per_ftnumber or nullOptional

          > 0, < 20000

          Proppant in lb per lateral ft for the bench's wells, as fluid_bbl_per_ft is set.

        • stage_length_ftnumber or nullOptional

          > 0, < 2000

          Stage length in ft.

          Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

        • clusters_per_stagenumber or nullOptional

          > 0, < 100

          Perforation clusters per stage; fractions are accepted.

          Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

        • frac_rate_bbl_per_minnumber or nullOptional

          > 0, < 500

          Frac pump rate in bbl per minute.

          Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

        • declineobjectOptional

          EUR settings for the bench's wells, as layer pad_formation; needs eur on.

          With eur off, a decline on any layer is a 400, even {} or one that reaches no well, though either sets nothing. POST /exports source turns eur on when it is left out.

          Each field takes the narrowest value set: the well's; its pad's or layout's, formations entry or bench first; its scenario's, formations entry first; the request's formations entry; the request's decline; Novi's defaults. The narrower layer wins first; within a layer, a stream's value beats the base: a well's b_max beats a plan's oil.b_max. Once a value reaches a well, every well's inputs.resolved.decline gives each value and its layer, and the export's wells table adds them.

          A well whose b_min resolves at or above its b_max is a 400 naming the well and both layers. The ARIES export refuses a scope whose wells differ. POST /gun-barrels and POST /economics forecast refuse a decline.

          Same fields as DeclineSettings.

      • formationstringOptional

        Target formation every laid-out well lands in (case-insensitive; GET /formations lists them). Required without benches; not with them.

      Show all 22 fields
      • tvd_ftnumber or nullOptional

        > 0, < 40000

        True vertical depth in ft. Blank estimates it from the structure grid and nearby wells.

      • landing_below_top_ftnumber or nullOptional

        > -40000, < 40000

        Instead of tvd_ft: how far below the formation top to land, ft. TVD is the formation top at the well plus this, the top in the set's TVD datum as POST /tvd-estimates' formation_top_ft gives it; needs formation and a grid there. The top is averaged over the well's surface and bottom hole, whatever the set's subsurface_sampling (GET /model-sets).

      • landing_fractionnumber or nullOptional

        ≥ 0, ≤ 1

        Instead of tvd_ft or landing_below_top_ft: where to land as a fraction of the formation's thickness, 0 at its top to 1 at its base (0.5 the middle). TVD is top + landing_fraction × (base − top), to the foot.

        The top is the formation's structure grid: the set's own, else a TVD-only one in its depth pack. The base is the top of the next formation down the rock column with a grid at an end of the well (shl, bhl) the formation's own grid reaches.

        The rock column ranks the set's structure grids and its depth pack's TVD-only ones from the grids, not GET /formations order: at sample points spread over the grids' lattices, one lies below another when its top is a foot or more deeper at more of the points both reach than the reverse, or by median depth when they share none. Grids are ordered by how many others each lies below, less how many lie below it, ties by median depth. A grid with no value at any sample point is left out. Grids within a foot of each other wherever both reach are one surface: neither is the other's base, and both take the next surface below.

        Top and base are each averaged over the ends both grids reach, in the set's TVD datum as POST /tvd-estimates' formation_top_ft, and tvd_source names the base's formation. When the set's depth pack names a thickness grid, the base is the top plus that grid instead, and tvd_source names it. With a depth pack, a formation with no gridded formation below it at the well (as the deepest one) takes its base from its novi_thickness_avg grid.

        Needs formation. The well is refused as landing_below_top_ft is, naming landing_fraction, when:

        • its formation has no grid there or no place in the column;
        • no formation below it has a grid at an end its own grid reaches and, with a depth pack, it has no novi_thickness_avg grid there either (the error says when the grids reach different ends);
        • the base's top is a foot or more above the formation's at either end: the grids cross, the error names shl or bhl, and no deeper formation is tried;
        • top and base averaged over the ends are under a foot apart: the zone pinches out.

        A well's inputs echo it when it was sent.

      • til_datestringOptional

        Format date

        TIL (turn-in-line, first production) date, YYYY-MM-DD: ip_day 1 is this day.

        From GET /dataset as_of to 30 years from today. Blank takes the next wider layer's date, the request's til_date last, else today. In spacing it orders parents and children (a well online at least 90 days before a neighbor is its parent, and the parent's days online count from it) and dates every spacing feature row.

      • fluid_bbl_per_ftnumber or nullOptional

        > 0, < 1000

        Fluid in bbl per lateral ft for the layout's wells: below a bench's and above a scenario's and the design's, echoed as layer pad. Works with benches. Needs one design, or none. A layout alone echoes no til_date or landing in inputs.resolved; completions here turn on its completion keys.

      • proppant_lb_per_ftnumber or nullOptional

        > 0, < 20000

        Proppant in lb per lateral ft for the layout's wells, as fluid_bbl_per_ft is set.

      • stage_length_ftnumber or nullOptional

        > 0, < 2000

        Stage length in ft.

        Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

      • clusters_per_stagenumber or nullOptional

        > 0, < 100

        Perforation clusters per stage; fractions are accepted.

        Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

      • frac_rate_bbl_per_minnumber or nullOptional

        > 0, < 500

        Frac pump rate in bbl per minute.

        Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

      • declineobjectOptional

        EUR settings for the layout's wells, as layer pad; needs eur on.

        With eur off, a decline on any layer is a 400, even {} or one that reaches no well, though either sets nothing. POST /exports source turns eur on when it is left out.

        Each field takes the narrowest value set: the well's; its pad's or layout's, formations entry or bench first; its scenario's, formations entry first; the request's formations entry; the request's decline; Novi's defaults. The narrower layer wins first; within a layer, a stream's value beats the base: a well's b_max beats a plan's oil.b_max. Once a value reaches a well, every well's inputs.resolved.decline gives each value and its layer, and the export's wells table adds them.

        A well whose b_min resolves at or above its b_max is a 400 naming the well and both layers. The ARIES export refuses a scope whose wells differ. POST /gun-barrels and POST /economics forecast refuse a decline.

        Same fields as DeclineSettings.

    • pdpbooleanOptional

      Default true

      Space against existing (PDP) wells; false spaces the wells against each other only.

    • til_datestringOptional

      Format date

      TIL date, YYYY-MM-DD, for every well no narrower layer dates, as POST /forecasts takes it.

  • deck_idstringOptional

    The deck to price with, one GET /economics/decks lists for the set; left out, the set's default deck (prototype-midland-flat; illustrative-haynesville-gas on a Haynesville set).

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

    Default "prototype"

    How NPV and payback are counted: prototype, yearly discounting (the app's default), or fe, monthly discounting, which matches Novi's earlier Forecast Engine.

    "prototype""fe"
  • deckobjectOptional

    Overrides of the deck's values for this request (every deck takes the same ranges); any left out keep the deck's.

    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.

  • includearray of stringsOptional

    up to 5 itemsunique items

    Extras to return. With flows, at most 500 wells across all scenarios (a forecast's wells × designs); 400 above that limit.

    "flows""scenario_flows""totals""summary""breakeven"

Responses

200 OK

One result per scenario, in request order.

  • 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"
  • scenariosarray of objectsRequired

    One per scenario, in request order (with forecast, one per design).

    ShowHide 9 child fields in each item
    • economicsobject or nullRequired

      The pad's economics, 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, or the pad's.

    • wellsarray of objectsRequired

      Each well, in request order.

      ShowHide 2 child fields in each item
      • reasonstring or nullRequired

        Why the well has no cash flow, or null.

      • flowsarray of numbers or nullOptional

        With include flows: its monthly cash flow, month 0 the capex, or null.

    • keystringOptional

      The scenario's key, when it sent one.

    • forecastobjectOptional

      With forecast: the design this scenario priced.

      ShowHide 1 child field
      • designintegerRequired

        ≥ 0

        The design priced: its index in the response's forecast.designs.

    • planobjectOptional

      The plan reference the scenario was priced from.

      ShowHide 4 child fields
      • idstringRequired

        Format uuid

        Plan id.

      • designintegerRequired

        The design priced.

      • wellsarray of integersRequired

        The plan wells priced, in order.

      • scenariostringOptional

        On a plan made with scenarios, the scenario priced.

    • flowsarray of numbers or nullOptional

      With include flows or scenario_flows: the pad's monthly cash flow, or null without one.

    • summaryobjectOptional

      With include summary: the scenario's totals. Wells that couldn't be priced still count in wells, total_lateral_ft and completions.

      ShowHide 5 child fields
      • wellsintegerRequired

        ≥ 1

        The scenario's wells.

      • pricedintegerRequired

        ≥ 0

        Wells with a cash flow.

      • total_lateral_ftnumberRequired

        Lateral summed over every well, ft, rounded to 1 ft.

      • eurobjectRequired

        EUR over the wells with an EUR on each of oil and gas the scenario's model set serves (both, on a set serving all three), priced or not.

        ShowHide 4 child fields
        • oilnumber or nullRequired

          Oil EUR summed, bbl, to 0.1; null when no well is summed or the set doesn't serve oil.

        • gasnumber or nullRequired

          Gas EUR summed, mcf, to 0.1; null when no well is summed or the set doesn't serve gas.

        • boenumber or nullRequired

          oil + gas / 6, BOE, to 0.1, an unserved stream counting 0; null when no well is summed.

        • wellsintegerRequired

          ≥ 0

          The wells summed: those with an EUR on each served stream of oil and gas.

      • completionsarray of objectsRequired

        Each distinct (formation, proppant, fluid) the wells were priced with, by formation (null last), then proppant, then fluid.

        ShowHide 4 child fields in each item
        • formationstring or nullRequired

          The wells' formation; null for wells sent in full (raw wells) and wells without one.

        • wellsintegerRequired

          ≥ 1

          Wells priced with it.

        • proppant_lb_per_ftnumberRequired

          Proppant, lb/ft.

        • fluid_bbl_per_ftnumberRequired

          Fluid, bbl/ft.

    • breakevenobject or nullOptional

      With include breakeven: the prices at which this scenario's npv is 0, every other deck value and override held, under the request's conventions; 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.

  • forecastobjectOptional

    With forecast: what was forecast; layout only when one was sent.

    ShowHide 4 child fields
    • pdpbooleanRequired

      Whether the wells spaced against existing wells.

    • wellsintegerRequired

      ≥ 1

      Wells forecast.

    • designsarray of objectsRequired

      The designs as run, one scenario each, in order.

      ShowHide 12 child fields in each item
      • indexintegerRequired

        ≥ 0

        Position in designs.

      • namestringRequired

        Name.

      • inputsobjectRequired

        As requested, blanks as null; the stage fields only where the set's models read them.

        ShowHide 5 child fields
        • fluid_bbl_per_ftnumber or nullRequired

          > 0, < 1000

          Completion fluid in bbl per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.

        • proppant_lb_per_ftnumber or nullRequired

          > 0, < 20000

          Proppant in lb per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.

        • stage_length_ftnumber or nullOptional

          > 0, < 2000

          Stage length in ft.

          Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

        • clusters_per_stagenumber or nullOptional

          > 0, < 100

          Perforation clusters per stage; fractions are accepted.

          Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

        • frac_rate_bbl_per_minnumber or nullOptional

          > 0, < 500

          Frac pump rate in bbl per minute.

          Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

      • fluid_bbl_per_ftnumberRequired

        Fluid used, bbl/ft.

      • proppant_lb_per_ftnumberRequired

        Proppant used, lb/ft.

      • completions_sourcestringRequired

        input when both were entered, otherwise how the defaults were made.

      • formationsarray of objectsRequired

        Every formation the request's wells or the design name; wells without a formation use the design's own values.

        ShowHide 9 child fields in each item
        • formationstringRequired

          Formation.

        • inputsobjectRequired

          As requested, blanks as null; the stage fields only where the set's models read them.

          ShowHide 5 child fields
          • fluid_bbl_per_ftnumber or nullRequired

            > 0, < 1000

            Completion fluid in bbl per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.

          • proppant_lb_per_ftnumber or nullRequired

            > 0, < 20000

            Proppant in lb per lateral ft. Blank uses the recent-completions median of the well's formation, else the play's.

          • stage_length_ftnumber or nullOptional

            > 0, < 2000

            Stage length in ft.

            Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

          • clusters_per_stagenumber or nullOptional

            > 0, < 100

            Perforation clusters per stage; fractions are accepted.

            Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

          • frac_rate_bbl_per_minnumber or nullOptional

            > 0, < 500

            Frac pump rate in bbl per minute.

            Read only on a model set whose models use it (GET /completions/defaults?include=inputs lists which); elsewhere it is accepted, changes nothing and is listed in the design's unused. It layers as fluid_bbl_per_ft does. A blank takes the median of the well's formation over the set's recent wells, else the play's; with neither, the request is a 400 naming the design's field.

        • fluid_bbl_per_ftnumberRequired

          Fluid used, bbl/ft.

        • proppant_lb_per_ftnumberRequired

          Proppant used, lb/ft.

        • completions_sourcestringRequired

          input when both were entered, otherwise how the defaults were made.

        • stage_length_ftnumberOptional

          Stage length used, ft: only on a model set whose models read it, and left out when nothing set it and the set's wells give no median.

        • clusters_per_stagenumberOptional

          Clusters per stage used: only on a model set whose models read it, and left out when nothing set it and the set's wells give no median.

        • frac_rate_bbl_per_minnumberOptional

          Frac rate used, bbl/min: only on a model set whose models read it, and left out when nothing set it and the set's wells give no median.

        • sourcesobjectOptional

          How each stage value used was found: input when the request set it, else the median's text.

          ShowHide 3 child fields
          • stage_length_ftstringOptional

            input, or how the default was made.

          • clusters_per_stagestringOptional

            input, or how the default was made.

          • frac_rate_bbl_per_minstringOptional

            input, or how the default was made.

      • stage_length_ftnumberOptional

        Stage length used, ft: only on a model set whose models read it, and left out when nothing set it and the set's wells give no median.

      • clusters_per_stagenumberOptional

        Clusters per stage used: only on a model set whose models read it, and left out when nothing set it and the set's wells give no median.

      • frac_rate_bbl_per_minnumberOptional

        Frac rate used, bbl/min: only on a model set whose models read it, and left out when nothing set it and the set's wells give no median.

      • sourcesobjectOptional

        How each stage value used was found: input when the request set it, else the median's text.

        ShowHide 3 child fields
        • stage_length_ftstringOptional

          input, or how the default was made.

        • clusters_per_stagestringOptional

          input, or how the default was made.

        • frac_rate_bbl_per_minstringOptional

          input, or how the default was made.

      • unusedarray of stringsOptional

        The stage fields the request sent, on the design or any narrower layer, that the model set's models don't read, so nothing used them; only when there is one.

        "stage_length_ft""clusters_per_stage""frac_rate_bbl_per_min"
    • layoutobjectOptional

      What a layout laid out: POST /layouts/fill's answer without its wells, and the formation; with wells_per_pad or benches, pads and each bench's wells as well indexes.

      ShowHide 14 child fields
      • countintegerRequired

        Wells.

      • azimuth_degnumberRequired

        Azimuth used.

      • lateral_length_ftnumber or nullRequired

        Length used, or null for edge to edge.

      • spacing_ftnumberOptional

        Spacing used; left out with benches.

      • setback_ftnumberOptional

        Setback used, ft; only when the request sent one.

      • setback_end_ftnumberOptional

        End setback used, ft; only when sent.

      • min_lateral_ftnumberOptional

        Shortest well used, ft; only when sent. No returned well is shorter: split pieces shorter than it are left out.

      • standoff_ftnumberOptional

        Standoff used, ft; only when sent.

      • standoff_wellsintegerOptional

        ≥ 0

        With standoff_ft: how many existing laterals POST /wells/search finds within standoff_ft of the unit (match lateral, in the wells' formations). The fill also clears laterals just past standoff_ft by that measure.

      • wells_per_padintegerOptional

        Wells per pad; only when sent.

      • wells_per_sectionnumberOptional

        With benches: their wells_per_section added up, the unit's total.

      • padsarray of arraysOptional

        With wells_per_pad: each pad's wells, as indexes of the response's (or plan's) wells.

      • benchesarray of objectsOptional

        With benches: each bench as laid out.

        ShowHide 6 child fields in each item
        • spacing_ftnumberRequired

          Spacing used, ft.

        • wells_per_sectionnumberRequired

          5,280 ft / spacing_ft, or as sent.

        • offset_ftnumberRequired

          Offset used, ft.

        • formationstring or nullRequired

          The bench's formation, or null when none was sent.

        • countintegerRequired

          ≥ 0

          Wells in the bench.

        • wellsarray of integersRequired

          Items ≥ 0

          The bench's wells, as indexes of the response's (or plan's) wells.

      • formationstringOptional

        The formation every well landed in, as GET /formations names it; left out with benches, which name their own.

  • totalsobjectOptional

    With include totals: sums over the priced scenarios.

    ShowHide 6 child fields
    • scenariosintegerRequired

      ≥ 1

      Scenarios in the request.

    • pricedintegerRequired

      ≥ 0

      Scenarios with economics.

    • wellsintegerRequired

      ≥ 0

      Wells in the priced scenarios.

    • npvnumber or nullRequired

      NPV summed over the priced scenarios, $; null when none is priced.

    • capexnumber or nullRequired

      Capex summed over the priced scenarios, $; null when none is priced.

    • flowsarray of numbers or nullOptional

      With include flows or scenario_flows: the priced scenarios' monthly cash flows summed month by month from month 0, all online together; null when none is priced.

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.

502

A model worker returned an error.

Shared errors400401403500503What they mean