Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Buckhead Energy Public State API
version: 3.0.0
description: 'Read-only JSON over oil & gas metrics Buckhead Energy computes: state and county drilling-activity counts, permit-to-spud and spud-to-production cycle times, DUC aging, lateral-length trends, production bands, county momentum scores, operator leaderboards by wells operated, and county / formation leaderboards. Designed for AI agents, partner integrations, and custom data consumers.
Coverage: 24 U.S. states (TX, OK, NM, ND, CO, WY, CA, KS, MS, UT, IL, MT, AL, AR, IN, KY, LA, MI, NE, OH, PA, SD, TN, WV). Figures are Buckhead Energy analysis of public oil and gas data. The derived metrics (activity counts, cycle times, DUC aging, lateral trends, production bands, momentum) and the leaderboards are recomputed daily; the county production volumes that momentum reads are updated monthly.
**Aggregates only.** The API never returns per-well records (no API numbers, well or lease names) and never returns commodity prices. Every list is capped at 25 rows.
**Drilling activity by state and county only.** Permits, spuds, first production, DUCs, cycle times and lateral trends are published only as state and county counts. No drilling-activity figure is attributed to an operator, and nothing is finer than a county. Operator endpoints return wells operated and producing wells. Counts resting on fewer than 3 wells, and percentiles resting on fewer than 5, are withheld (null).
**No authentication required.** Subject to standard rate-limiting (100 req/min per IP, 5,000 req/day per IP, 10 concurrent per IP). The daily limit is shared by REST and MCP, and both limits apply across all server instances. Responses include X-Request-ID and X-RateLimit-* headers; 429 includes Retry-After. Responses are bounded to 1 MiB and 5,000 array entries, with a 15-second execution deadline.'
contact:
name: Buckhead Energy
url: https://www.buckheadenergy.com/
email: land@buckheadenergy.com
servers:
- url: https://www.buckheadenergy.com/api/v1
description: Production
tags:
- name: State
description: 'State-level metrics: activity, cycle times, DUC aging, lateral trends, production bands, momentum, leaderboards'
paths:
/us-drilling-activity-index:
get:
tags:
- State
summary: National drilling-activity rollup
description: 'Per-state activity counts (12-month permits, DUCs, 12-month spuds, 12-month first production, active counties) and national totals. A state figure that is withheld (fewer than 3 wells) or unavailable is null, never 0. Each national total adds only the known state values: `totals.partial` is true when any state is missing and `totals.statesMissing.` lists the state codes left out (the total is then a floor); a metric with no known state value is null. Machine-readable twin of /us-drilling-activity-index.'
responses:
'200':
description: National totals plus per-state rows
content:
application/json:
schema:
type: object
properties:
data:
type: object
meta:
$ref: '#/components/schemas/Meta'
operationId: getUsDrillingActivityIndex
/state/{state}/snapshot:
get:
tags:
- State
summary: State oil & gas activity snapshot (aggregates)
description: Aggregate state counts plus the top operators by wells operated, top counties and formations. No per-well lists and no drilling activity attributed to an operator.
parameters:
- $ref: '#/components/parameters/State'
responses:
'200':
description: State snapshot
content:
application/json:
schema:
$ref: '#/components/schemas/SnapshotEnvelope'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
operationId: getStateSnapshot
/state/{state}/operators:
get:
tags:
- State
summary: Top operators leaderboard by total well count
parameters:
- $ref: '#/components/parameters/State'
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: Operator leaderboard
content:
application/json:
schema:
$ref: '#/components/schemas/OperatorLeaderboardEnvelope'
operationId: getTopOperators
description: Operators ranked by total wells operated, with producing-well counts. No drilling activity (permits, spuds, DUCs) is attributed to an operator.
/state/{state}/counties:
get:
tags:
- State
summary: County-level drilling activity rankings (top 25)
parameters:
- $ref: '#/components/parameters/State'
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: County rankings
content:
application/json:
schema:
$ref: '#/components/schemas/CountyListEnvelope'
operationId: getCountyDrillingActivity
/state/{state}/activity:
get:
tags:
- State
summary: State drilling-activity metrics
description: Monthly permits, spuds and first-production counts (last 24 months), 12-month totals and the top 25 counties. State and county counts only.
parameters:
- $ref: '#/components/parameters/State'
responses:
'200':
description: State drilling-activity metrics
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
state:
type: string
monthly:
type: array
maxItems: 24
items:
$ref: '#/components/schemas/MonthlyActivity'
totals12:
type:
- object
- 'null'
description: null when drilling counts are held
counties:
type: array
maxItems: 25
items:
type: object
held:
$ref: '#/components/schemas/HeldDrilling/properties/held'
reason:
$ref: '#/components/schemas/HeldDrilling/properties/reason'
note:
$ref: '#/components/schemas/HeldDrilling/properties/note'
meta:
$ref: '#/components/schemas/Meta'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
operationId: getStateActivity
/state/{state}/cycle-times:
get:
tags:
- State
summary: Permit-to-spud and spud-to-production cycle times
description: Days from permit to spud and from spud to first production (25th / 50th / 75th percentile) and permit conversion, for the state and its top 25 counties.
parameters:
- $ref: '#/components/parameters/State'
responses:
'200':
description: Permit-to-spud and spud-to-production cycle times
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
state:
allOf:
- $ref: '#/components/schemas/CycleTimes'
description: null when drilling counts are held
type:
- object
- 'null'
counties:
type: array
maxItems: 25
items:
$ref: '#/components/schemas/CycleTimes'
held:
$ref: '#/components/schemas/HeldDrilling/properties/held'
reason:
$ref: '#/components/schemas/HeldDrilling/properties/reason'
note:
$ref: '#/components/schemas/HeldDrilling/properties/note'
meta:
$ref: '#/components/schemas/Meta'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
operationId: getCycleTimes
/state/{state}/duc-aging:
get:
tags:
- State
summary: Drilled-but-uncompleted (DUC) inventory aging
description: DUC count and age percentiles (days since spud) for the state and its top 25 counties, plus the 24-month backlog trend.
parameters:
- $ref: '#/components/parameters/State'
responses:
'200':
description: Drilled-but-uncompleted (DUC) inventory aging
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
state:
$ref: '#/components/schemas/DucAging'
counties:
type: array
maxItems: 25
items:
$ref: '#/components/schemas/DucAging'
backlog:
type: array
maxItems: 24
items:
type: object
properties:
month:
type: string
ducCount:
type:
- integer
- 'null'
medianAge:
type:
- integer
- 'null'
backlogChange:
type:
- object
- 'null'
meta:
$ref: '#/components/schemas/Meta'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
operationId: getDucAging
/state/{state}/lateral-trends:
get:
tags:
- State
summary: Formation mix and median lateral length by year
description: Share of permits and median lateral length (feet) by year for the state's leading formations.
parameters:
- $ref: '#/components/parameters/State'
responses:
'200':
description: Formation mix and median lateral length by year
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
formations:
type: array
items:
type: string
years:
type: array
maxItems: 25
items:
type: object
held:
$ref: '#/components/schemas/HeldDrilling/properties/held'
reason:
$ref: '#/components/schemas/HeldDrilling/properties/reason'
note:
$ref: '#/components/schemas/HeldDrilling/properties/note'
meta:
$ref: '#/components/schemas/Meta'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
operationId: getLateralTrends
/state/{state}/production-bands:
get:
tags:
- State
summary: Producing wells by monthly-volume band
description: Count of producing wells in each monthly oil and gas volume band, and the top 25 counties where the highest-volume wells concentrate.
parameters:
- $ref: '#/components/parameters/State'
responses:
'200':
description: Producing wells by monthly-volume band
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
month:
type: string
oil:
type: array
items:
type: object
properties:
band:
type: integer
label:
type: string
wells:
type:
- integer
- 'null'
gas:
type: array
items:
type: object
topCounties:
type: array
maxItems: 25
items:
type: object
meta:
$ref: '#/components/schemas/Meta'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
operationId: getProductionBands
/state/{state}/momentum:
get:
tags:
- State
summary: County momentum scores (top 25)
description: Counties ranked by momentum score = 100 x (permits, last 12 months / prior 12) x (BOE production, last 12 months / prior 12). Above 100 = accelerating.
parameters:
- $ref: '#/components/parameters/State'
responses:
'200':
description: County momentum scores (top 25)
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
counties:
type: array
maxItems: 25
items:
allOf:
- $ref: '#/components/schemas/Momentum'
type: object
properties:
countySlug:
type: string
countyName:
type: string
held:
$ref: '#/components/schemas/HeldDrilling/properties/held'
reason:
$ref: '#/components/schemas/HeldDrilling/properties/reason'
note:
$ref: '#/components/schemas/HeldDrilling/properties/note'
meta:
$ref: '#/components/schemas/Meta'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
operationId: getStateMomentum
components:
schemas:
HeldDrilling:
type: object
description: Present when the state's drilling counts are held while the source is reconciled with state records (e.g. Oklahoma). Drilling fields are then null or empty; they are never zero-filled.
properties:
held:
type: boolean
enum:
- true
reason:
type: string
enum:
- reconciling-with-state-records
note:
type: string
MonthlyActivity:
type: object
description: One month of counts. Series are a fixed calendar of the 24 complete months before the current month; a count below 3 is withheld (null), and a month with no published count is a null cell (never omitted).
properties:
month:
type: string
example: 2026-07
permits:
type:
- integer
- 'null'
spuds:
type:
- integer
- 'null'
firstProd:
type:
- integer
- 'null'
Error:
type: object
properties:
error:
type: object
properties:
status:
type: integer
message:
type: string
meta:
$ref: '#/components/schemas/Meta'
Percentiles:
type: object
description: Days; a percentile resting on fewer than 5 wells is withheld (null).
properties:
n:
type:
- integer
- 'null'
p25:
type:
- number
- 'null'
p50:
type:
- number
- 'null'
p75:
type:
- number
- 'null'
CountyListEnvelope:
type: object
properties:
data:
type: array
maxItems: 25
items:
type: object
properties:
recentPermitCount:
type:
- integer
- 'null'
description: Absent while the state's drilling counts are held.
recentSpudCount:
type:
- integer
- 'null'
description: Absent while the state's drilling counts are held.
drillingHeld:
type:
- object
- 'null'
description: Held marker (held, reason, note, since, regulator) on each row of a held state.
properties:
held:
$ref: '#/components/schemas/HeldDrilling/properties/held'
reason:
$ref: '#/components/schemas/HeldDrilling/properties/reason'
note:
$ref: '#/components/schemas/HeldDrilling/properties/note'
since:
type: string
regulator:
type: object
meta:
allOf:
- $ref: '#/components/schemas/Meta'
type: object
description: held / reason / note are present when the state's permit and spud counts are held; rows then omit recentPermitCount and recentSpudCount.
properties:
held:
$ref: '#/components/schemas/HeldDrilling/properties/held'
reason:
$ref: '#/components/schemas/HeldDrilling/properties/reason'
note:
$ref: '#/components/schemas/HeldDrilling/properties/note'
Meta:
type: object
properties:
apiVersion:
type: string
example: '1.0'
dataAsOf:
type:
- string
- 'null'
format: date
description: Date the underlying metrics were last refreshed
source:
type: string
description: Attribution
example: Buckhead Energy analysis of public oil and gas data
OperatorLeaderboardEnvelope:
type: object
properties:
data:
type: array
maxItems: 25
items:
type: object
meta:
$ref: '#/components/schemas/Meta'
CycleTimes:
type: object
properties:
state:
type: string
countySlug:
type:
- string
- 'null'
countyName:
type:
- string
- 'null'
operatorSlug:
type:
- string
- 'null'
operatorName:
type:
- string
- 'null'
permitToSpud:
$ref: '#/components/schemas/Percentiles'
spudToProduction:
$ref: '#/components/schemas/Percentiles'
conversion:
type:
- object
- 'null'
properties:
permits:
type:
- integer
- 'null'
spudded:
type:
- integer
- 'null'
rate:
type:
- number
- 'null'
DucAging:
type: object
properties:
state:
type: string
countySlug:
type:
- string
- 'null'
countyName:
type:
- string
- 'null'
ducCount:
type:
- integer
- 'null'
p25:
type:
- integer
- 'null'
p50:
type:
- integer
- 'null'
p75:
type:
- integer
- 'null'
p90:
type:
- integer
- 'null'
Momentum:
type: object
description: score = 100 x (permits last 12 mo / prior 12) x (BOE last 12 mo / prior 12).
properties:
score:
type: integer
permits:
type: object
properties:
prior:
type: integer
recent:
type: integer
ratio:
type: number
production:
type: object
properties:
prior:
type: integer
recent:
type: integer
ratio:
type: number
through:
type: string
SnapshotEnvelope:
type: object
properties:
data:
type: object
properties:
state:
type: string
counts:
type: object
additionalProperties:
type:
- integer
- 'null'
description: Aggregate counts. permits12mo / spuds12mo / firstProd12mo are null when unknown, withheld, or held (see drillingHeld).
topOperators:
type: array
maxItems: 25
items:
type: object
topCounties:
type: array
maxItems: 25
items:
type: object
topFormations:
type: array
maxItems: 25
items:
type: object
dataAsOf:
type:
- string
- 'null'
drillingHeld:
type:
- object
- 'null'
description: Present when the state's permit, spud and first-production counts are held while the source is reconciled with state records.
properties:
held:
type: boolean
enum:
- true
reason:
type: string
enum:
- reconciling-with-state-records
note:
type: string
since:
type: string
regulator:
type: object
properties:
name:
type: string
url:
type: string
meta:
$ref: '#/components/schemas/Meta'
responses:
BadRequest:
description: Invalid input
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
parameters:
Limit:
name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 25
default: 25
description: Max rows to return (at most 25).
State:
name: state
in: path
required: true
schema:
type: string
enum:
- TX
- OK
- NM
- ND
- CO
- WY
- CA
- KS
- MS
- UT
- IL
- MT
- AL
- AR
- IN
- KY
- LA
- MI
- NE
- OH
- PA
- SD
- TN
- WV
description: Two-letter postal code for a covered state (24 states).
example: TX
x-mcp:
url: https://www.buckheadenergy.com/mcp
transport: streamable-http
discovery: https://www.buckheadenergy.com/.well-known/mcp.json
note: A native Model Context Protocol server exposes the same metrics as MCP tools.