Skip to content
Developers
Get an API token

Start a plan

Starts a development plan as a background job and answers 202 with its Location.

Start a plan

POST/plans

Starts a development plan as a background job and answers 202 with its Location. A plan runs up to GET /dataset limits.plan_wells forecasts (wells × completion designs): 10,000 by default, so 5,000 wells with two designs.

Send a Novi API token as a bearer token on every request. Authentication
What you send

wells, a layout the server lays out, or up to 100 layouts, their wells one after another (each echoed in layouts with first, its first well's plan index). from_plan runs a done plan's request again on the set's current models; assumption_set fills fields the body leaves out. The body may be up to 64 MB.

Waiting

GET /plans/{id}?wait=25 until status is done or error; each answer waits for the status to change. With an Idempotency-Key, a retry returns the plan the first request started.

Options

Each is described on its field.

  • eur: true adds an eur step: every forecast carries eur, totals add each stream's EUR sum and count, and the export's forecast.csv adds EUR columns.
  • bands: true gives every forecast its P10/P90 bands, summed in totals; with band_eur: true, totals add p10 and p90 EUR.
  • With TIL dates (til_date on a well, pad, layout, scenario or the plan), wells space as parents and children in date order, and totals add by_date, each stream by calendar month.
  • per_well_errors: true fails a well that can't be placed on its own.
  • dry_run: true checks and counts the plan (PlanDryRun) without starting it. Wells aren't placed until a plan runs; POST /tvd-estimates gives the TVD a plan would estimate.
Scenarios

With a scenario on every well, or on every layout, up to 20 alternatives run in one plan, each scenario's wells spacing against only each other and existing wells. totals come per scenario and design, GET /plans/{id}/stats takes group_by=scenario or scenario, an export or economics reference takes one scenario at a time, and GET /plans/{id}/export answers 409.

Depletion chain

A dated plan chains depletion by default where GET /dataset depletion_chain.available is true: a planned well's P50 feeds the neighbor-production features of the later-month plan wells it is a parent of, and the plan echoes depletion_chain. See depletion_chain.

Chunks and queue

Wells run in spatial chunks of about 1,000, each with the plan wells within the spacing radius around it. Plans queue, oldest first, for a server task with room: a task runs at most 80,000 forecasts in plans at once, or limits.plan_wells + 10,000 where that is more. A queued plan reads running, with progress, done and every steps count 0, until a task takes it; a create never answers 409 for server load.

Limits

limits.plan_wells is at most 100,000. Once a caller has a plan queued or running, a new plan that would take their unfinished forecasts (wells × designs, across model sets) past GET /dataset limits.plan_unfinished_forecasts answers 429 with Retry-After; a caller with nothing unfinished is always accepted. The caller is the request's user, or the server without sign-in. Plans being deleted don't count, and a dry run is never refused.

Server tasks

Where a plan runs and is kept.

  • With a state store and Redis, any task takes queued plans and answers GET, wait, PATCH and DELETE for any plan. A DELETE stops a plan running on another task after its chunks in flight.
  • A plan running on another task answers GET with its progress; with include=wells it lists no wells until done (with Retry-After: 1), and a sort is a 409 until then.
  • A plan with callback_url runs on the task that took it, and may start before older queued plans.
  • With a state store, a finished plan is read back from the store. Without one, plans don't survive a restart (GET /health uptime_s starts from 0): keep a deadline and create the plan again on a 404.
Callbacks

With callback_url, the server POSTs {"type": "plan.done" | "plan.failed", "plan": <the plan, as GET /plans/{id} returns it without include, less callbacks>} once the plan is done or fails; a plan deleted while running sends nothing.

  • It goes as an export's callback does (POST /exports): the same host allowlist (GET /export-formats callbacks, whose events list only export events; 400 while callbacks are off), https and public addresses only.
  • 3 retries after 2 s, 15 s and 60 s, with the same X-Export-Event, X-Export-Delivery and X-Export-Signature headers, plus X-Plan-Id.
  • A plan takes one URL; its callbacks shows the delivery, the URL as its origin.
  • The payload has the totals but no wells: page them with GET /plans/{id}?include=wells, or export the plan with a callback_url of its own and download it within the export's time to live.
Retention

With a state store, an unsaved plan is kept for the server's scratch period after it is made (90 days unless the server sets another; storage.expires_at says when) and deleted within a minute of expires_at; a saved plan is kept until deleted. Saving clears expires_at; unsaving starts a new scratch period. A deleted plan is gone from the API at once, its shares revoked and its attached documents deleted.

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.

Header parameters

  • Idempotency-KeystringOptional

    pattern ^[A-Za-z0-9._:-]{1,128}$

    Makes a retry safe: send your own key (a UUID, or your request id) and the same key on every retry. Without the header, nothing changes.

    The same key and body (compared as JSON, key order ignored) within 24 hours replays what the first request made, with its id, in its current state, with Idempotent-Replayed: true, and starts nothing. A different body is a 409 (details.field Idempotency-Key).

    • Keys are per operation, and only a success records one: retry a 502, 503, 504 or a lost response with the same key.
    • With Redis, POST /saved/{collection}, /forecast-sources and /area-sets keep keys there, as do POST /plans and /exports on a server with a state store: every server task shares them and a restart keeps them. While Redis isn't answering, these answer 503.
      • A retry while the first request is still being made waits up to 30 s for it, then answers 409: retry shortly with the same key.
      • A key the first request hasn't recorded within a minute (its task stopped, or Redis failed as it finished) lapses; a retry then makes the resource again.
    • Otherwise keys live in the server process's memory, the latest 1,000 per operation: a restart (a deploy is one) forgets them, and a retry during the first request waits for it.
    • POST /forecasts with async: true and POST /plans/{id}/economics keep each key with its job, as their descriptions say. A POST /plans with dry_run: true neither keeps nor replays its key.
    • A replay of a plan or export the server has dropped is a 404.

Request bodyRequired

application/json

Plan wells, a layout or layouts, and options.

  • wellsarray of objectsOptional

    1 to 100000 items

    Plan wells (required unless layout or layouts is sent); up to the server's GET /dataset limits.plan_wells (10,000 by default, at most 100,000) divided by the number of designs.

    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 the plan's wells out in, up to GET /dataset limits.plan_wells divided by the number of designs and at most 10,000, a fill's own limit.

    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.

  • layoutsarray of objectsOptional

    1 to 100 items

    Instead of wells or layout: layouts whose wells the plan takes one after another, up to GET /dataset limits.plan_wells divided by the number of designs in all, each at most 10,000 (a fill's own limit).

    • All layouts share one work limit (about a second). Each evens out as POST /layouts/fill does, with the work the plan's fills leave, unless any layout has a bench with a non-zero offset_ft: then none does, so a stagger set across layouts holds.
    • Errors name layouts[i]. Past the plan's wells in all: a 400 on layouts[i] with details.max (the plan's wells), details.before (wells the layouts before it laid out) and details.count (its own).
    ShowHide 23 child fields in each item

    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).

      Same fields as UnitArea.

    • 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 23 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.

    • scenariostringOptional

      1 to 60 characters

      Every one of the layout's wells' scenario: send one on every layout, or on none. Layouts may share one, a development across units.

  • designsarray of objectsOptional

    1 to 10 items

    Completion designs; every well is forecast with each. Leave out for one design at the recent-completions median. A well's own completions, a scenario's and a pad's or layout's need one design.

    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.

  • scenariosarray of objectsOptional

    1 to 20 items

    Values for each scenario's wells, keyed by the scenario the wells name; a scenario without an entry takes the request's values.

    A well's own completions, til_date and landing beat its scenario's, as do its pad's and its layout's or bench's. A scenario's completions beat the design's, and its til_date and pdp the request's. Once an entry sets completions, every well's inputs.resolved gives them. Once one sets a TIL date or landing that a well takes, inputs.resolved gives each well's til_date and landing, and the export's wells table adds til_date, til_layer and landing_layer.

    A 400 naming the entry refuses a name no well has, a repeated name, scenarios when no well has a scenario, and completions in it under more than one design.

    ShowHide 10 child fields in each item
    • namestringRequired

      1 to 60 characters

      The scenario these values are for: exactly a name on the request's wells or layouts, trimmed, at most 60 characters, each once.

    • fluid_bbl_per_ftnumber or nullOptional

      > 0, < 1000

      Fluid in bbl per lateral ft for the scenario's wells: below a well's own, its pad's and a formations entry here, above the design's values. Needs one design, or none.

    • proppant_lb_per_ftnumber or nullOptional

      > 0, < 20000

      Proppant in lb per lateral ft for the scenario'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.

    • til_datestring or nullOptional

      Format date

      TIL date for the scenario's wells without their own or their pad's or layout's, over the request's til_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.

    • pdpboolean or nullOptional

      Whether this scenario's wells space against existing (PDP) wells, over the request's pdp, so scenarios in one request can differ.

    • declineobjectOptional

      EUR settings for the scenario's wells; 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.

    • formationsarray of objectsOptional

      up to 100 items

      Values for the scenario's wells in one formation, each formation at most once. The only place a scenario sets landing.

      ShowHide 10 child fields in each item
      • formationstringRequired

        Formation (case-insensitive; GET /formations lists them).

      • fluid_bbl_per_ftnumber or nullOptional

        > 0, < 1000

        Fluid in bbl per lateral ft for this formation's wells in the scenario or pad, over the entry's own. Needs one design, or none.

      • proppant_lb_per_ftnumber or nullOptional

        > 0, < 20000

        Proppant in lb per lateral ft, 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.

      • tvd_ftnumber or nullOptional

        > 0, < 40000

        True vertical depth in ft. Landing falls through as one unit: a well, or a narrower layer, that sets any of tvd_ft, landing_below_top_ft or landing_fraction keeps its own, so this reaches only wells that set none.

      • landing_below_top_ftnumber or nullOptional

        > -40000, < 40000

        Instead of tvd_ft: ft below the formation top, as on a well.

      • landing_fractionnumber or nullOptional

        ≥ 0, ≤ 1

        Instead of tvd_ft or landing_below_top_ft: 0 at the formation top to 1 at its base, as on a well.

      • declineobjectOptional

        EUR settings for this formation's wells in the scenario or 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.

  • padsarray of objectsOptional

    at least 1 items

    Values for each pad's wells, keyed by the pad the wells name; a well on no listed pad takes the layers below. An entry may hold only pad and name.

    A well's own completions, til_date and landing beat its pad's, an entry's formations beat its own values, and a pad beats its wells' scenarios. Once an entry sets completions, every well's inputs.resolved gives them. Once one sets a TIL date or landing that a well takes, inputs.resolved gives each well's til_date and landing, and the export's wells table adds til_date, til_layer and landing_layer.

    A 400 naming the field refuses:

    • a pad no well has, or a repeat (1 and "1" are one pad);
    • a bad pad on any well;
    • over 200,000 formations entries across the list;
    • pads with layout or layouts, whose own fields set their wells;
    • a well with no formation that takes landing_below_top_ft or landing_fraction from an entry's own values;
    • completions in it under more than one design.
    ShowHide 13 child fields in each item
    • padinteger or stringRequired

      1 to 60 characters

      The pad these values are for: an integer or text as the wells name it, trimmed, at most 60 characters, each once; 1 and "1" are one pad.

    • namestring or nullOptional

      up to 60 characters

      The pad's name, 1 to 60 characters once trimmed; null is none, and a blank name is a 400. Names needn't be unique: the key still groups and orders pads, pairs them in comparisons and filters with pad=.

      POST /plans keeps it: the economics export's pad column writes it instead of the key on well and pad rows, GET /plans/{id}/stats?group_by=pad gives it as groups[].name, GET /plans/{id}/rollup as pads[].name, and the type curve, plan economics and comparisons by pad give it beside the key. POST /forecasts and POST /exports source check it but don't use it.

    • fluid_bbl_per_ftnumber or nullOptional

      > 0, < 1000

      Fluid in bbl per lateral ft for the pad's wells: below a well's own and a formations entry here, above a scenario's and the design's. Needs one design, or none.

    • proppant_lb_per_ftnumber or nullOptional

      > 0, < 20000

      Proppant in lb per lateral ft for the pad'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.

    • til_datestring or nullOptional

      Format date

      TIL date for the pad's wells without their own, over a scenario's and the request's til_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.

    • tvd_ftnumber or nullOptional

      > 0, < 40000

      True vertical depth in ft for the pad's wells. Landing falls through as one unit, so a well, or a formations entry here, that sets any landing field keeps it.

    • landing_below_top_ftnumber or nullOptional

      > -40000, < 40000

      Instead of tvd_ft: ft below the top of each well's own formation; a well that takes it needs one.

    • landing_fractionnumber or nullOptional

      ≥ 0, ≤ 1

      Instead of tvd_ft or landing_below_top_ft: 0 at the top of each well's own formation to 1 at its base; a well that takes it needs one.

    • declineobjectOptional

      EUR settings for the pad's wells; 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.

    • formationsarray of objectsOptional

      up to 100 items

      Values for the pad's wells in one formation, each formation at most once.

      Same fields as ScenarioFormationInput.

  • formationsarray of objectsOptional

    up to 100 items

    The request's landing per formation, each formation at most once; a landing on the well, its pad, layout, bench or scenario entry beats it. Goes with wells, layout or layouts.

    An entry for a formation no well has is accepted. Completions per formation stay in designs. Once an entry sets a landing that a well takes, inputs.resolved gives each well's til_date and landing, and the export's wells table adds til_date, til_layer and landing_layer.

    ShowHide 5 child fields in each item
    • formationstringRequired

      Formation (case-insensitive; GET /formations lists them).

    • tvd_ftnumber or nullOptional

      > 0, < 40000

      True vertical depth in ft for the request's wells in this formation that no narrower layer lands.

    • landing_below_top_ftnumber or nullOptional

      > -40000, < 40000

      Instead of tvd_ft: ft below the formation top, as on a well.

    • landing_fractionnumber or nullOptional

      ≥ 0, ≤ 1

      Instead of tvd_ft or landing_below_top_ft: 0 at the formation top to 1 at its base, as on a well.

    • declineobjectOptional

      EUR settings for the request's wells in this 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.

  • pdpbooleanOptional

    Default true

    Space against existing (PDP) wells. A scenario's pdp in scenarios beats it, and this stays the plan's echoed pdp.

  • namestring or nullOptional

    up to 100 characters

    Your name for the plan.

  • eurbooleanOptional

    Default false

    Add the EUR (Novi type-curve decline fit) to each oil and gas forecast; GET /dataset eur says whether this server has it (503 if not).

  • eur_waterbooleanOptional

    Default false

    Fit water's EUR too, with decline.water over the settings at any layer.

    Adds eur to each water forecast, water to the decline echo, totals[].eur and inputs.resolved.decline, and water's columns to the eur, forecast and wells tables, where monthly water runs to the EUR day. BOE never reads it, and oil's and gas's fits are unchanged. Without it, decline.water is a 400. Needs eur: true (a 400 on eur_water without it).

  • declineobjectOptional

    Decline fit settings, with eur: true only; any left out take Novi's defaults (GET /dataset eur.defaults), and oil and gas (with eur_water, water) override them per stream. The plan layer: a well, pad, layout, bench, scenario or formations entry can set its wells' own, field by field.

    Same fields as DeclineSettings.

