Oil Price API Drilling Intelligence API

openapi: 3.2.0
info:
  title: Oil Price API V1 Drilling Intelligence 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: Drilling Intelligence
  description: Rig, permit, frac-spread, and drilling activity datasets.
paths:
  /v1/rig-counts/latest:
    get:
      summary: Get latest rig count data (simplified)
      operationId: getV1RigCountsLatest
      tags:
      - Drilling Intelligence
      description: 'Retrieve the latest rig count data in a simplified format.

        This endpoint returns the most recent US rig count with week-over-week and year-over-year changes.

        **Requires the Scale plan.**'
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Latest rig count data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RigCountLatestResponse'
        '403':
          description: Insufficient plan - Scale required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsufficientPlanError'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/rig-counts:
    get:
      summary: Get historical rig count data
      operationId: getV1RigCounts
      tags:
      - Drilling Intelligence
      description: 'Retrieve historical rig count data with filtering options.

        **Requires the Scale plan.**'
      parameters:
      - name: region
        in: query
        required: false
        description: Filter by region
        schema:
          type: string
          enum:
          - us
          - canada
          - international
          default: us
          example: us
      - name: start_date
        in: query
        required: false
        description: Start date (YYYY-MM-DD)
        schema:
          type: string
          format: date
          example: '2025-01-01'
      - name: end_date
        in: query
        required: false
        description: End date (YYYY-MM-DD)
        schema:
          type: string
          format: date
          example: '2025-08-10'
      - name: page
        in: query
        required: false
        description: Page number for pagination
        schema:
          type: integer
          minimum: 1
          default: 1
          example: 1
      - name: per_page
        in: query
        required: false
        description: Results per page (max 100)
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
          example: 100
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Historical rig count data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RigCountHistoricalResponse'
        '403':
          description: Insufficient plan - Scale required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsufficientPlanError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/drilling-intelligence:
    get:
      summary: Get the drilling intelligence summary
      operationId: getV1DrillingIntelligence
      tags:
      - Drilling Intelligence
      description: 'Compatibility alias for the cache-backed drilling intelligence summary.

        Prefer `/v1/drilling-intelligence/summary` for new integrations.

        **Requires the Scale plan.**'
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Drilling intelligence summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DrillingIntelligenceSummaryResponse'
        '401':
          description: Unauthorized - missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Insufficient plan - Scale required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsufficientPlanError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/drilling-intelligence/latest:
    get:
      summary: Get the latest drilling intelligence summary
      operationId: getV1DrillingIntelligenceLatest
      tags:
      - Drilling Intelligence
      description: 'Compatibility alias for `/v1/drilling-intelligence/summary`.

        **Requires the Scale plan.**'
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Latest drilling intelligence summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DrillingIntelligenceSummaryResponse'
        '401':
          description: Unauthorized - missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Insufficient plan - Scale required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsufficientPlanError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/drilling-intelligence/summary:
    get:
      summary: Get drilling intelligence summary
      operationId: getV1DrillingIntelligenceSummary
      tags:
      - Drilling Intelligence
      description: 'Get latest data points for each category in a consolidated summary view.

        **Requires the Scale plan.**'
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Drilling intelligence summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DrillingIntelligenceSummaryResponse'
        '401':
          description: Unauthorized - missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Insufficient plan - Scale required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsufficientPlanError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/drilling/latest:
    get:
      summary: Get latest drilling intelligence summary (compatibility alias)
      operationId: getV1DrillingLatest
      tags:
      - Drilling Intelligence
      description: 'Backward-compatible SDK alias for the cached drilling intelligence summary payload.

        Prefer `/v1/drilling-intelligence/summary` for new integrations.

        **Requires the Scale plan.**'
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Latest drilling intelligence summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DrillingIntelligenceSummaryResponse'
        '401':
          description: Unauthorized - missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Insufficient plan - Scale required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsufficientPlanError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/drilling-intelligence/frac-spreads:
    get:
      summary: Get frac spreads data
      operationId: getV1DrillingIntelligenceFracSpreads
      tags:
      - Drilling Intelligence
      description: 'Get the latest national frac-spread count and any available legacy

        basin series.

        **Requires the Scale plan.**'
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Frac spreads data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FracSpreadsResponse'
        '401':
          description: Unauthorized - missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Insufficient plan - Scale required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsufficientPlanError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/drilling-intelligence/well-permits:
    get:
      summary: Get well permits data
      operationId: getV1DrillingIntelligenceWellPermits
      tags:
      - Drilling Intelligence
      description: 'Get recent drilling permits with bounded pagination and an optional

        state filter.

        **Requires the Scale plan.**'
      parameters:
      - name: state_code
        in: query
        required: false
        description: Two-letter US state code
        schema:
          type: string
          minLength: 2
          maxLength: 2
          example: TX
      - name: days
        in: query
        required: false
        description: Lookback window in days (clamped to 1-365)
        schema:
          type: integer
          minimum: 1
          maximum: 365
          default: 30
          example: 30
      - name: page
        in: query
        required: false
        description: Page number for pagination
        schema:
          type: integer
          minimum: 1
          default: 1
          example: 1
      - name: per_page
        in: query
        required: false
        description: Results per page (max 200)
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
          example: 50
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Well permits data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WellPermitsResponse'
        '401':
          description: Unauthorized - missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Insufficient plan - Scale required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsufficientPlanError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/drilling-intelligence/duc-wells:
    get:
      summary: Get DUC wells data
      operationId: getV1DrillingIntelligenceDucWells
      tags:
      - Drilling Intelligence
      description: 'Get the latest EIA drilled-but-uncompleted well inventory by basin.

        **Requires the Scale plan.**'
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: DUC wells data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DrillingBasinSeriesResponse'
        '401':
          description: Unauthorized - missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Insufficient plan - Scale required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsufficientPlanError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/drilling-intelligence/completions:
    get:
      summary: Get wells completed by basin
      operationId: getV1DrillingIntelligenceCompletions
      tags:
      - Drilling Intelligence
      description: 'Get the latest EIA wells-completed series by basin.

        **Requires the Scale plan.**'
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Latest wells completed by basin
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DrillingBasinSeriesResponse'
        '401':
          description: Unauthorized - missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Insufficient plan - Scale required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsufficientPlanError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/drilling-intelligence/wells-drilled:
    get:
      summary: Get wells drilled by basin
      operationId: getV1DrillingIntelligenceWellsDrilled
      tags:
      - Drilling Intelligence
      description: 'Get the latest EIA wells-drilled series by basin.

        **Requires the Scale plan.**'
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Latest wells drilled by basin
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DrillingBasinSeriesResponse'
        '401':
          description: Unauthorized - missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Insufficient plan - Scale required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsufficientPlanError'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    DrillingBasinSeriesResponse:
      type: object
      required:
      - status
      - data
      properties:
        status:
          type: string
          example: success
        data:
          type: object
          required:
          - summary
          properties:
            duc_wells:
              type: array
              items:
                $ref: '#/components/schemas/DrillingDataPoint'
            completions:
              type: array
              items:
                $ref: '#/components/schemas/DrillingDataPoint'
            wells_drilled:
              type: array
              items:
                $ref: '#/components/schemas/DrillingDataPoint'
            summary:
              type: object
              required:
              - total
              - by_basin
              - last_updated
              properties:
                total:
                  type: number
                  example: 2815
                by_basin:
                  type: object
                  additionalProperties:
                    type: number
                  example:
                    PERMIAN: 893
                    BAKKEN: 420
                last_updated:
                  type:
                  - string
                  - 'null'
                  format: date-time
    WellPermitsResponse:
      type: object
      required:
      - status
      - data
      properties:
        status:
          type: string
          example: success
        data:
          type: object
          required:
          - well_permits
          - summary
          - pagination
          properties:
            well_permits:
              type: array
              items:
                type: object
                properties:
                  api_number:
                    type: string
                  state:
                    type: string
                    example: TX
                  county:
                    type:
                    - string
                    - 'null'
                  operator:
                    type:
                    - string
                    - 'null'
                  permit_number:
                    type:
                    - string
                    - 'null'
                  permit_type:
                    type:
                    - string
                    - 'null'
                  permit_status:
                    type:
                    - string
                    - 'null'
                  permit_date:
                    type:
                    - string
                    - 'null'
                    format: date
                  approval_date:
                    type:
                    - string
                    - 'null'
                    format: date
                  spud_date:
                    type:
                    - string
                    - 'null'
                    format: date
                  well_name:
                    type:
                    - string
                    - 'null'
                  latitude:
                    type:
                    - number
                    - 'null'
                  longitude:
                    type:
                    - number
                    - 'null'
            summary:
              type: object
              properties:
                total:
                  type: integer
                by_state:
                  type: object
                  additionalProperties:
                    type: integer
                days:
                  type: integer
                last_updated:
                  type:
                  - string
                  - 'null'
                  format: date-time
            pagination:
              type: object
              properties:
                page:
                  type: integer
                per_page:
                  type: integer
                total:
                  type: integer
                total_pages:
                  type: integer
    FracSpreadsResponse:
      type: object
      required:
      - status
      - data
      properties:
        status:
          type: string
          example: success
        data:
          type: object
          required:
          - frac_spreads
          - summary
          properties:
            frac_spreads:
              type: array
              items:
                $ref: '#/components/schemas/DrillingDataPoint'
            summary:
              type: object
              properties:
                national_count:
                  type:
                  - integer
                  - 'null'
                  example: 196
                by_basin:
                  type: object
                  additionalProperties:
                    type: number
                last_updated:
                  type:
                  - string
                  - 'null'
                  format: date-time
    RigCountHistoricalResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        rig_counts:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                example: US_RIG_COUNT
              region:
                type: string
                example: United States
              count:
                type: integer
                example: 540
              unit:
                type: string
                example: rigs
              source:
                type: string
                example: baker_hughes
              created_at:
                type: string
                format: date-time
                example: '2025-08-02T20:15:00Z'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    PaginationMeta:
      type: object
      properties:
        current_page:
          type: integer
          example: 1
        per_page:
          type: integer
          example: 100
        total_pages:
          type: integer
          example: 5
        total_count:
          type: integer
          example: 450
        next_page:
          type:
          - integer
          - 'null'
          example: 2
        prev_page:
          type:
          - integer
          - 'null'
          example: null
    InsufficientPlanError:
      type: object
      properties:
        status:
          type: string
          example: error
        error:
          type: object
          properties:
            code:
              type: string
              example: INSUFFICIENT_PLAN
            message:
              type: string
              example: Drilling intelligence data is available exclusively to Scale subscribers
            details:
              type: object
              properties:
                required_tier:
                  type: string
                  example: reservoir_mastery
                upgrade_url:
                  type: string
                  example: https://oilpriceapi.com/pricing
                current_plan:
                  type: string
                  example: free
    DrillingDataPoint:
      type: object
      required:
      - code
      - name
      - value
      - unit
      - source
      - created_at
      - formatted_date
      properties:
        code:
          type: string
          example: US_RIG_COUNT
        name:
          type: string
          example: US Rig Count
        value:
          type: number
          example: 540
        unit:
          type: string
          example: rigs
        source:
          type: string
          example: Baker Hughes
        created_at:
          type: string
          format: date-time
          example: '2026-07-27T00:00:00Z'
        formatted_date:
          type: string
          example: 2026-07-27 00:00:00 UTC
    RigCountLatestResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        data:
          type: object
          properties:
            code:
              type: string
              example: US_RIG_COUNT
            region:
              type: string
              example: United States
            count:
              type: integer
              example: 540
            unit:
              type: string
              example: rigs
            source:
              type: string
              example: baker_hughes
            created_at:
              type: string
              format: date-time
              example: '2025-08-02T20:15:00Z'
            week_over_week_change:
              type: integer
              example: -5
            year_over_year_change:
              type: integer
              example: 45
    DrillingIntelligenceSummaryResponse:
      type: object
      required:
      - status
      - data
      properties:
        status:
          type: string
          example: success
        data:
          type: object
          required:
          - rig_counts
          - frac_spread_count
          - well_permits
          - duc_wells_total
          - deltas
          - last_updated
          properties:
            rig_counts:
              type: object
              additionalProperties:
                type: integer
              example:
                US_RIG_COUNT: 587
                CANADA_RIG_COUNT: 204
                INTERNATIONAL_RIG_COUNT: 1073
            frac_spread_count:
              type:
              - integer
              - 'null'
              example: 196
            well_permits:
              type: object
              properties:
                last_30d:
                  type: integer
                  example: 671
                by_state:
                  type: object
                  additionalProperties:
                    type: integer
            duc_wells_total:
              type: integer
              example: 2421
            deltas:
              type: object
              additionalProperties: true
            last_updated:
              type:
              - string
              - 'null'
              format: date-time
              example: '2026-07-27T00:00:00Z'
    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