Skip to content
Developers
Get an API token

Get a plan's economics job

A plan economics job: its status, then result (the plan priced) or error.

Get a plan's economics job

GET/plans/{id}/economics/{job_id}

A plan economics job: its status, then result (the plan priced) or error. Running, it answers with Retry-After: 1: send wait instead of polling. Done or failed, it carries an ETag for If-None-Match (304). 404 for an unknown or expired id, another tenant's job, or one of another plan or model set.

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

Parameters

Path parameters

Query parameters

  • waitintegerOptional

    ≥ 1, ≤ 25

    Use this instead of polling: on a running job, the answer is held until it finishes, or this many seconds pass.

    Whole seconds, 1 to 25 (400 otherwise). The answer is what a GET without wait would get when the wait ends, Retry-After included; a finished job answers at once. A client that disconnects ends the wait.

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

Responses

200 OK

The job.

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

Conditional requests 304 Unchanged since the ETag in If-None-Match.

Errors

StatusWhen
404

No such well, grid, plan or route.

Shared errors400401403500503What they mean