Skip to content
Developers
Get an API token

Get a well

A well's header: operator, location, formation, lateral, TVD, completions, dates and cumulative production.

Get a well

GET/wells/{key}

A well's header: operator, location, formation, lateral, TVD, completions, dates and cumulative production. Send fields to skip the header fields you don't need, and include=floors to learn which values may start at the dataset's first production month rather than at the well's own start.

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

Parameters

Path parameters

  • keystringRequired

    Wellbore key, as SB329-01414. GET /wells/facets, /wells/search, /wells/typecurve and /wells/production are paths, not wells: keys are API numbers or SBnnn-nnnnn, so no well is shadowed.

Query parameters

  • fieldsstringOptional

    Only these fields, comma-separated; absent or empty, every field. wellbore_key is always kept, and the response keeps its own key order.

    Allowed: any of the well's header fields listed below.

    Header fields: wellbore_key, well_name, operator, basin, subbasin, state, county, formation, lateral_length, tvd_td, shl_lat, shl_lon, bhl_lat, bhl_lon, heel_lat, heel_lon, lat, lon, first_prod, last_prod, cum_oil_12, cum_gas_12, cum_boe_12, cum_oil_life, cum_gas_life, cum_boe_life, total_proppant, total_fluid, stage_count, frac_date, til_date.

    For example well_name,tvd_td. fields is checked before the well is looked up, so a bad name is a 400 whatever the key.

    Names are top-level only (no dots), case-sensitive and never empty; one not allowed here is a 400 with the allowed names in details.allowed.

  • includestringOptional

    floors adds floored: the names of this answer's fields whose value may start at the dataset's first production month, not at the well's own start.

    The record starts in that month (GET /dataset first_production), so a well whose first production falls in it may have produced earlier, unless its til_date is in that month too (the rule exclude_floor uses on POST /wells/typecurve). Such a well's first_prod is the floor month, and its cum_*_12 and cum_*_life count only from it: show them as "before <month>" or "since <month>", not as facts. The values don't change.

    floored lists only fields this answer has (with fields, those asked), is [] for a well that isn't floored, and is absent without include; an empty value is the same as none. Any other nonempty value, or one named twice, is a 400 with details.field include, checked before the well is looked up.

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

  • wellbore_keystringRequired

    Wellbore key.

  • well_namestring or nullOptional

    Well name.

  • operatorstring or nullOptional

    Current operator.

  • basinstring or nullOptional

    Basin.

  • subbasinstring or nullOptional

    Sub-basin.

  • statestring or nullOptional

    State.

  • countystring or nullOptional

    County.

  • formationstring or nullOptional

    Landing formation.

  • lateral_lengthnumber or nullOptional

    Lateral length, ft.

  • tvd_tdnumber or nullOptional

    True vertical depth, ft.

  • shl_latnumber or nullOptional

    Surface hole latitude.

  • shl_lonnumber or nullOptional

    Surface hole longitude.

Show all 32 fields
  • bhl_latnumber or nullOptional

    Bottom hole latitude.

  • bhl_lonnumber or nullOptional

    Bottom hole longitude.

  • heel_latnumber or nullOptional

    Heel latitude.

  • heel_lonnumber or nullOptional

    Heel longitude.

  • latnumber or nullOptional

    Header latitude.

  • lonnumber or nullOptional

    Header longitude.

  • first_prodstring or nullOptional

    Format date

    First production.

  • last_prodstring or nullOptional

    Format date

    Last production.

  • cum_oil_12number or nullOptional

    First 12 months oil, whole bbl.

  • cum_gas_12number or nullOptional

    First 12 months gas, whole mcf.

  • cum_boe_12number or nullOptional

    First 12 months, whole BOE.

  • cum_oil_lifenumber or nullOptional

    Cumulative oil, whole bbl.

  • cum_gas_lifenumber or nullOptional

    Cumulative gas, whole mcf.

  • cum_boe_lifenumber or nullOptional

    Cumulative BOE, whole.

  • total_proppantnumber or nullOptional

    Proppant, whole lb.

  • total_fluidnumber or nullOptional

    Fluid, whole bbl.

  • stage_countinteger or nullOptional

    Frac stages.

  • frac_datestring or nullOptional

    Format date

    Frac date.

  • til_datestring or nullOptional

    Format date

    Turn-in-line date.

  • flooredarray of stringsOptional

    With include=floors only: the fields here whose value may start at the dataset's first production month rather than at the well's own start (first_prod is then that floor month; 12-month and to-date volumes count only from it). Empty for a well that isn't floored.

    "first_prod""cum_oil_12""cum_gas_12""cum_boe_12""cum_oil_life""cum_gas_life""cum_boe_life"
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