---
title: "Top producing wells"
method: GET
path: "/v1/well-production/top-producers"
tags: ["Well Production"]
---

# Top producing wells

`GET /v1/well-production/top-producers`

## Request

- Base URL: `https://api.oilpriceapi.com`
- URL: `https://api.oilpriceapi.com/v1/well-production/top-producers`
- Auth: API key in header `Authorization`

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.

## Query parameters

- `state_code` string
- `state` string
- `limit` integer
- `months` integer

## Response `200`

Top producers

- object
  - `status` string
  - `data` object
    - `state` string
    - `period` object
      - `start` string, date
      - `end` string, date
    - `count` integer
    - `producers` object[]
      - `api_number` string
      - `operator` string, nullable
      - `well_name` string, nullable
      - `total_oil_bbl` number, nullable
      - `total_gas_mcf` number, nullable
      - `months_producing` integer

## Other responses

- `400`: UNKNOWN_PARAMETERS for an unrecognized query name, or INVALID_PARAMETER for malformed or conflicting state/state_code values.
- `401`: Unauthorized
- `403`: The current plan lacks well-level Drilling Intelligence access.
- `404`: Well-level data is unavailable for the state or requested time window.
- `500`: Unexpected server error. Retry transient failures with bounded backoff and retain the request ID when contacting support.

## Changes

- **2026-10-26** `9e633619fedf`: 1 breaking, 8 info
  - added the pattern `^[A-Za-z]{2}$` to the `query` request parameter `state`
  - added the new optional `query` request parameter `limit`
  - added the new optional `query` request parameter `months`
  - added the new optional `query` request parameter `state_code`
  - …5 more

[Operation history](https://skmtc.dev/oilpriceapi/apis/oil-price-api-v1/changes/v1/well-production/top-producers/get.md)

---

[API](https://skmtc.dev/oilpriceapi/apis/oil-price-api-v1.md) - [All operations](https://skmtc.dev/oilpriceapi/apis/oil-price-api-v1/llms.txt) - [OpenAPI document](https://skmtc.dev/oilpriceapi/apis/oil-price-api-v1/revisions/7f8b4d763210?raw)