Skip to content
Developers
Get an API token

Build a type curve from a plan's forecasts

A done plan's forecasts for one design as type curves, in POST /wells/typecurve's shape.

Build a type curve from a plan's forecasts

GET/plans/{id}/typecurve/{design}

A done plan's forecasts for one design as type curves, in POST /wells/typecurve's shape. It carries an ETag: send it as If-None-Match for a 304.

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

Each well's value is its served forecast for the design (the curve GET /plans/{id}/wells/{index} serves; exports call it P50) at each forecast ip_day: each stream's cumulative, BOE as oil + gas / 6 (null when either is), and rate, the step's average daily rate.

Statistics

At each ip_day, wells counts the wells with a value; mean is their plain mean and q10, q50 and q90 their quantiles, linear between ranks as GET /plans/{id}/stats takes them, not the plan's P10 and P90 bands. min_wells is 1.

Counts

wells counts the wells in scope (the plan's, or the scenario's), used those with a forecast for the design, and excluded.no_forecast the rest (not placed, or the forecast failed); the other excluded counts are 0. A well whose stream failed stays in used but leaves that stream's wells.

Errors

409 while the plan runs, when it failed, or for a scenario plan without scenario; 404 for an unknown plan or a design index the plan doesn't have.

Parameters

Path parameters

  • idstringRequired

    Format uuid

    Plan id from POST /plans.

  • designintegerRequired

    ≥ 0, ≤ 9

    The design's position in the plan's designs, from 0.

