Skip to content
Developers
Get an API token

Sum a plan's oil, gas and water by pad and zone

One design's oil, gas and water at one ip_day, summed for a plan by pad and by landing zone (formation) in each pad, without downloading the wells.

Sum a plan's oil, gas and water by pad and zone

GET/plans/{id}/rollup

One design's oil, gas and water at one ip_day, summed for a plan by pad and by landing zone (formation) in each pad, without downloading the wells. Every pad is listed, without paging, as PlanRollup describes; a plan whose wells name no pads answers one key: null pad.

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

Wells and streams count as GET /plans/{id} totals counts them: a well counts when its forecast under the design isn't an error, and a stream sums its wells whose stream forecast isn't an error, so a well without a water forecast is left out of water only. A well without a value at ip_day adds 0. Each value is summed unrounded and rounded once to 0.1.

  • Counts add up exactly: formations to their pad and pads to totals, wells_flagged with null as 0.
  • Values can differ from the sum of their parts by rounding: a pad from its N formations by up to 0.05 × (N + 1), and totals from its P pads by up to 0.05 × (P + 1).
  • On a done plan the totals row equals GET /plans/{id} totals for the same design and scenario wherever those have a value at ip_day: wells_with_forecast, wells_flagged and each stream's value.
EUR

On a plan made with eur: true, every row has eur (PlanRollupEur), rounded and adding up as the values do. It doesn't change with ip_day, so a done plan's totals row has that design and scenario's totals eur, without their P10 and P90 sums.

While it runs

Every pad and formation row is listed from the first read, its counts and sums covering the wells finished so far; partial is true, with Retry-After: 1 and no ETag. A done plan's answer carries an ETag; send If-None-Match for a 304.

Errors

409 for a failed plan; for a plan made with scenarios read without scenario (with details.scenarios), since its rows would add alternatives together; and, with several server tasks, for a plan running on another task until it finishes: retry shortly.

Parameters

Path parameters

