Well Production API Reference

All endpoints are under https://api.oilpriceapi.com/v1/well-production. Authentication is required. Prefer Authorization: Token YOUR_API_KEY; api_key query parameters are also accepted.

Well production is in beta. Treat /summary as the source of truth for live coverage before relying on a state-level or well-level query.

GET /v1/well-production

Alias for GET /v1/well-production/summary.

curl "https://api.oilpriceapi.com/v1/well-production" \
  -H "Authorization: Token YOUR_API_KEY"

GET /v1/well-production/summary

Return national summary data, top state aggregates, source metadata, and current coverage.

curl "https://api.oilpriceapi.com/v1/well-production/summary" \
  -H "Authorization: Token YOUR_API_KEY"

Response Shape

{
  "status": "success",
  "data": {
    "national": null,
    "top_states": [
      {
        "state": "TX",
        "period": "2026-04",
        "oil_bbl": 174743000,
        "oil_bpd": 5824767,
        "gas_mcf": 1164406000,
        "boe": 368810667
      }
    ],
    "data_sources": {
      "state_aggregates": "EIA API v2 (monthly)",
      "well_level": "State regulatory agencies",
      "well_level_states": ["TX", "AK", "NM", "ND"],
      "national_rollup": "Derived from collected well-level state rows"
    },
    "coverage": {
      "states_with_data": ["AK", "AR", "CA", "CO", "TX"],
      "well_level_states_with_data": ["AK", "ND", "TX"],
      "latest_period": "2026-04",
      "total_records": 597499
    }
  }
}

Coverage Fields

GET /v1/well-production/states

Return latest state aggregate production rows. These are state-level totals, not well-level records.

Parameters

curl "https://api.oilpriceapi.com/v1/well-production/states?period=2026-04" \
  -H "Authorization: Token YOUR_API_KEY"

Response Shape

{
  "status": "success",
  "data": {
    "period": "2026-04",
    "count": 28,
    "states": [
      {
        "state": "TX",
        "period": "2026-04",
        "oil_bbl": 174743000,
        "oil_bpd": 5824767,
        "gas_mcf": 1164406000,
        "boe": 368810667
      }
    ]
  }
}

GET /v1/well-production/states/{state_code}

Return state aggregate production history for one state.

Parameters

curl "https://api.oilpriceapi.com/v1/well-production/states/TX?start_date=2025-06-01&end_date=2026-04-30" \
  -H "Authorization: Token YOUR_API_KEY"

Returns DATA_NOT_AVAILABLE with HTTP 404 when the state has no aggregate rows for the requested period.

GET /v1/well-production/wells/{api_number}

Return well-level production history for one 14-digit API number.

Parameters

curl "https://api.oilpriceapi.com/v1/well-production/wells/42461410190000" \
  -H "Authorization: Token YOUR_API_KEY"

Returns INVALID_PARAMETER with HTTP 400 for API numbers that are not 14 digits, and DATA_NOT_AVAILABLE with HTTP 404 when no well-level rows exist for that well.

GET /v1/well-production/top-producers

Return top producing wells for a state over a rolling month window.

Parameters

curl "https://api.oilpriceapi.com/v1/well-production/top-producers?state_code=ND&months=3&limit=10" \
  -H "Authorization: Token YOUR_API_KEY"

Response Shape

{
  "status": "success",
  "data": {
    "state": "ND",
    "period": {
      "start": "2026-04-01",
      "end": "2026-07-04"
    },
    "count": 10,
    "producers": [
      {
        "api_number": "33025012340000",
        "operator": "Example Operator",
        "well_name": "Example 1H",
        "total_oil_bbl": 12345,
        "total_gas_mcf": 67890,
        "months_producing": 1
      }
    ]
  }
}

GET /v1/well-production/cycle-time

Analyze permit-to-production cycle time using joined permit and production data.

Parameters

curl "https://api.oilpriceapi.com/v1/well-production/cycle-time?state=TX&start_date=2025-01-01" \
  -H "Authorization: Token YOUR_API_KEY"

Returns DATA_NOT_AVAILABLE with HTTP 404 when the filters do not produce an analysis result.

GET /v1/well-production/cycle-time/cohorts

Compare permit-to-production cycle time across cohorts.

Parameters

curl "https://api.oilpriceapi.com/v1/well-production/cycle-time/cohorts?state=TX&group_by=quarter" \
  -H "Authorization: Token YOUR_API_KEY"

Access and Coverage Notes

• Aggregate endpoints — summary, states, states/{state_code}, cycle-time, cycle-time/cohorts — are available on every plan, including free, subject to your plan's standard request limits.
• Well-level endpoints — wells/{api_number} and top-producers — require drilling-intelligence access on the Scale plan.
• states endpoints are state aggregates from EIA and may have broader coverage than well-level endpoints.
• wells/{api_number} and top-producers only return states that appear in coverage.well_level_states_with_data.
• Registered scrapers can exist before a state has production-green rows. Do not infer coverage from the registered worker list alone.

Related

• Overview
• Well Permits
• Drilling Productivity