Oil Price API Well Lifecycle API

openapi: 3.2.0
info:
  title: Oil Price API V1 Well Lifecycle API
  version: v1
  description: 'Source-aware oil and energy data API. Check each endpoint''s source timestamp,

    coverage, and freshness fields before using a response in a time-sensitive workflow. ## Authentication


    API-key endpoints use `Authorization: Token YOUR_API_KEY`. Operations that do

    not require an API key explicitly declare an empty security requirement. `/v1/demo/prices` is keyless. ## Rate Limiting


    - Free tier: 50 requests per day

    - Paid tiers have plan-specific monthly quotas. - `402` means the allowance is exhausted: a Free or post-trial caller

    must upgrade, and a paid plan has used its monthly allowance (the body

    carries `MONTHLY_QUOTA_EXCEEDED` and reset metadata, so do not retry before

    the reset). `429` means an active-trial allowance or a rolling rate limit

    (for example the hourly safety limit) is exceeded; retry `429` and transient

    `5xx` responses with bounded backoff. - Website login and signup (`POST /sessions` and `POST /users`) also enforce

    authentication-attempt limits independently of API plan quotas: 3 attempts

    per normalized email address in 5 minutes, and 3 attempts per minute per

    verified visitor IP. Requests without a verified proxy identity retain

    the existing 20 requests/minute IP ceiling. A `429` on these routes means

    wait for `Retry-After` before retrying; upgrading a plan does not remove

    authentication-attempt limits. Futures curves are never refused because a market is closed or a session has

    just reopened. The last available data is served with `metadata.freshness_status`,

    `metadata.stale`, `metadata.latest_data_at` and `metadata.stale_by_minutes`:

    `outside_market_hours` while the venue is closed (weekend, daily break,

    holiday); `awaiting_first_print` for the first 30 minutes of a new session

    while only a valid prior close exists; `degraded` when the market is open and

    the source is behind. None of these is a fresh trade; source timestamps remain

    unchanged. Data older than the 96-hour serving bound is refused with 503. Gasoil reports `metadata.freshness_status: no_recent_trades` when the

    benchmark contract has not traded within 30 minutes but our collector confirmed

    the quote within that window and the curve printed within 90 minutes. The last

    trade is served with its true `latest_data_at` and `stale_by_minutes`, plus

    `source_checked_at` and `curve_latest_trade_at`. Paid monthly-cap responses include `retry_guidance`: immediate retries cannot

    restore quota. When a representative sample supports it, `batching_opportunity`

    describes an estimated lower request rate; batching does not restore an already

    exhausted allowance. It may replace an unnecessary upgrade recommendation. ## Continuous futures coverage


    On `/v1/futures/continuous/brent`, `/v1/futures/continuous/wti` and their

    `/historical` routes, `metadata.history_available_from` is the earliest

    stored public continuous futures source date, falling back to collection

    date for older imports without a source timestamp. It is a date string or

    null when no public observations exist. Coverage metadata is cached for up

    to one hour and does not promise observations or volume on every later date. It describes the archive independently of the request''s date range; account

    depth limits remain in `metadata.history_window` on historical responses. Latest-response `metadata.total_historical_records` counts stored public

    snapshots, including revisions, rather than distinct source dates. Latest

    quotes and their prior-day comparisons exclude private organization rows

    and other price types. Repeated source timestamps select the later collected

    revision; the oldest metadata/response cache formats are no longer used. ## Spread and indicator query parameters


    Spread and indicator endpoints reject unrecognized query parameter names with

    HTTP 400 and `error.code: UNKNOWN_PARAMETERS`, after authentication and access

    checks. The error includes `unrecognized_parameters`, `allowed_parameters`,

    and a `suggestions` map for recognized date-name mistakes; values are not

    echoed.'
  contact:
    name: Oil Price API Support
    email: support@oilpriceapi.com
    url: https://oilpriceapi.com
  license:
    name: Commercial License
    url: https://oilpriceapi.com/terms
servers:
- url: https://api.oilpriceapi.com
  description: Production server
tags:
- name: Well Lifecycle
  description: Well lifecycle availability, cohorts, and state coverage.
