Skip to content
Developers
Get an API token

Summarize a plan's wells

The distribution of one per-well metric over a plan's wells under one design, without downloading the wells: how many have a value, min, max, mean, quantiles and a histogram, as PlanStats describes them.

Summarize a plan's wells

GET/plans/{id}/stats

The distribution of one per-well metric over a plan's wells under one design, without downloading the wells: how many have a value, min, max, mean, quantiles and a histogram, as PlanStats describes them.

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

eur_boe by default on a plan made with eur: true, else cum_boe at ip_day 1080; values are rounded to 0.1, in unit. On a plan made with scenarios, every figure pools all its scenarios' wells unless scenario picks one; group_by=scenario measures each beside that pooled top level.

Quantiles and bins

Quantiles interpolate linearly between the closest ranks (NumPy's default, Hyndman and Fan type 7): q10 is the low end, 10% of wells below it. They are the spread across wells, not a forecast's uncertainty: P10/P90 bands (Novi's P10 is the low curve, the reverse of SPE PRMS) are per well, from bands: true. The histogram has bins equal-width bins from min to max, each from its lower edge up to its upper one (the last includes max); when every value is the same it is one bin.

While it runs

The figures cover the wells finished so far, with partial: true, Retry-After: 1 and no ETag. A done plan's answer carries an ETag; send it as If-None-Match for a 304. A failed plan answers 409.

Parameters

Path parameters

Query parameters

  • metricstringOptional

    The metric: eur_boe by default on a plan with EUR, else cum_boe.

    Per-well metrics: eur_oil (bbl), eur_gas (mcf) and eur_boe (BOE) are each well's EUR and need a plan made with eur: true (400 otherwise); cum_oil, cum_gas and cum_boe are the forecast's cumulative volume at ip_day. BOE is oil + gas / 6, only for wells with both.

    "eur_boe""eur_oil""eur_gas""cum_boe""cum_oil""cum_gas"
  • designintegerOptional

    Default 0≥ 0, ≤ 9

    the design whose forecasts are measured, as its index in the plan's designs; 400 past the last one.

  • ip_dayintegerOptional

    Default 1080≥ 1

    for a cum_ metric, the ip_day (days since first production) whose cumulative volume is measured: one of GET /dataset ip_days, default 1080 (3 years). 400 with an eur_ metric.

  • binsintegerOptional

    Default 20≥ 1, ≤ 100

    Histogram bins.

  • includestringOptional

    values adds every well's value, ascending (ties by plan index), with its plan index: for probit plots, and for linking a point to its well. Up to the plan's wells (GET /dataset limits.plan_wells).

    "values"
  • quantilesstringOptional

    Which quantiles to return, comma-separated: whole percentiles 1 to 99, at most 9 different ones, as 10,25,50,75,90 for a box plot; quantiles then holds exactly q10, q25 and so on. Quantiles of wells' values (type 7, q10 the low end), not P-level bands. Absent: q10, q50 and q90.

  • group_bystringOptional

    Also measure each group of wells: design, formation, scenario or pad. The top-level figures stay those of design, 0 by default.

    • design: every design of the plan; a 400 with the design parameter.
    • formation: each well's target formation, wells without one as key: null.
    • scenario: each scenario of a plan made with them; a 400 on another plan and with the scenario parameter.
    • pad: each stored pad key (after scenario scoping), wells without one as null, never folded into Other. A plan whose wells name no pads is a 400: send wells[].pad.

    Each group has its own counts, min, max, mean, quantiles and histogram, and values with include=values, all on the same edges (for formation and scenario the top-level edges, for design every design's), so groups plot side by side. PlanStats groups gives their order; design, formation and scenario give at most 50 groups, the rest summed in one Other row with others.

    "design""formation""scenario""pad"
  • normalize_lateral_ftnumberOptional

    ≥ 100, ≤ 20000

    Scale each well's value to this lateral length before measuring: value × normalize_lateral_ft / its lateral_length_ft, so 1000 gives values per 1,000 ft of lateral. Every figure is then normalised, the response echoes it, and unit still names the volume. 100 to 20,000.

  • scenariostringOptional

    1 to 60 characters

    Measure one scenario of a plan made with them: every figure, the histogram's bins and any group_by=formation or group_by=design groups cover only its wells, and the response echoes the name.

    Send the name exactly as the plan's scenarios list it, URL-encoded: 660 ft is scenario=660%20ft. With include=values, index stays the well's index in the whole plan, so a point still links to its well. While the plan runs, the figures cover the scenario's wells finished so far.

    An empty name, or one the plan doesn't have, is a 400 whose details.scenarios lists the plan's scenarios (empty on a plan without them, where any name is a 400). A name over 60 characters is a 400 without the list. With group_by=scenario it is a 400 on group_by: scenario picks one, so leave group_by=scenario out.

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

  • idstringRequired

    Format uuid

    Plan id.

  • designintegerRequired

    ≥ 0

    The design, as its index in designs.

  • metricstringRequired

    The metric measured.

    "eur_boe""eur_oil""eur_gas""cum_boe""cum_oil""cum_gas"
  • ip_dayinteger or nullRequired

    For a cum_ metric, the ip_day measured; null for an eur_ metric.

  • unitstringRequired

    The unit of every value: bbl (oil), mcf (gas) or BOE.

    "bbl""mcf""BOE"
  • partialbooleanRequired

    True while the plan runs: the figures cover the wells finished so far.

  • wellsintegerRequired

    ≥ 0

    Wells with a value; every figure describes them.

  • missingintegerRequired

    ≥ 0

    Wells finished without a value: no forecast, a failed EUR fit, or BOE without both oil and gas.

  • minnumber or nullRequired

    Smallest value; null when no well has one.

  • maxnumber or nullRequired

    Largest value; null when no well has one.

  • meannumber or nullRequired

    Mean value; null when no well has one.

  • quantilesobjectRequired

    Quantiles across wells (linear interpolation between the closest ranks), not P-level bands: q10 (the 10th percentile of the wells' values, the low end), q50 (the median) and q90 (the high end), or with quantiles= exactly the asked ones; each null when no well has a value.

Show all 18 fields
  • histogramobjectRequired

    Equal-width bins from min to max.

    ShowHide 2 child fields
    • edgesarray of numbersRequired

      Bin edges, ascending, one more than counts; empty when no well has a value.

    • countsarray of integersRequired

      Items ≥ 0

      Wells per bin; they add up to wells.

  • normalize_lateral_ftnumberOptional

    With normalize_lateral_ft: the lateral every value was scaled to, ft.

  • scenariostringOptional

    With scenario: the scenario measured.

  • valuesobjectOptional

    With include=values: every well with a value, ascending.

    ShowHide 2 child fields
    • indexarray of integersRequired

      Items ≥ 0

      The wells, by plan index, in value order.

    • valuearray of numbersRequired

      Their values, ascending (ties by index).

  • group_bystringOptional

    With group_by: what groups is by.

    "design""formation""scenario""pad"
  • groupsarray of objectsOptional

    With group_by: each design in order, each formation in GET /formations order, then wells without one, or each scenario in the order of the plan's scenarios; pad lists all keys in first measured well order, null last, never folded into Other. For other groupings, at most 50, the rest in one Other row.

    ShowHide 11 child fields in each item
    • keystring or integer or nullRequired

      The design's index (group_by=design), the formation, null for wells without one, the scenario, the pad key (null for wells without one), or Other on the summed row. Pads never fold into Other.

    • wellsintegerRequired

      ≥ 0

      Wells in the group with a value.

    • missingintegerRequired

      ≥ 0

      Wells in the group without one.

    • minnumber or nullRequired

      Smallest value; null when none has one.

    • maxnumber or nullRequired

      Largest value; null when none has one.

    • meannumber or nullRequired

      Mean value; null when none has one.

    • quantilesobjectRequired

      The same quantiles as the top level, over this group's wells.

    • histogramobjectRequired

      Counts on edges every group shares, so groups plot side by side.

      ShowHide 2 child fields
      • edgesarray of numbersRequired

        The same for every group: bins bins from the smallest to the largest value of all the groups (for group_by=formation or scenario, the top-level edges); empty when no group has a value.

      • countsarray of integersRequired

        Items ≥ 0

        This group's wells per bin; they add up to its wells.

    • namestringOptional

      With group_by=pad, the pad's name when the plan gives one in pads[].name; absent otherwise. key stays the pad key.

    • valuesobjectOptional

      With include=values: this group's wells, ascending.

      Same fields as PlanStatsValues.

    • othersintegerOptional

      ≥ 1

      On the Other row only: how many groups it sums.

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