Show all 21 fields
  • til_datestringOptional

    Format date

    TIL (first production) date, YYYY-MM-DD, for every well no narrower layer dates: from GET /dataset as_of to 30 years from today. Echoed in each such well's inputs.

  • bandsbooleanOptional

    Default false

    Add P10/P90 bands to each stream forecast (Novi's predrill bands, same model call); GET /dataset bands says which streams have them, and a request answers 503 when none has.

  • band_eurbooleanOptional

    Default false

    Also fit each oil and gas band to an EUR with the decline settings, and water's with eur_water: two more decline fits per such forecast (about three times eur's fitting). Needs bands and eur.

  • callback_urlstring or nullOptional

    up to 2048 characters

    Where to POST the plan once it is done or fails: https, to a host the server allows (GET /export-formats callbacks). See POST /plans.

  • depletion_chainbooleanOptional

    Feed each planned well's P50 production to the plan wells it is a parent of, those with a later TIL month. On by default where GET /dataset depletion_chain.available is true, else off. Only plans take it.

    • A well whose planned parent is TIL in an earlier calendar month is re-forecast after it, wave by wave, each design on its own parents' P50. A parent read past its 1,080-day forecast is extended with the plan's decline settings (Novi's defaults without eur).
    • Existing (PDP) parents' production is as GET /dataset depletion_chain.neighbor_production says.
    • false: a planned parent's production reads as 0 in every neighbor-production feature (novi_spacing_sum_prior_* and novi_spacing_delgados_p*), so neighbor production is existing wells' history alone.
    • With available false, the plan runs as without it, and with true sent its echo says why.
    • Each wave adds a production pass and a forecast per design, so deep chains take longer. steps.chain counts the waves' passes running, and a chained well finishes once its last design's wave lands.
  • dry_runbooleanOptional

    Default false

    With true, only check and count: the same checks as a create and a 200 with PlanDryRun, with nothing started (no job, no callback). false or absent: a plan.

    An Idempotency-Key is neither kept nor replayed. Wells aren't placed, so a well whose TVD can't be estimated or whose landing can't be placed answers 200 here and fails once the plan runs (only that well with per_well_errors: true, unless no well can be placed).

  • per_well_errorsbooleanOptional

    Default false

    With true, a well whose TVD or landing can't be placed fails alone; the plan ends in error only when no well can be placed. Without it, one placement failure fails the whole plan.

    • The plan lists failed_wells. The well's summary has error {field, message}, error forecasts and no estimates or spacing; reading it or its explanations is a 409. Stats count it as missing; exports keep its reason with blank placement columns.
    • Its plan neighbors are spaced and forecast without it, as if it were never drilled: less interference, so their forecasts may read high.
    • For the like-for-like plan, run the wells again with this one placed: tvd_ft for its landing_fraction or landing_below_top_ft, and a target formation if it has none (a plan built from a layout goes as its well list, so only this well changes).
    • Economics leaves any scenario holding it unpriced (economics null, reason naming the first well without flows); list the placed wells in plan.wells to price them.
    • Worker or internal errors still fail the plan.
  • from_planstringOptional

    Format uuid

    Instead of wells, layout or layouts: a done plan's id. The new plan runs its stored request again on the model set's current models, and echoes from_plan.

    • It keeps the wells where they were (a layout's aren't laid out again), designs, pdp, decline and EUR settings, bands, depletion chain, per_well_errors and its start day, which undated wells take.
    • Only name, callback_url and dry_run go with it; any other field is a 400 naming it. A plan you can't see on this model set is 404; one running or failed is 409.
    • POST /comparisons of the two names the release and model set each ran on, so a difference comes from the models or the release, not the inputs.
  • assumption_setobjectOptional

    A saved assumption set: each plan field it holds that this body leaves out or sends as null is filled from it before the body is checked, unless clear names it; a field the body sends wins.

    • It fills designs, formations, til_date, pdp, depletion_chain, eur, eur_water, decline, bands and band_eur, never its pad_template or economics (not plan fields). A 400 on a filled field names it and starts "From assumption set {name} (version {n}):".
    • A set you can't read is 404; one made on another model set, a 400 on assumption_set naming both; without a state store, 409; with from_plan, 400.
    • The plan echoes assumption_set with the version run and the fields filled; GET /plans/{id}?include=request answers the body after the fill.
    • Without one, a plan runs on the dataset's defaults (Novi defaults) and has no assumption_set echo.
    ShowHide 3 child fields
    • idstringRequired

      Format uuid

      An assumption set's id, from POST /saved/assumption-sets.

    • versionintegerOptional

      ≥ 1

      The version you read; another one is a 409 whose details.version is the current one. Left out, the current version.

    • cleararray of strings or nullOptional

      Set values the fill skips: til_date, eur or both. Absent, null or []: the set fills as without it.

      • til_date: the set's start date, so wells this body doesn't date run undated.
      • eur: the set's eur, eur_water, decline and band_eur, and each filled formations entry's decline, so the plan runs without EUR; bands and those entries' landings still fill.
      • A field this body sends still wins: a til_date sent beside it runs on that date, and "eur": true runs EUR on this body's own settings.
      • A name the set doesn't hold is ignored, so you needn't read the set first; a name may repeat. Any other value is a 400 on assumption_set.clear.
      • assumption_set.filled leaves out what the set didn't fill.
      "til_date""eur"

Responses

With dry_run: true: the plan a create would start, counted; nothing was started.

  • dry_runanyRequired

    Always true

    Always true: nothing was started.

  • wellsintegerRequired

    ≥ 1

    Wells the plan would have: wells as sent, or laid out from layout or layouts.

  • designsintegerRequired

    ≥ 1

    Completion designs the plan would run, one when none is sent.

  • forecastsintegerRequired

    ≥ 1

    wells × designs, what GET /dataset limits.plan_wells caps.

  • scenariosarray of objectsOptional

    When the request sent scenarios: each, in the order its first well came, with its well count.

    ShowHide 3 child fields in each item
    • namestringRequired

      The scenario.

    • wellsintegerRequired

      ≥ 1

      Its wells.

    • pdpbooleanOptional

      The scenario's own pdp; only when scenarios set one. Without it the scenario ran with the request's pdp.

  • layoutobjectOptional

    When the request sent layout: what it would lay out, as the plan would echo it.

    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.

  • layoutsarray of objectsOptional

    When the request sent layouts: what each would lay out, in order, as the plan would echo them.

    ShowHide 16 child fields in each item
    • firstintegerRequired

      ≥ 0

      The plan index of the layout's first well; its wells follow in order.

    • countintegerRequired

      Wells.

    • azimuth_degnumberRequired

      Azimuth used.

    • lateral_length_ftnumber or nullRequired

      Length used, or null for edge to edge.

    • scenariostringOptional

      When the layout was sent with one: its scenario.

    • 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.

    Show all 16 fields
    • 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.

  • assumption_setobjectOptional

    When the request sent assumption_set: the set, as the plan would echo it.

    ShowHide 4 child fields
    • idstringRequired

      Format uuid

      The set's id.

    • versionintegerRequired

      ≥ 1

      The version the plan ran with.

    • namestringRequired

      The set's name then.

    • filledarray of stringsRequired

      The request fields the set filled, in the set's key order. A value they set reads in each well's resolved inputs as the field it filled (plan or plan_formation).

Errors

StatusWhen
404

No such well, grid, plan or route.

409

The Idempotency-Key was already used with a different body; or, with Redis, the first request with this Idempotency-Key is still being made (after a 30 s wait); retry shortly with the same key; or from_plan names a plan still running, or failed.

413

The request body is over 64 MB.

429

The caller already has plans queued or running, and this one would take their unfinished forecasts past GET /dataset limits.plan_unfinished_forecasts; details has limit, unfinished, plans and, when the body was read, requested. Wait for one to finish or delete one.

503

A model worker or the subsurface grids aren't ready, or, with Redis, the Redis that keeps Idempotency-Key records isn't answering; retry shortly with the same key.

Shared errors400401403500What they mean