Query parameters

  • streamsstringOptional

    The streams, comma-separated, each once: oil, gas, water and boe, as oil,boe. Absent or empty: the plan's streams, then boe (all four on a plan with oil, gas and water). Another name, or one named twice, is a 400.

  • measuresstringOptional

    cum, each well's cumulative at the ip_day, and rate, its average daily rate over the step ending there (the first step from day 0), comma-separated, as rate or cum,rate. Absent or empty: both. Another name, or one named twice, is a 400.

  • normalize_lateral_ftnumberOptional

    ≥ 100, ≤ 20000

    Scale each well to this many ft of lateral before the statistics: its value × normalize_lateral_ft / its lateral_length_ft (as GET /plans/{id}?include=wells serves it). A plain decimal from 100 to 20,000, as 1000 for per 1,000 ft. Absent: unscaled, and the answer's normalize_lateral_ft is null.

  • pooledbooleanOptional

    Default false

    true, with normalize_lateral_ft only (without it, a 400 on pooled): each series also gets pooled, Σ value / Σ lateral × normalize_lateral_ft over the wells with a value at the ip_day, as POST /wells/typecurve gives it. Absent or false: no pooled key.

  • group_bystringOptional

    One curve per group, the 12 with the most wells used kept and the rest counted in groups_left_out. Any other value is a 400.

    • formation: each well's formation; ties by name, wells without one last.
    • pad: each pad key; ties by key, wells without a pad as group: null; with scenario, among its wells. A plan whose wells name no pads is a 400: send wells[].pad.
    "formation""pad"
  • scenariostringOptional

    1 to 60 characters

    On a plan made with scenarios, the alternative to aggregate: wells, used and the curves are then over its wells alone. A scenario plan answers 409 without it, so alternatives are never averaged together; the 409's details.scenarios lists the plan's scenario names in plan order, to pick from. An empty name, a name the plan doesn't have, or any name on a plan without scenarios is a 400.

  • 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 plan's type curves.

  • wellsintegerRequired

    ≥ 0

    Wells matching the scope.

  • usedintegerRequired

    ≥ 0

    Of them, those used: on POST /wells/typecurve, with production, a lateral when normalizing, and not left out by exclude_floor, min_lateral_ft or cohort_ip_day; on GET /plans/{id}/typecurve/{design}, with a forecast for the design.

  • excludedobjectRequired

    Wells left out, and why: wells is used plus these. floor, short_lateral and short_history are present only with their options and count each well under the first that leaves it out, in that order.

    ShowHide 7 child fields
    • no_productionintegerRequired

      ≥ 0

      Wells without production.

    • no_lateralintegerRequired

      ≥ 0

      With normalize_lateral_ft, wells with production but without a lateral.

    • no_locationintegerRequired

      ≥ 0

      With bbox, near or a unit: keyed wells (wells) without a location, which no spatial scope can place.

    • floorintegerOptional

      ≥ 0

      With exclude_floor: true, wells whose first production is in the dataset's first production month, without a til_date in it.

    • short_lateralintegerOptional

      ≥ 0

      With min_lateral_ft, wells with a shorter lateral.

    • short_historyintegerOptional

      ≥ 0

      With cohort_ip_day, wells without a value for every asked stream and measure at every 30-day ip_day to it.

    • no_forecastintegerOptional

      ≥ 0

      GET /plans/{id}/typecurve/{design} only: plan wells without a forecast for the design, as they couldn't be placed or the forecast failed.

  • normalize_lateral_ftnumber or nullRequired

    The lateral every well was scaled to, ft; null without normalize_lateral_ft.

  • min_wellsintegerRequired

    ≥ 1

    Fewest wells for a mean and quantiles.

  • unitsobjectRequired

    Units: bbl, mcf, bbl and BOE, rates per day.

    ShowHide 5 child fields
    • oilstringRequired

      Oil volumes.

    • gasstringRequired

      Gas volumes.

    • waterstringRequired

      Water volumes.

    • boestringRequired

      BOE volumes.

    • ratestringRequired

      Rates are those units per day.

  • ip_daysarray of integersRequired

    The ip_days every series is parallel to.

  • curvesarray of objectsRequired

    One curve, or with group_by one per group, most wells first; with group_by and no wells used, empty.

    ShowHide 4 child fields in each item
    • groupstring or integer or nullRequired

      The formation, operator or first-production year, or on a plan the pad key; null without group_by, or for the wells without that value.

    • wellsintegerRequired

      ≥ 0

      Wells in this curve.

    • streamsobjectRequired

      The asked streams.

      ShowHide 4 child fields
      • oilobjectOptional

        oil: the asked measures.

        ShowHide 2 child fields
        • cumobjectOptional

          One measure across wells, parallel to ip_days.

          ShowHide 3 child fields
          • wellsarray of integersRequired

            Items ≥ 0

            How many wells reach each ip_day: on POST /wells/typecurve without cohort_ip_day, later ip_days describe fewer, older wells; on GET /plans/{id}/typecurve/{design}, the wells used with a finite value for this stream and measure there.

          • meanarray of numbersRequired

            Means.

          • pooledarray of numbersOptional

            With pooled: true only.

        • rateobjectOptional

          One measure across wells, parallel to ip_days.

          Same fields as TypeCurveSeries.

      • gasobjectOptional

        gas: the asked measures.

        ShowHide 2 child fields
        • cumobjectOptional

          One measure across wells, parallel to ip_days.

          Same fields as TypeCurveSeries.

        • rateobjectOptional

          One measure across wells, parallel to ip_days.

          Same fields as TypeCurveSeries.

      • waterobjectOptional

        water: the asked measures.

        ShowHide 2 child fields
        • cumobjectOptional

          One measure across wells, parallel to ip_days.

          Same fields as TypeCurveSeries.

        • rateobjectOptional

          One measure across wells, parallel to ip_days.

          Same fields as TypeCurveSeries.

      • boeobjectOptional

        boe: the asked measures.

        ShowHide 2 child fields
        • cumobjectOptional

          One measure across wells, parallel to ip_days.

          Same fields as TypeCurveSeries.

        • rateobjectOptional

          One measure across wells, parallel to ip_days.

          Same fields as TypeCurveSeries.

    • namestringOptional

      On GET /plans/{id}/typecurve/{design} with group_by=pad, the pad's name when the plan gives one in pads[].name; absent otherwise. group stays the pad key.

  • groups_left_outintegerRequired

    ≥ 0

    With group_by, the groups past the largest; else 0.

  • cohort_ip_dayintegerOptional

    ≥ 30

    The cohort_ip_day sent; only with it.

  • well_seriesobjectOptional

    With include: ["wells"]: each well's own series.

    ShowHide 4 child fields
    • wellbore_keyarray of stringsRequired

      The wells used, in key order.

    • well_namearray of stringsRequired

      Their names.

    • lateral_lengtharray of numbersRequired

      Their laterals, ft.

    • streamsobjectRequired

      The asked streams and measures.

      ShowHide 4 child fields
      • oilobjectOptional

        oil: the asked measures.

        ShowHide 2 child fields
        • cumarray of arraysOptional

          One per well, in wellbore_key order.

        • ratearray of arraysOptional

          One per well, in wellbore_key order.

      • gasobjectOptional

        gas: the asked measures.

        ShowHide 2 child fields
        • cumarray of arraysOptional

          One per well, in wellbore_key order.

        • ratearray of arraysOptional

          One per well, in wellbore_key order.

      • waterobjectOptional

        water: the asked measures.

        ShowHide 2 child fields
        • cumarray of arraysOptional

          One per well, in wellbore_key order.

        • ratearray of arraysOptional

          One per well, in wellbore_key order.

      • boeobjectOptional

        boe: the asked measures.

        ShowHide 2 child fields
        • cumarray of arraysOptional

          One per well, in wellbore_key order.

        • ratearray of arraysOptional

          One per well, in wellbore_key order.

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

Errors

StatusWhen
404

No such well, grid, plan or route.

409

The request conflicts with the state of the plan or resource it names, and message says how: for example a plan still running or failed, a stale If-Match, an Idempotency-Key reused with another body, or a server without a state store.

Shared errors400401403500503What they mean