Oil Price API Well Production API

openapi: 3.2.0
info:
  title: Oil Price API V1 Well Production 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 Production
  description: Well production data and operational analytics.
paths:
  /v1/well-production:
    get:
      summary: Well production summary
      operationId: getV1WellProduction
      tags:
      - Well Production
      description: 'National and top-state oil/gas production summary. Sourced from state regulators

        (TX RRC, NM OCD, ND NDIC, AOGCC) and EIA.'
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Production summary
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  data:
                    type: object
                    properties:
                      national:
                        type:
                        - object
                        - 'null'
                      top_states:
                        type: array
                        items:
                          $ref: '#/components/schemas/StateProduction'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/well-production/summary:
    get:
      summary: Well production summary
      operationId: getV1WellProductionSummary
      tags:
      - Well Production
      description: 'Alias for `/v1/well-production`. Returns the national and top-state oil/gas

        production summary from state regulators and EIA.'
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Production summary
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  data:
                    type: object
                    properties:
                      national:
                        type:
                        - object
                        - 'null'
                      top_states:
                        type: array
                        items:
                          $ref: '#/components/schemas/StateProduction'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/well-production/states:
    get:
      summary: List states with production data
      operationId: getV1WellProductionStates
      description: List states with available well-production coverage and their latest available period.
      tags:
      - Well Production
      security:
      - ApiKeyAuth: []
      parameters:
      - name: period
        in: query
        required: false
        description: Optional production month in YYYY-MM format; defaults to the latest available month.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}$
        example: 2026-07
      responses:
        '200':
          description: States with available production data
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  data:
                    type: object
                    properties:
                      period:
                        type:
                        - string
                        - 'null'
                        example: 2026-07
                      count:
                        type: integer
                      states:
                        type: array
                        items:
                          type: object
                          properties:
                            state:
                              type: string
                              example: TX
                            period:
                              type: string
                              example: 2026-07
                            oil_bbl:
                              type:
                              - number
                              - 'null'
                            oil_bpd:
                              type:
                              - number
                              - 'null'
                            gas_mcf:
                              type:
                              - number
                              - 'null'
                            boe:
                              type:
                              - number
                              - 'null'
                            well_level:
                              type: object
                              description: Coverage of per-well rows, separate from EIA state aggregate coverage.
                              properties:
                                status:
                                  type: string
                                  enum:
                                  - available
                                  - not_covered
                                latest_period:
                                  type:
                                  - string
                                  - 'null'
                                  example: 2026-07
                                row_count:
                                  type: integer
                                well_count:
                                  type: integer
                                snapshot_generated_at:
                                  type:
                                  - string
                                  - 'null'
                                  format: date-time
        '400':
          description: Invalid period; use YYYY-MM.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/well-production/states/{state_code}:
    get:
      summary: Monthly production time series for a state
      operationId: getV1WellProductionStatesByStateCode
      description: Retrieve the monthly well-production time series for one covered state.
      tags:
      - Well Production
      security:
      - ApiKeyAuth: []
      parameters:
      - name: state_code
        in: path
        required: true
        description: Two-letter state code (e.g. TX, NM, ND, AK).
        schema:
          type: string
          example: TX
        example: TX
      responses:
        '200':
          description: Monthly production series
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  data:
                    type: object
                    properties:
                      state:
                        type: string
                        example: TX
                      period:
                        type: object
                        properties:
                          start:
                            type: string
                            format: date
                          end:
                            type: string
                            format: date
                      count:
                        type: integer
                      data:
                        type: array
                        items:
                          type: object
                          properties:
                            period:
                              type: string
                              example: 2025-06
                            oil_bbl:
                              type:
                              - number
                              - 'null'
                            gas_mcf:
                              type:
                              - number
                              - 'null'
                            water_bbl:
                              type:
                              - number
                              - 'null'
                            boe:
                              type:
                              - number
                              - 'null'
                            days_producing:
                              type:
                              - integer
                              - 'null'
                            source:
                              type: string
                              example: eia_api
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/well-production/wells/{api_number}:
    get:
      summary: Production for a single well
      operationId: getV1WellProductionWellsByApiNumber
      tags:
      - Well Production
      description: Production history for a single well by its 14-digit API well number.
      security:
      - ApiKeyAuth: []
      parameters:
      - name: api_number
        in: path
        required: true
        description: 14-digit API well number.
        schema:
          type: string
        example: '42329447130000'
      responses:
        '200':
          description: Well production history
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  data:
                    type: object
        '400':
          description: API number is not 14 digits (`{"error":{"code":"INVALID_PARAMETER",...}}`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Well not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/well-production/top-producers:
    get:
      summary: Top producing wells
      operationId: getV1WellProductionTopProducers
      tags:
      - Well Production
      description: 'Highest-producing wells over the trailing period, optionally scoped to a state.

        Defaults to TX and the trailing 12 months. Returns 404 with an explicit

        reason when well-level coverage is absent or outside the requested window.'
      security:
      - ApiKeyAuth: []
      parameters:
      - name: state_code
        in: query
        required: false
        description: Two-letter state code. Use either state_code or its state alias; conflicting values return 400.
        schema:
          type: string
          pattern: ^[A-Za-z]{2}$
          default: TX
        example: TX
      - name: state
        in: query
        required: false
        description: Alias for state_code. Conflicting values return 400.
        schema:
          type: string
          pattern: ^[A-Za-z]{2}$
        example: TX
      - name: limit
        in: query
        required: false
        description: Maximum wells returned; clamped to 1–100.
        schema:
          type: integer
          default: 20
        example: 20
      - name: months
        in: query
        required: false
        description: Lookback window in months; defaults to 12.
        schema:
          type: integer
          default: 12
        example: 12
      responses:
        '200':
          description: Top producers
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  data:
                    type: object
                    properties:
                      state:
                        type: string
                        example: TX
                      period:
                        type: object
                        properties:
                          start:
                            type: string
                            format: date
                          end:
                            type: string
                            format: date
                      count:
                        type: integer
                      producers:
                        type: array
                        items:
                          type: object
                          properties:
                            api_number:
                              type: string
                            operator:
                              type:
                              - string
                              - 'null'
                            well_name:
                              type:
                              - string
                              - 'null'
                            total_oil_bbl:
                              type:
                              - number
                              - 'null'
                            total_gas_mcf:
                              type:
                              - number
                              - 'null'
                            months_producing:
                              type: integer
        '400':
          description: 'UNKNOWN_PARAMETERS for an unrecognized query name, or INVALID_PARAMETER

            for malformed or conflicting state/state_code values.

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                        - UNKNOWN_PARAMETERS
                        - INVALID_PARAMETER
                      message:
                        type: string
                      status:
                        type: integer
                        example: 400
                      unrecognized_parameters:
                        type: array
                        items:
                          type: string
                      allowed_parameters:
                        type: array
                        items:
                          type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The current plan lacks well-level Drilling Intelligence access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Well-level data is unavailable for the state or requested time window.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                        - DATA_NOT_AVAILABLE
                      message:
                        type: string
                      status:
                        type: integer
                        example: 404
                      reason:
                        type: string
                        enum:
                        - state_not_covered
                        - no_rows_in_period
                      well_level_status:
                        type: string
                        enum:
                        - not_covered
                        - outside_window
                      state:
                        type: string
                      latest_production_month:
                        type:
                        - string
                        - 'null'
                        example: 2026-07
                      suggested_months:
                        type: integer
                        description: Present when increasing the window can include the latest month.
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/well-production/cycle-time:
    get:
      summary: Well cycle-time statistics
      operationId: getV1WellProductionCycleTime
      tags:
      - Well Production
      description: 'Aggregate spud-to-completion and completion-to-production cycle-time statistics

        (median, percentiles) across wells, with optional filters.'
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Cycle-time statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  data:
                    type: object
                    properties:
                      filters:
                        type: object
                      well_count:
                        type: integer
                        example: 10000
                      wells_with_cycle_data:
                        type: integer
                        example: 45
                      cycle_time_stats:
                        $ref: '#/components/schemas/CycleTimeStats'
                      stage_breakdown:
                        type: object
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/well-production/cycle-time/cohorts:
    get:
      summary: Cycle-time by cohort
      operationId: getV1WellProductionCycleTimeCohorts
      tags:
      - Well Production
      description: Cycle-time statistics grouped into cohorts (e.g. by spud quarter).
      security:
      - ApiKeyAuth: []
      parameters:
      - name: group_by
        in: query
        required: false
        description: Cohort grouping (e.g. `quarter`).
        schema:
          type: string
          default: quarter
          example: operator
      responses:
        '200':
          description: Cohort cycle-time statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  data:
                    type: object
                    properties:
                      group_by:
                        type: string
                        example: quarter
                      cohorts:
                        type: object
                        additionalProperties:
                          type: object
                          properties:
                            well_count:
                              type: integer
                            wells_with_data:
                              type: integer
                            stats:
                              $ref: '#/components/schemas/CycleTimeStats'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    CycleTimeStats:
      type: object
      properties:
        count:
          type: integer
          example: 45
        median_days:
          type: number
          example: 30
        p25_days:
          type: number
          example: 20
        p75_days:
          type: number
          example: 50
        p90_days:
          type: number
          example: 133
        min_days:
          type: number
          example: 1
        max_days:
          type: number
          example: 332
        avg_days:
          type: number
          example: 52
    StateProduction:
      type: object
      properties:
        state:
          type: string
          example: TX
        period:
          type: string
          example: 2026-03
        oil_bbl:
          type:
          - number
          - 'null'
          example: 179126000
        oil_bpd:
          type:
          - number
          - 'null'
          example: 5778258
        gas_mcf:
          type:
          - number
          - 'null'
        boe:
          type:
          - number
          - 'null'
          example: 179126000
    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