Query parameters

  • designintegerOptional

    Default 0≥ 0, ≤ 9

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

  • scenariostringOptional

    Required on a plan made with scenarios, which answers 409 without it: the scenario whose wells are summed, named exactly as the plan's scenarios list it, URL-encoded (660 ft is scenario=660%20ft), and echoed.

    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.

  • ip_dayintegerOptional

    Default 1080≥ 1

    The ip_day (days since first production) whose cumulative volumes are summed: one of GET /dataset ip_days, default 1080 (3 years). Another value is a 400 with details.allowed.

  • 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 roll-up; an ETag when done, Retry-After: 1 while running.

  • plan_idstringRequired

    Format uuid

    Plan id.

  • designintegerRequired

    ≥ 0

    The design, as its index in designs.

  • scenariostring or nullRequired

    The scenario summed; null on a plan without scenarios.

  • ip_dayintegerRequired

    ≥ 1

    The ip_day (days since first production) each cumulative volume is read at.

  • partialbooleanRequired

    True while the plan runs: counts and sums cover the wells finished so far, and every row is listed.

  • unitsobjectRequired

    The unit of each stream's value.

    ShowHide 3 child fields
    • oilstringRequired

      Oil volume unit.

      "bbl"
    • gasstringRequired

      Gas volume unit.

      "mcf"
    • waterstringRequired

      Water volume unit.

      "bbl"
  • totalsobjectRequired

    Every well in scope. On a done plan it equals GET /plans/{id} totals for this design and scenario at ip_day.

    ShowHide 7 child fields
    • wellsintegerRequired

      ≥ 0

      Wells in the group and scope, forecast or not, finished or not.

    • wells_with_forecastintegerRequired

      ≥ 0

      Wells with a forecast under the design, as GET /plans/{id} totals counts them; while running, of those finished.

    • wells_flaggedinteger or nullRequired

      ≥ 0

      Wells whose checks flagged inputs outside training, as totals counts them; null when no well in the row was checked.

    • oilobjectOptional

      One stream's sum.

      ShowHide 2 child fields
      • valuenumber or nullRequired

        The cumulative volume at ip_day summed over wells, in units, rounded once to 0.1; null when wells is 0.

      • wellsintegerRequired

        ≥ 0

        Wells summed: those with this stream's forecast.

    • gasobjectOptional

      One stream's sum.

      Same fields as PlanRollupStream.

    • waterobjectOptional

      One stream's sum.

      Same fields as PlanRollupStream.

    • eurobjectOptional

      On a plan made with eur: true: each stream's EUR summed over the row's wells with one, and BOE over those with both, by the code GET /plans/{id} totals eur uses; no P10 or P90. Only the streams the model set serves (GET /model-sets streams): a set serving gas alone answers gas alone.

      ShowHide 4 child fields
      • boeobjectRequired

        BOE EUR over the wells with both fits, so the sum and the well count agree.

        ShowHide 2 child fields
        • valuenumber or nullRequired

          Oil EUR plus gas EUR / 6 (bbl of oil equivalent) summed over the wells with both; null when none has.

        • wellsintegerRequired

          Wells with both an oil and a gas EUR.

      • oilobjectOptional

        A stream's EUR over the row's wells.

        ShowHide 3 child fields
        • valuenumber or nullRequired

          EUR summed over the wells with one; null when none has.

        • daysinteger or nullRequired

          ip_day of the EUR; null when none has one, or when the wells summed differ in eur_years: the sum then runs to no one day, and each scenario is read apart.

        • wellsintegerRequired

          Wells with an EUR.

      • gasobjectOptional

        A stream's EUR over the row's wells.

        Same fields as PlanRollupEurStream.

      • waterobjectOptional

        Only on a plan made with eur_water: true. BOE doesn't read it.

        Same fields as PlanRollupEurStream.

  • padsarray of objectsRequired

    Every pad, in plan order of each pad's first well, wells without a pad last.

    ShowHide 10 child fields in each item
    • keystring or nullRequired

      The pad key the plan was sent; null for wells without one.

    • wellsintegerRequired

      ≥ 0

      Wells in the group and scope, forecast or not, finished or not.

    • wells_with_forecastintegerRequired

      ≥ 0

      Wells with a forecast under the design, as GET /plans/{id} totals counts them; while running, of those finished.

    • wells_flaggedinteger or nullRequired

      ≥ 0

      Wells whose checks flagged inputs outside training, as totals counts them; null when no well in the row was checked.

    • formationsarray of objectsRequired

      The pad's wells by formation: GET /formations order, unlisted ones by name, wells without one last.

      ShowHide 8 child fields in each item
      • keystring or nullRequired

        The formation; null for wells without one.

      • wellsintegerRequired

        ≥ 0

        Wells in the group and scope, forecast or not, finished or not.

      • wells_with_forecastintegerRequired

        ≥ 0

        Wells with a forecast under the design, as GET /plans/{id} totals counts them; while running, of those finished.

      • wells_flaggedinteger or nullRequired

        ≥ 0

        Wells whose checks flagged inputs outside training, as totals counts them; null when no well in the row was checked.

      • oilobjectOptional

        One stream's sum.

        Same fields as PlanRollupStream.

      • gasobjectOptional

        One stream's sum.

        Same fields as PlanRollupStream.

      • waterobjectOptional

        One stream's sum.

        Same fields as PlanRollupStream.

      • eurobjectOptional

        On a plan made with eur: true: each stream's EUR summed over the row's wells with one, and BOE over those with both, by the code GET /plans/{id} totals eur uses; no P10 or P90. Only the streams the model set serves (GET /model-sets streams): a set serving gas alone answers gas alone.

        Same fields as PlanRollupEur.

    • namestringOptional

      The pad's name, only when the plan names it.

    • oilobjectOptional

      One stream's sum.

      Same fields as PlanRollupStream.

    • gasobjectOptional

      One stream's sum.

      Same fields as PlanRollupStream.

    • waterobjectOptional

      One stream's sum.

      Same fields as PlanRollupStream.

    • eurobjectOptional

      On a plan made with eur: true: each stream's EUR summed over the row's wells with one, and BOE over those with both, by the code GET /plans/{id} totals eur uses; no P10 or P90. Only the streams the model set serves (GET /model-sets streams): a set serving gas alone answers gas alone.

      Same fields as PlanRollupEur.

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