paths:
  /v1/well-lifecycle/states:
    get:
      summary: Well lifecycle state availability
      operationId: getV1WellLifecycleStates
      tags:
      - Well Lifecycle
      description: 'Returns customer-safe lifecycle availability statuses by state. This endpoint

        classifies states as available, partial, repair_required, or unavailable so

        clients do not mistake missing lifecycle coverage for valid zero data.'
      security:
      - ApiKeyAuth: []
      parameters:
      - name: states
        in: query
        required: false
        description: Comma-separated two-letter state codes. Defaults to promoted lifecycle states; pass states explicitly to inspect unavailable or repair-gated states.
        schema:
          type: string
        example: TX,NM,WY
      - name: api_limit
        in: query
        required: false
        description: Maximum permit APIs analyzed per state for bounded online validation. Defaults to 1 for the no-param overview and 1000 for explicit state requests.
        schema:
          type: integer
          default: 1000
          example: 100
      - name: include_samples
        in: query
        required: false
        description: Include diagnostic sample rows in list responses.
        schema:
          type: boolean
          default: false
          example: false
      responses:
        '200':
          description: Lifecycle state availability list
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  data:
                    type: object
                    properties:
                      generated_at:
                        type: string
                        format: date-time
                      count:
                        type: integer
                      states:
                        type: array
                        items:
                          $ref: '#/components/schemas/WellLifecycleStateAvailability'
                      meta:
                        type: object
        '400':
          description: Invalid state code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Enterprise plan required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/well-lifecycle/states/{state_code}:
    get:
      summary: Well lifecycle availability for one state
      operationId: getV1WellLifecycleStatesByStateCode
      tags:
      - Well Lifecycle
      description: Detailed lifecycle availability report for a state, including reason codes and diagnostic samples.
      security:
      - ApiKeyAuth: []
      parameters:
      - name: state_code
        in: path
        required: true
        description: Two-letter state code.
        schema:
          type: string
          example: TX
        example: TX
      - name: api_limit
        in: query
        required: false
        description: Maximum permit APIs analyzed for bounded online validation.
        schema:
          type: integer
          default: 1000
          example: 100
      - name: full
        in: query
        required: false
        description: Run an unbounded full-state validation report. Use carefully for large states.
        schema:
          type: boolean
          default: false
          example: true
      responses:
        '200':
          description: Lifecycle state availability report
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  data:
                    $ref: '#/components/schemas/WellLifecycleStateAvailability'
        '400':
          description: Invalid state code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Enterprise plan required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/well-lifecycle/wells/{api_number}:
    get:
      summary: Well lifecycle summary for one well
      operationId: getV1WellLifecycleWellsByApiNumber
      tags:
      - Well Lifecycle
      description: 'Returns the persisted permit-to-production lifecycle summary for a single

        promoted-state well. Runtime requests read materialized lifecycle summaries

        and do not perform large raw permit/production joins.'
      security:
      - ApiKeyAuth: []
      parameters:
      - name: api_number
        in: path
        required: true
        description: 10-, 12-, or 14-digit API number. Common dashed formats are accepted and normalized to a 14-digit API number.
        schema:
          type: string
        example: '30015234560000'
      responses:
        '200':
          description: Persisted lifecycle summary
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  data:
                    $ref: '#/components/schemas/WellLifecycleWellSummary'
        '400':
          description: Malformed API number
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Enterprise plan required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Lifecycle summary unavailable for this well or state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/well-lifecycle/cohorts:
    get:
      summary: Well lifecycle cohorts
      operationId: getV1WellLifecycleCohorts
      tags:
      - Well Lifecycle
      description: 'Returns cohort-level cycle-time summaries from persisted lifecycle summaries

        for promoted states. Supported grouping dimensions are operator, county, and

        permit quarter.'
      security:
      - ApiKeyAuth: []
      parameters:
      - name: state
        in: query
        required: true
        description: Promoted two-letter state code.
        schema:
          type: string
          enum:
          - NM
          - WY
          - ND
          - AK
        example: NM
      - name: group_by
        in: query
        required: false
        description: Cohort grouping dimension.
        schema:
          type: string
          enum:
          - operator
          - county
          - quarter
          default: operator
          example: operator
        example: operator
      responses:
        '200':
          description: Lifecycle cohort summaries
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  data:
                    $ref: '#/components/schemas/WellLifecycleCohorts'
        '400':
          description: Invalid state or grouping parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Enterprise plan required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Lifecycle cohorts unavailable for this state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    WellLifecycleCohorts:
      type: object
      properties:
        state:
          type: string
          example: NM
        group_by:
          type: string
          enum:
          - operator
          - county
          - quarter
          example: operator
        count:
          type: integer
          example: 25
        cohorts:
          type: array
          items:
            $ref: '#/components/schemas/WellLifecycleCohort'
    WellLifecycleWellSummary:
      type: object
      properties:
        api_number:
          type: string
          example: '30015234560000'
        state:
          type: string
          example: NM
        county:
          type:
          - string
          - 'null'
          example: Eddy
        operator:
          type:
          - string
          - 'null'
          example: Example Energy LLC
        well_name:
          type:
          - string
          - 'null'
          example: STATE 1H
        source:
          type: string
          example: New Mexico OCD
        lifecycle_dates:
          type: object
          properties:
            permit_date:
              type:
              - string
              - 'null'
              format: date
            approval_date:
              type:
              - string
              - 'null'
              format: date
            spud_date:
              type:
              - string
              - 'null'
              format: date
            year_spudded:
              type:
              - integer
              - 'null'
            completion_date:
              type:
              - string
              - 'null'
              format: date
            first_production_month:
              type:
              - string
              - 'null'
              format: date
            latest_production_month:
              type:
              - string
              - 'null'
              format: date
        production:
          type: object
          properties:
            production_months:
              type: integer
              example: 18
            cumulative_oil_bbl:
              type:
              - number
              - 'null'
              example: 125000
            cumulative_gas_mcf:
              type:
              - number
              - 'null'
              example: 400000
            cumulative_water_bbl:
              type:
              - number
              - 'null'
              example: 210000
            cumulative_boe:
              type:
              - number
              - 'null'
              example: 191666.67
        cycle_times:
          type: object
          properties:
            permit_to_spud_days:
              type:
              - integer
              - 'null'
              example: 40
            spud_to_completion_days:
              type:
              - integer
              - 'null'
              example: 70
            completion_to_first_prod_days:
              type:
              - integer
              - 'null'
              example: 26
            permit_to_first_prod_days:
              type:
              - integer
              - 'null'
              example: 136
            permit_to_frac_days:
              type:
              - integer
              - 'null'
              example: 69
            completion_to_frac_days:
              type:
              - integer
              - 'null'
              example: 9
            frac_to_first_prod_days:
              type:
              - integer
              - 'null'
              example: 52
        frac_focus:
          type: object
          properties:
            matched:
              type: boolean
              example: true
            disclosure_count:
              type: integer
              example: 1
            match_status:
              type: string
              enum:
              - no_match
              - exact_api_match
              - exact_api_match_missing_job_date
              - multiple_exact_api_matches
              - multiple_exact_api_matches_missing_primary_job_date
              example: exact_api_match
            match_confidence:
              type:
              - integer
              - 'null'
              example: 100
            primary_upload_key:
              type:
              - string
              - 'null'
              example: ff-upload-1
            job_start_date:
              type:
              - string
              - 'null'
              format: date
              example: '2024-03-10'
            job_end_date:
              type:
              - string
              - 'null'
              format: date
              example: '2024-03-12'
            water_gallons:
              type:
              - integer
              - 'null'
              format: int64
              example: 12750000
            non_water_gallons:
              type:
              - integer
              - 'null'
              format: int64
              example: 100
            chemical_count:
              type:
              - integer
              - 'null'
              example: 42
            source:
              type: string
              example: FracFocus
        source_coverage_status:
          type: string
          enum:
          - full_chain
          - permit_spud_production_no_completion
          - permit_completion_production_no_spud
          - permit_production_only
          - production_join_without_permit_date
          example: full_chain
        data_quality_flags:
          type: array
          items:
            type: string
          example:
          - missing_completion_date
        summary_generated_at:
          type: string
          format: date-time
    WellLifecycleStateAvailability:
      type: object
      properties:
        state:
          type: string
          example: TX
        status:
          type: string
          enum:
          - available
          - partial
          - repair_required
          - unavailable
          example: repair_required
        validation_status:
          type: string
          example: research_required
        success:
          type: boolean
          example: true
        reasons:
          type: array
          items:
            type: string
          example:
          - duplicate_source_records_need_state_policy
        metrics:
          type: object
          properties:
            permit_apis:
              type: integer
            production_matches:
              type: integer
            exact_match_rate_pct:
              type: number
            clean_permit_to_production_rate_pct:
              type: number
            chronology_error_rate_pct:
              type: number
        production_window:
          type:
          - object
          - 'null'
        scope:
          type: object
          properties:
            api_limit:
              type:
              - integer
              - 'null'
            bounded:
              type: boolean
        thresholds:
          type:
          - object
          - 'null'
        caveats:
          type: array
          items:
            type: string
        samples:
          type:
          - object
          - 'null'
        summary:
          $ref: '#/components/schemas/WellLifecycleStateSummary'
    WellLifecycleCohort:
      type: object
      properties:
        key:
          type: string
          example: Example Energy LLC
        well_count:
          type: integer
          example: 150
        cycle_time_stats:
          type: object
          properties:
            avg_permit_to_first_prod_days:
              type:
              - number
              - 'null'
              example: 126.8
            min_permit_to_first_prod_days:
              type:
              - number
              - 'null'
              example: 45
            max_permit_to_first_prod_days:
              type:
              - number
              - 'null'
              example: 260
            avg_permit_to_spud_days:
              type:
              - number
              - 'null'
              example: 45.2
            avg_spud_to_completion_days:
              type:
              - number
              - 'null'
              example: 58.7
            avg_completion_to_first_prod_days:
              type:
              - number
              - 'null'
              example: 21.4
            avg_permit_to_frac_days:
              type:
              - number
              - 'null'
              example: 69.2
            avg_completion_to_frac_days:
              type:
              - number
              - 'null'
              example: 8.7
            avg_frac_to_first_prod_days:
              type:
              - number
              - 'null'
              example: 52.1
    WellLifecycleStateSummary:
      type: object
      properties:
        status:
          type: string
          enum:
          - summary_available
          - summary_not_built
          - not_promoted
          example: summary_available
        summary_wells:
          type: integer
          example: 12450
        production_window:
          type:
          - object
          - 'null'
          properties:
            first_production_month:
              type:
              - string
              - 'null'
              format: date
              example: '2019-01-01'
            latest_production_month:
              type:
              - string
              - 'null'
              format: date
              example: '2026-04-01'
        cumulative:
          type:
          - object
          - 'null'
          properties:
            oil_bbl:
              type:
              - number
              - 'null'
              example: 1850000
            gas_mcf:
              type:
              - number
              - 'null'
              example: 4250000
            water_bbl:
              type:
              - number
              - 'null'
              example: 3100000
            boe:
              type:
              - number
              - 'null'
              example: 2558333.33
        coverage_statuses:
          type: object
          additionalProperties:
            type: integer
          example:
            full_chain: 11890
            permit_spud_production_no_completion: 560
        frac_focus:
          type: object
          properties:
            matched_wells:
              type: integer
              example: 10420
            match_rate_pct:
              type:
              - number
              - 'null'
              example: 83.7
            latest_job_start_date:
              type:
              - string
              - 'null'
              format: date
              example: '2026-07-10'
        summary_generated_at:
          type:
          - string
          - 'null'
          format: date-time
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code (e.g. UNAUTHORIZED, NOT_FOUND, INVALID_PARAMETER).
              example: UNAUTHORIZED
            message:
              type: string
              example: 'Missing or invalid API key. Include header: Authorization: Token YOUR_API_KEY'
            status:
              type: integer
              example: 401
            request_id:
              type: string
              example: fa0e389f-ca86-47b2-b167-2b4645a2fb8b
            docs:
              type: string
              example: https://docs.oilpriceapi.com#UNAUTHORIZED
            signup_url:
              type:
              - string
              - 'null'
              example: https://www.oilpriceapi.com/auth/signup
            demo_endpoint:
              type:
              - string
              - 'null'
              example: /v1/demo/prices
  responses:
    InternalServerError:
      description: Unexpected server error. Retry transient failures with bounded backoff and retain the request ID when contacting support.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'API key as: Authorization: Token YOUR_API_KEY'
externalDocs:
  description: OilPriceAPI developer documentation
  url: https://docs.oilpriceapi.com