Skip to content
Developers
Get an API token

Price a whole plan in the background

Prices every well of a done plan under one design (and, on a scenario plan, one scenario) in the background, as POST /economics prices a plan well: one call for thousands of wells, and no client sums.

Price a whole plan in the background

POST/plans/{id}/economics

Prices every well of a done plan under one design (and, on a scenario plan, one scenario) in the background, as POST /economics prices a plan well: one call for thousands of wells, and no client sums.

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

It answers 202 with a PlanEconomicsJob and its Location; GET /plans/{id}/economics/{job_id}?wait=25 until status is done or error. Jobs belong to the request tenant. An Idempotency-Key replays the first job for the same plan and body.

Totals

totals and each group sum their priced wells' monthly cash flows as if every well came online together, then take NPV, IRR and payback of that sum, so the pads' npv and capex add up to the totals'. An unpriced well counts in wells, not priced; the first (by plan index) names the reason. A group's economics are null only when none of its wells is priced (POST /economics instead gives a scenario with any unpriced well none).

Groups

No group is folded.

  • group_by: ["pad"]: pad keys in plan order of each pad's first well, wells without a pad last as key: null. A plan whose wells name no pad is a 400: send wells[].pad on POST /plans.
  • group_by: ["formation"]: GET /formations order, wells without one last.
  • include: ["wells"] adds a row per well in plan order; "breakeven", each group's and the totals' flat oil and gas breakeven prices, as POST /economics finds them.
Limits

At most 4 jobs run at once per tenant, across model sets and server tasks; the next is a 409 with Retry-After: 1. A job still pricing 10 minutes after it was posted, its wait for a server included, fails (unavailable): price one scenario or fewer groups. One no server took fails a minute later. Jobs are kept an hour after they finish, in Redis (shared by every server task) or the server's memory; with Redis, a job whose server stops runs again on another.

Errors

The plan's 409s come first (running, failed, or made without eur: true), then design, scenario, group_by, include, conventions, deck_id and deck, in that order; design, scenario, conventions and the deck are checked as POST /economics checks them.

Parameters

Path 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 bodyOptional

application/json

What to price, and how to group it.

  • designintegerOptional

    Default 0≥ 0, ≤ 9

    The plan design priced, its index from 0.

  • scenariostringOptional

    1 to 60 characters

    On a plan made with scenarios, the one to price: required there (a 400 lists them), and a 400 on a plan without scenarios. A job prices one development; price each scenario in its own job.

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

  • 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"
  • group_byarray of stringsOptional

    unique items

    Groups to sum, each once. Absent: totals only.

    "pad""formation"
  • includearray of stringsOptional

    unique items

    Optional parts, each once.

    "wells""breakeven"

Responses

202 Accepted

The job, running (or, replaying an Idempotency-Key, as it is now).

  • idstringRequired

    Format uuid

    Job id.

  • plan_idstringRequired

    Format uuid

    The plan priced.

  • statusstringRequired

    running, then done or error.

    "running""done""error"
  • created_atstringRequired

    Format date-time

    When it was requested.

  • finished_atstring or nullRequired

    Format date-time

    When it finished or failed.

  • secondsnumberRequired

    Run time so far, or in total once finished.

  • resultobject or nullRequired

    Once done, the plan priced; null otherwise.

    ShowHide 8 child fields
    • plan_idstringRequired

      Format uuid

      The plan.

    • designintegerRequired

      ≥ 0

      The design priced.

    • scenariostring or nullRequired

      The scenario priced; null on a plan without scenarios.

    • 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"
    • totalsobjectRequired

      The priced wells of a plan, a pad or a landing zone, summed month by month as if all came online together.

      ShowHide 10 child fields
      • wellsintegerRequired

        ≥ 0

        Wells in it.

      • pricedintegerRequired

        ≥ 0

        Wells with a cash flow, summed.

      • capexnumber or nullRequired

        Capex of the priced wells, $, all at month 0; null when none is priced.

      • npvnumber or nullRequired

        NPV of the summed cash flow, $, at the deck discount_rate, as conventions says; null when none is priced.

      • irr_pctnumber or nullRequired

        IRR of the summed cash flow, % a year; null when it never returns its capex or none is priced.

      • payback_monthsnumber or nullRequired

        Payback of the summed cash flow, months; null when it never pays back or none is priced.

      • reasonstring or nullRequired

        The first unpriced well (by plan index) and why, as POST /economics names it; null when every well is priced.

      • keystring or nullOptional

        On a group: the pad key or formation; null for the wells without one. Absent on totals.

      • namestringOptional

        On a pad group, the pad's name when the plan gives one in pads[].name; absent otherwise, and on totals and formation groups. key stays the pad key.

      • breakevenobject or nullOptional

        With include breakeven: the flat oil and gas prices at which npv is 0, over the priced wells; null when none is priced.

        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.

    • groupsobjectOptional

      With group_by: the groups asked for.

      ShowHide 2 child fields
      • padarray of objectsOptional

        With group_by pad: each pad key in plan order of its first well, no pad last; never folded.

        Same fields as EconomicsRollup.

      • formationarray of objectsOptional

        With group_by formation: each formation in GET /formations order, none last.

        Same fields as EconomicsRollup.

    • wellsarray of objectsOptional

      With include wells: every well priced, in plan order.

      ShowHide 10 child fields in each item
      • indexintegerRequired

        ≥ 0

        The well's plan index.

      • labelstringRequired

        The well's name, else Plan well N.

      • padstring or nullRequired

        Its pad key; null without one.

      • formationstring or nullRequired

        Its target formation; null without one.

      • capexnumber or nullRequired

        Capex, $; null when unpriced.

      • npvnumber or nullRequired

        NPV, $; null when unpriced.

      • irr_pctnumber or nullRequired

        IRR, % a year; null when unpriced or it never returns its capex.

      • payback_monthsnumber or nullRequired

        Payback, months; null when unpriced or it never pays back.

      • reasonstring or nullRequired

        Why it has no cash flow, or null.

      • pad_namestringOptional

        The pad's name when the plan gives one in pads[].name; absent otherwise. pad stays the key.

  • errorobject or nullRequired

    Once failed, why; null otherwise.

    ShowHide 3 child fields
    • codestringRequired

      Machine-readable code.

      "invalid_argument""not_found""conflict""unavailable""internal"
    • messagestringRequired

      What went wrong and how to fix it.

    • detailsobjectRequired

      Context: field names the input at fault, as wells[3].tvd_ft.

      ShowHide 1 child field
      • fieldstringOptional

        The input at fault.

  • linksobjectRequired

    Related URLs.

    ShowHide 1 child field
    • selfstringRequired

      This job.

Errors

StatusWhen
404

No such well, grid, plan or route.

409

The plan is running, failed or was made without eur: true; the Idempotency-Key was already used with a different body; or 4 plan economics jobs are already running for the tenant (with Retry-After: 1).

413

The request body is over 10 MB.

Shared errors400401403500503What they mean