Buckhead Energy Counties API

openapi: 3.2.0
info:
  title: Buckhead Energy Public Counties 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: counties
  description: County-level metrics
paths:
  /counties/{state}/{county}/metrics:
    get:
      tags:
      - counties
      summary: County metrics
      description: 'One county: monthly permits / spuds / first production (last 24 months), cycle times, DUC aging and momentum score. No operator breakdown.'
      parameters:
      - $ref: '#/components/parameters/State'
      - $ref: '#/components/parameters/CountySlug'
      responses:
        '200':
          description: County metrics
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      state:
                        type: string
                      countySlug:
                        type: string
                      monthly:
                        type: array
                        maxItems: 24
                        items:
                          $ref: '#/components/schemas/MonthlyActivity'
                      cycleTimes:
                        allOf:
                        - $ref: '#/components/schemas/CycleTimes'
                        type:
                        - object
                        - 'null'
                      ducAging:
                        allOf:
                        - $ref: '#/components/schemas/DucAging'
                        type:
                        - object
                        - 'null'
                      momentum:
                        allOf:
                        - $ref: '#/components/schemas/Momentum'
                        type:
                        - object
                        - 'null'
                      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: getCountyMetrics
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
    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'
    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
    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
    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'
  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:
    CountySlug:
      name: county
      in: path
      required: true
      schema:
        type: string
        pattern: ^[a-z0-9-]{1,80}$
      description: County slug (lowercase, hyphenated).
      example: midland
    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.