AFE Leaks
Get API Token

AFE Leaks API Documentation

Complete reference for integrating upstream cost data and SEC financials into your applications. RESTful endpoints with JSON responses and comprehensive filtering.

🔑 Get API Token

New: MCP Server for AI Clients

Connect Claude Desktop, Cursor, Claude Code, or Codex directly to AFE Leaks data. Ask questions naturally and your AI calls our 34 database tools across well-level operations, costs, production, and SEC financials.

Setup Guide

New: OData v2 — Full Wells Universe

v2 OData exposes the full ~3 million well universe (vs. v1's ~100K cost-data wells) plus permits, completions, frac-focus, and treatment summaries. API-tier only, lowercase snake_case contract, and cross-database enrichment via state / operator_clean filters.

v2 Reference v1 (cost-data wells)

📋 Table of Contents

Getting Started

API Endpoints

🔐 Authentication

🔑 API Key (Recommended)

Permanent API keys for integrations, scripts, and external tools. No expiration or refresh needed. 

X-API-Key: afe_your_api_key_here

Get your key: Login to API Portal

🔥 Firebase Token

Session-based tokens for web applications. Tokens expire and require refresh. 

Authorization: Bearer <firebase_token>

Get token: Via Firebase Auth in web applications

Need an API Token?

Login to get your personal API access token for authentication.

Get API Token →

🌐 Base URL 

https://api.afeleaks.com

All API endpoints are relative to this base URL.

🛢️ Upstream Data Endpoints

Access well costs, production data, and completion details from 100,000+ wells

💰

Cost Data

Well-level cost summaries

GET /api/cost-data

Returns summarized cost data by well (API-level)

GET /api/cost-breakdown

Returns line-item level cost details

🔍

Wells & Metadata

Well information and details

GET /api/wells

General well metadata with dynamic column selection

GET /api/locations

Well-path or location data (WKT format)

📊

Production & Revenue

Production and revenue data

GET /api/production

Production records by well and date

GET /api/product

Product revenue data with well information

🔧

Technical Details

Completion and geology data

GET /api/casing

Casing design records

GET /api/formations

Formation tops and geology records

GET /api/surveys

Directional survey records

GET /api/welltests

Flow/pressure test data

GET /api/well-eur-parameters

Per-stream decline-curve fits and EUR estimates (oil/gas/water per well)

🏭

Vendor & Files

Vendor costs and regulatory files

GET /api/vendor-costs

Vendor cost data with well information

GET /api/files

Regulatory file links and documents

⚙️ Common Parameters

Pagination

limit Max records (default: 100, max: 10,000)
offset Skip N records for pagination

Well Filters

API API well number
operator Operator name
state State
county County
reservoir Reservoir/formation

Location Filters

lease Lease name
leaseNum Lease number
wellNum Well number
district Regulatory district

Date Range Filters

spudDateMin Min spud date (YYYY-MM-DD)
spudDateMax Max spud date (YYYY-MM-DD)
updateDateMin Min update date (YYYY-MM-DD)
updateDateMax Max update date (YYYY-MM-DD)

📊 Column Reference

Detailed descriptions of all columns returned by upstream data endpoints

🔍 og_data (Well Metadata)

Note: The /api/wells endpoint supports dynamic column selection using the columns parameter. You can specify which columns to return (e.g., ?columns=API,operator,state,spudDate) from any of the columns listed below.

API – 10- or 12-digit API well number (unique well identifier)
api12 – 12-digit API number (alternate format)
api14 – 14-digit API number (alternate format)
lease – Lease name
leaseNum – Lease number
wellNum – Well number
district – Regulatory district
county – County name
oilGas – Well type (oil/gas/both)
field – Field name
fieldNum – Field number
spudDate – Date well was spudded (drilling started)
lastSpud – Date of last spud (if re-entered)
operator – Operator name (current or at time of record)
operator_clean – Cleaned operator name (standardized)
compDate – Completion date
first_production – Date of first production
last_production – Date of last production
reservoir – Cleaned/standardized reservoir name
lateral – Lateral length (ft)
tvd – True vertical depth (ft)
md – Measured depth (ft)
perf_top – Top of perforated interval (ft)
perf_bottom – Bottom of perforated interval (ft)
perf_interval – Perforated interval length (ft)
depth – Total depth (ft)
fluid – Total fluid used (gallons)
proppant – Total proppant used (lbs)
prop_per_ft – Proppant per foot (lbs/ft)
location – Well location (legal description or lat/lon)
state – State
plug_date – Plugging date
casing_design – Casing design description
update_date – Date of last update
📊 product (Production/Revenue Data)
TaxpayerNumber – Primary taxpayer number
TaxpayerName – Primary taxpayer name
TaxSubType – Tax subtype (if applicable)
date – Production/revenue date
leaseNum – Lease number
district – Regulatory district
SecondaryTaxpayerNumber – Secondary taxpayer number
SecondaryTaxpayerName – Secondary taxpayer name
APIGravity – API gravity (oil quality measure)
volume – Product volume (e.g., barrels, mcf, etc.)
value – Product value (USD)
marketing – Marketing adjustment or revenue
product – Product type (oil, gas, NGL, etc.)
leaseOil – Lease oil production (bbl)
leaseGas – Lease gas production (mcf)
update_date – Date of last update
💰 cost_data_aggregate (Cost Data Summary)
API – API well number
type – AFE/Actual
capex – Total capital expenditure (USD)
component – Cost component (e.g., drilling, completion)
update_date – Date of last update
operator – Operator name (cleaned)
state – State
county – County
reservoir – Reservoir name
lease – Lease name
wellNum – Well number
spudDate – Spud date
fp_year – First production year
perf_interval – Perforated interval (ft)
tvd – True vertical depth (ft)
afedate – AFE date
💸 cost_breakdown_details (Cost Line Items)
API – API well number
cost_type – AFE/Actual
type – Cost type (e.g., material, service)
component – Cost component (e.g., casing, cement)
code – Cost code or identifier
category – Cost category (e.g., drilling, completion)
value – Cost value (USD)
operator – Operator name (cleaned)
state – State
county – County
reservoir – Reservoir name
lease – Lease name
wellNum – Well number
spudDate – Spud date
fp_year – First production year
perf_interval – Perforated interval (ft)
tvd – True vertical depth (ft)
afedate – AFE date
Note: No update_date column
🔧 casing_data (Casing Design)
API – API well number
type – Casing string type (e.g., surface, production)
segment – Casing segment/interval
hole_size – Hole size (inches)
hole_depth – Hole depth (ft)
size – Casing size (inches)
weight – Casing weight (lbs/ft)
grade – Casing grade
update_date – Date of last update
📉 well_eur_parameters (Decline-Curve Fits & EUR)

One row per well per stream (oil/gas/water). ~600K rows across ~200K wells. Each row carries the Arps multi-segment parameters used to forecast the stream, the actual + forecast cum, and the total EUR. method_category distinguishes direct decline fits from correlation-based estimates for wells with too little history.

state – State (key)
API – API well number (key)
stream – oil / gas / water (key)
eur_method – Method used (e.g., decline_curve, correlation)
method_category – calculated_eur or correlated_eur
fit_status – fit / failed / etc.
county – County (indexed with state + reservoir)
reservoir – Reservoir name
spud_date – Spud date
first_production – First production date
last_production – Last production date
fit_start_date – Date the fit window begins
fit_start_mop – Month-of-production at fit start
fit_start_reason – Why fit starts there (e.g., peak)
peak_date, peak_mop – Peak production date / month
months_fit – Number of months in the fit window
actual_months, forecast_months – Historical vs forecast horizon
qi_monthly, qi_daily – Initial rate (per fit start)
di_annual – Initial annual decline (nominal)
b_factor – Arps b-exponent
dmin_annual – Terminal decline (exponential tail)
b_min, b_max – Bounds applied during fit
well_life_years – Forecast horizon
actual_cum – Cumulative produced to last_production
forecast_cum – Remaining forecast cumulative
eur – Estimated Ultimate Recovery (actual + forecast)
last_actual_monthly, fit_last_monthly – Last actual and last fit monthly
correlation_scope – Peer group used for correlated EURs
correlation_multiplier – Applied scaling factor
training_well_count – Peer well count (correlated fits)
run_date – Date the fit was generated
Units: oil/water in bbl, gas in mcf
🛢️ prod_data (Production Data)
API – API well number
date – Production date
oil – Oil produced (barrels)
gas – Gas produced (MCF)
water – Water produced (barrels)
update_date – Date of last update
📍 locs (Well Locations)
API – API well number
geometry_wkt – Well geometry/location (WKT format)
update_date – Date of last update
📐 survey_data (Directional Surveys)
API – API well number
MD – Measured depth (ft)
TVD – True vertical depth (ft)
Inclination – Inclination (degrees)
Azimuth – Azimuth (degrees)
DogLegSeverity – Dog leg severity
N – North coordinate
E – East coordinate
VS – Vertical section
update_date – Date of last update
🧪 test_data (Well Tests)
API – API well number
dateTst – Test date
oilD – Oil rate (barrels/day)
gasD – Gas rate (MCF/day)
waterD – Water rate (barrels/day)
chokeSize – Choke size
tubingPressure – Tubing pressure (psi)
casingPressure – Casing pressure (psi)
testType – Test type
testHours – Test duration (hours)
reservoir – Reservoir tested
update_date – Date of last update
🏔️ formation_data (Formation Tops)
API – API well number
reservoir – Formation/reservoir name
tvd – Top TVD (ft)
md – Top MD (ft)
update_date – Date of last update
📄 file_links (Regulatory Files)
API – API well number
Form – File/form type
url – File download URL
update_date – Date of last update
🏭 vendor_costs (Vendor Cost Data)
API – API well number
date – Cost date
vendor – Vendor name
code – Vendor cost code
type – Cost type
description – Cost description
note – Additional notes
cost – Cost amount (USD)
link – Reference link
cost_type – AFE/Actual
rig – Rig information
phase – Project phase
Note: Joined with og_data for well metadata

💼 SEC Financial Data Endpoints

Access SEC XBRL financial data from 10-K and 10-Q filings with comprehensive filtering

📄

Submissions

Filing metadata

GET /api/financials/sub

Company submission metadata (filing information)

🎨

Presentation

Display information

GET /api/financials/pre

Presentation/display info for financial statement elements

🔢

Numeric Data

Financial values

GET /api/financials/num

Numeric financial data values from SEC filings

📝

Text Data

Narrative content

GET /api/financials/text

Text/narrative financial data

GET /api/financials/textbig

Large text content (MD&A, footnotes) in chunks

📊

Standardized Financials

Normalized metrics across companies

GET /api/financials/standardization

Standardized revenue, EBITDA, cash flow, and other metrics by company and period.

Filters: cik, ticker, name, enddate, metric_name, table, category, sub_category

🛢️

Reserves

Proved reserves & reconciliation

GET /api/financials/reserves

Proved reserves and standardized reserve reconciliation by company and year.

Filters: cik, ticker, name, ownership_view, category, sub_category, metric_name

⚙️

Operational Metrics

Volumes, prices & unit costs

GET /api/financials/operational-metrics

Quarterly production volumes, commodity prices, and per-unit costs by company and segment.

Filters: cik, ticker, name, ownership_view, segment, category, sub_category, metric_name

🏗️

Property Metrics

Acreage & well counts

GET /api/financials/property-metrics

Acreage, well counts, and property-level metrics by company and year.

Filters: cik, ticker, name, ownership_view, segment, category, sub_category, metric_name

🔮

Guidance Metrics

Forward-looking targets

GET /api/financials/guidance-metrics

Capex guidance, production targets, and other forward-looking metrics by company and target period.

Filters: cik, ticker, name, category, sub_category, basin, target_period, metric_name

💳

Credit Metrics

Ratings & leverage

GET /api/financials/credit-metrics

Credit ratings, leverage ratios, and credit-related metrics by company and period.

Filters: cik, ticker, name, category, sub_category, metric_name

🏦

Institutional Holdings

13F holdings (row-level)

GET /api/financials/institutional-holdings

One row per (manager × issuer × quarter) from 13F filings, restricted to our energy-coverage universe. Strict and best-effort dollar values, share counts, and confidence flags.

Filters: ticker, cik, issuer_name, manager_name, filer_cik, period_end, period_from, period_to, put_call, include_low_confidence

👤

Institutional Managers

13F filer profiles

GET /api/financials/institutional-managers

Per-quarter snapshot of each 13F filer in our coverage universe: specialist score, oil/gas weighted exposure, top-N concentration, position turnover, and confidence flags.

Filters: filer_cik, manager_name, period_end, period_from, period_to, min_specialist_score

📈

Institutional Summary

Per-issuer ownership snapshot

GET /api/financials/institutional-summary

Per-quarter ownership snapshot for each covered issuer: holder count, new/exited counts, top-holder share, HHI concentration, and total reported / strict / normalized value.

Filters: ticker, cik, issuer_name, period_end, period_from, period_to

📊 SEC Financial Data Tables

📋 sub (Company Submissions)
cik – Central Index Key (company identifier)
name – Company name
adsh – Accession number (filing identifier)
sic – Standard Industrial Classification
fye – Fiscal year end (MMDD)
form – SEC form type (10-K, 10-Q, etc.)
period – Reporting period end date
filed – Filing date
accepted – SEC acceptance date
prevrpt – Previous report indicator
detail – Detail level
instance – XBRL instance document
🎨 pre (Presentation Data)
adsh – Accession number
tag – XBRL tag name
version – Taxonomy version
plabel – Presentation label
negating – Negating multiplier
stmt – Statement type (BS, IS, CF, EQ)
inpth – Presentation path
rfile – R file reference
rorder – Report order
tbl – Table identifier
🔢 num (Numeric Financial Data)
adsh – Accession number
tag – XBRL tag name
version – Taxonomy version
enddate – Period end date
qtrs – Number of quarters
uom – Unit of measure
value – Numeric value
footnote – Footnote reference
filed – Filing date
axis – Dimensional axis
segment – Dimensional segment
📝 text (Text Financial Data)
adsh – Accession number
tag – XBRL tag name
version – Taxonomy version
enddate – Period end date
qtrs – Number of quarters
value – Text value
footnote – Footnote reference
filed – Filing date
axis – Dimensional axis
segment – Dimensional segment
📄 textbig (Large Text Content)
adsh – Accession number
tag – XBRL tag name
version – Taxonomy version
enddate – Period end date
qtrs – Number of quarters
chunk_order – Chunk sequence number
value – Large text chunk
footnote – Footnote reference
filed – Filing date
axis – Dimensional axis
segment – Dimensional segment

⚡ OData v4 Access

All upstream data endpoints support OData v4 protocol, enabling direct integration with Excel, Power BI, Tableau, and other business intelligence tools. Query data using standard OData operators like $filter, $select, $orderby, $top, and $skip.

Base URL

https://api.afeleaks.com/api/odata/

Authentication

OData endpoints use HTTP Basic Authentication. Use apikey as the username and your API key as the password.

Excel / Power Query: When prompted for credentials, select "Basic" authentication, enter apikey as username, and paste your API key as the password.

Available Endpoints

Endpoint Description
Upstream Data (Wells with Cost Data)
/api/odata/Wells Well metadata (API, operator, county, state, reservoir, depths, etc.)
/api/odata/CostData Summarized well cost data (AFE and Actual totals)
/api/odata/CostBreakdown Detailed line-item cost breakdowns
/api/odata/Production Monthly production data (oil, gas, water volumes)
/api/odata/Casing Casing string details and specifications
/api/odata/Locations Well location coordinates
/api/odata/Surveys Directional survey data
/api/odata/WellTests Well test results and measurements
/api/odata/Formations Formation tops and geological data
/api/odata/Files Available document files for wells
Product Revenues & Vendor Costs
/api/odata/Product Product revenues by lease (oil, gas, NGL sales and GPT costs)
/api/odata/VendorCosts Vendor cost data with breakdown by phase, type, and vendor
/api/odata/WellEurParameters Per-stream decline-curve fits and EUR estimates (oil/gas/water rows per well). Includes Arps parameters, actual + forecast cum, and total EUR.
SEC Financial Data (XBRL)
/api/odata/FinancialsSub SEC filing submissions metadata
/api/odata/FinancialsNum Raw XBRL numeric values from filings
/api/odata/FinancialsPre Presentation linkbase (statement line items)
/api/odata/FinancialsText Text/footnote data from filings
/api/odata/FinancialsTextBig Large text blocks (chunked for performance)
/api/odata/FinancialsStandardized Standardized financial metrics (revenue, EBITDA, etc.)
/api/odata/Reserves Proved reserves and standardized reserve reconciliation by company/year
/api/odata/OperationalMetrics Quarterly operational metrics (volumes, prices, unit costs) by company/segment
/api/odata/PropertyMetrics Acreage, well counts, and property-level metrics by company/year
/api/odata/GuidanceMetrics Forward-looking guidance (capex, production targets) by company/period
/api/odata/CreditMetrics Credit ratings, leverage ratios, and credit-related metrics
/api/odata/Hedges Commodity hedge details — swaps, collars, floors, ceilings by company, commodity, benchmark, and period
13F Institutional Ownership
/api/odata/InstitutionalHoldings Row-level 13F holdings — one row per (manager × issuer × quarter) with strict and best-effort dollar values, share counts, and confidence flags
/api/odata/InstitutionalManagers Per-quarter snapshot of each 13F filer in our energy-coverage universe: specialist score, oil/gas weighted exposure, top-N concentration, position turnover
/api/odata/InstitutionalSummary Per-issuer ownership snapshot: holder count, top-holder share, HHI concentration, and total reported / strict / normalized value

Query Examples

Filter wells by state:

/api/odata/Wells?$filter=state eq 'TX'

Filter by operator and select specific columns:

/api/odata/Wells?$filter=operator_clean eq 'DIAMONDBACK'&$select=API,wellName,county,reservoir

Get production with pagination:

/api/odata/Production?$top=1000&$skip=0&$orderby=prod_date desc

Filter by multiple conditions:

/api/odata/Wells?$filter=state eq 'TX' and county eq 'REEVES' and perf_interval gt 5000

Using with Excel Power Query

  1. Open Excel and go to Data → Get Data → From Other Sources → From OData Feed
  2. Enter the OData URL: https://api.afeleaks.com/api/odata/Wells
  3. When prompted for authentication, select Basic
  4. Enter apikey as the username
  5. Paste your API key as the password
  6. Click Connect to load the data

Tip: For large datasets, use $filter to narrow down results before loading (e.g., filter by state or operator).

🛰️ OData v2 — Full Wells Universe

A second OData v4 namespace for the full ~3M-well universe and federal/state regulatory data. Cost endpoints stay on v1.

v2 adds four entity families that v1 doesn't cover: permit data, completion / frac-focus / treatment summaries, the full well_header universe (not just wells with cost data), and raw lease-level production from RRC. Existing v1 endpoints are untouched — you can keep using them. Choose v2 when you need scale (~3M wells vs. ~100K) or surface area (permits / completions) that v1 doesn't have.

Base URL

https://api.afeleaks.com/api/odata/v2/

Public introspection: /$metadata (EDMX schema), / (service document), /_health (connectivity check). All other endpoints require auth.

Authentication — API tier only

v2 is API-tier only. Pass X-API-Key: <your_key> or HTTP Basic Auth (any username, password = your API key). Requests with no auth at all return 401 Unauthorized; Firebase session cookies (basic / premium tiers) authenticate but get a 403 Forbidden from the v2 tier gate — v2 does not unlock for non-API tiers. Use v1 (/api/odata/*) for browser-session access, or contact sales for an API key.

Column naming — lowercase snake_case

Every v2 entity returns column names in lowercase snake_case for a uniform contract — including domain abbreviations:

  • api_number (not "API")
  • md, tvd, ns, ew, vs, dls, inclination, azimuth on Surveys
  • ngl on Production

Tables under v1 still use the legacy mixed casing ("API", "NGL", etc.). If you mix v1 and v2 in the same Power Query, expect to rename columns.

Migrating from v1? Filter field names changed too.

A v1 $filter clause pasted into v2 will return 400 BadRequest because the field names changed alongside the response columns. API is not a recognized v2 filter field — use api_number. Same goes for any other column the v1 contract spelled in CAPS or PascalCase.

v1 (still valid on v1)

/api/odata/Wells
  ?$filter=API eq '4234567890'

v2

/api/odata/v2/Wells
  ?$filter=api_number eq '4234567890'

Same pattern for $orderby and $select: lowercase the field names. v2 returns 200 with an empty array (not 404) when a filter matches no rows, so an empty result on a known-good query usually means the API number isn't in the dataset, not that the request was malformed.

Required filters

v2 entities backed by very large tables enforce a minimum filter to prevent full-table scans. A request without one returns 400 BadRequest with the list of acceptable filters.

Entity Required (any one of)
/v2/Wellsstate · api_number · operator_clean
/v2/Permitsstate · api_number
/v2/Production & rich tablesapi_number (or any enrich filter)
/v2/ProductionRawstate + district + lease_no (composite)
summary entitiesno required filter (small datasets)

Cross-database enrichment filters

The rich entities (Production, Casing, Surveys, Formations, FileLinks, Locs) accept well-metadata filters — state, county, operator_clean, reservoir, operator_cleanStartsWith — even though those columns don't physically exist on the entity. v2 transparently runs a 2-stage query: it first hydrates the matching api_number list from the well universe, then fetches the rows you asked for.

This lets you ask "all surveys for EOG operators in Texas" in one call, instead of composing /v2/Wells → collect APIs → /v2/Surveys?api_number=….

Cap: 25,000 wells per request. If your enrich filter matches more wells than that, v2 returns 400 EnrichTooBroad. Narrow the filter (add county or reservoir, prefer operator_clean over state alone) or page via api_number directly.

v2 Entities

Endpoint Description
Wells & Permits (full universe)
/api/odata/v2/WellsWell header — ~3M rows. api_number, state/county/lease, operator (raw + cleaned), reservoir, spud / completion / first-prod / last-prod / shut-in / plug dates, mineral owner type. Requires state, api_number, or operator_clean.
/api/odata/v2/PermitsDrilling permits with full lifecycle dates (issue / amended / extended / expired / cancelled / spud), application type, directional/horizontal/sidetrack flags. Requires state or api_number.
/api/odata/v2/CompletionSummaryPer-well completion summary — fluid / proppant volumes, treatment + proppant + fluid type, stage and filings count, has_fracfocus flag.
/api/odata/v2/FracFocusSummaryFracFocus-derived completion data — fluid + proppant + recomplete volumes, job and recomplete dates.
/api/odata/v2/TreatmentSummaryState-data-derived treatment volumes (proppant / fluid / stages) where reported by the operator.
/api/odata/v2/TypeCurveCountyP50 normalized oil/gas type curves at the county × month-of-production grain. Use for benchmarking.
Production
/api/odata/v2/ProductionAllocated monthly production (oil / gas / water / ngl) per api_number. Requires api_number or any enrich filter.
/api/odata/v2/ProductionRawLease-level RRC production (oil / gas / cond / casinghead, vent-flare, ending balances). ~143M rows. Requires state + district + lease_no or just state.
Wellbore detail (require api_number or enrich filter)
/api/odata/v2/CasingCasing string + cement detail — type, segment, hole size/depth, weight, grade, top/depth, cement class, TOC/BOC, packer, set date, test pressure.
/api/odata/v2/SurveysDirectional surveys — md / tvd / inclination / azimuth / ns / ew / vs / dls + source file URL.
/api/odata/v2/FormationsFormation tops — reservoir, tvd, md per well.
/api/odata/v2/FileLinksAvailable document links (form type + URL) for each well.
/api/odata/v2/LocsSurface and bottomhole coordinates, lateral length, full WKT geometry.
Reserves & forecasts
/api/odata/v2/WellEurParametersPer-stream decline-curve fits (oil / gas / water rows per api_number) — Arps parameters (qi, di, b, dmin, b_min/b_max), fit window, actual + forecast cum, total EUR, and run_date. Requires state or api_number.

Query Examples

All wells in Texas Eagle Ford (5K rows max):

/api/odata/v2/Wells?$filter=state eq 'TX' and reservoir eq 'EAGLE FORD'&$top=5000

Operator-prefix lookup (uses text_pattern_ops index):

/api/odata/v2/Wells?$filter=state eq 'TX' and startswith(operator_clean, 'EOG')

All surveys for EOG wells in Texas (cross-DB enrichment):

/api/odata/v2/Surveys?$filter=state eq 'TX' and operator_clean eq 'EOG RESOURCES'

No api_number needed — v2 hydrates the api list from well_header and joins to Surveys in one call. 25K wells max per request.

Recent permits in Texas:

/api/odata/v2/Permits?$filter=state eq 'TX' and permit_date ge 2025-01-01&$orderby=permit_date desc

Lease-level raw production (composite filter):

/api/odata/v2/ProductionRaw?$filter=state eq 'TX' and district eq '08' and lease_no eq '273604'

Get total well count with $count:

/api/odata/v2/Wells?$filter=state eq 'TX'&$top=0&$count=true

Per-table $count is cached for 10 minutes; first call ~700ms, repeats are free.

Errors you may see

Status Code When
400BadRequestRequired filter missing (e.g. /v2/Wells without state / api_number / operator_clean).
400EnrichTooBroadCross-DB enrichment matched > 25K wells. Narrow your filter.
401UnauthorizedNo auth presented. Add X-API-Key header or HTTP Basic Auth (password = your API key).
403ForbiddenAuthenticated but tier is too low (Firebase basic / premium session). v2 requires API-tier access — use X-API-Key with an API-tier key.
429RateLimitedv2 rate limit is 25,000 req/min (half of v1). The cap is per-API-key.

📦 Bulk Table Downloads

Pre-generated .csv.gz snapshots of every upstream and XBRL table, served directly from Google Cloud Storage via short-lived signed URLs. Use these when you need a full copy of a table for offline analysis, ETL into a warehouse, or any workflow where paginating through the REST API would be slow or expensive.

Plan requirement: Bulk downloads are available only on the API Enterprise tiers (enterprise_s, enterprise_m, enterprise_l) and grandfathered legacy unlimited API (legacy_api_unlimited) plans. Starter, Professional, and Corporate plans should use the paginated REST / OData endpoints instead.

How it works

  1. A nightly batch job dumps each table to .csv.gz and uploads it to gs://afe-leaks-5cc64.appspot.com/bulk-downloads/latest/. Dated archive copies are retained for 30 days.
  2. Your client hits GET /api/bulk-download to discover the table list, file sizes, and the timestamp of the most recent generation.
  3. Your client hits GET /api/bulk-download/<table> with your bearer token or API key. The server verifies your plan and returns a 15-minute signed URL.
  4. Your client follows the signed URL to download the file directly from GCS — the bytes never pass through our API, so download speed is limited only by your bandwidth.

Endpoints

GET /api/bulk-download · Public · No auth required

Returns the manifest of all available tables with size, description, and generation timestamp. No authentication needed — useful for automated catalog discovery. 

curl https://api.afeleaks.com/api/bulk-download
GET /api/bulk-download/:table · Auth required · Enterprise / legacy only

Returns a signed download URL for the named table. The url is valid for 15 minutes; the bytes field tells you what to expect before you start the transfer. 

# 1. Resolve the signed URL
curl -H "X-API-Key: afe_your_key" \
  https://api.afeleaks.com/api/bulk-download/cost-data

# Response:
# {
#   "key": "cost-data",
#   "label": "Cost Data",
#   "bytes": 48234112,
#   "generated_at": "2026-04-14T07:00:00.000Z",
#   "url": "https://storage.googleapis.com/...",
#   "expires_at": "2026-04-14T12:15:00.000Z",
#   "content_encoding": "gzip",
#   "content_type": "text/csv"
# }

# 2. Follow the signed URL to download
curl -L -o cost-data.csv.gz "<url from step 1>"

# 3. Decompress
gunzip cost-data.csv.gz

The signed URL already sets Content-Disposition: attachment, so web browsers save the file directly. Requests with an unsupported plan return HTTP 403 with a current_plan and required_plan_codes payload explaining what to upgrade to.

Available tables

The manifest is the authoritative list — sizes and row counts update nightly. At a glance:

🛢️ Upstream (afeleaks)

  • wells — well metadata
  • cost-data — aggregated AFE/Actual costs
  • cost-breakdown — line-item breakdowns
  • production — monthly volumes
  • casing, locations, surveys
  • welltests, formations, files
  • product — product revenues
  • vendor-costs — vendor breakdowns

💼 SEC / XBRL (xbrl)

  • financials-sub — filing submissions
  • financials-num — numeric facts
  • financials-standardized — standardized metrics
  • financials-pre — presentation linkbase
  • financials-text, financials-textbig
  • reserves — proved + standardized reserves
  • operational-metrics — quarterly volumes / prices / unit costs
  • property-metrics — acreage, well counts, property-level metrics
  • guidance-metrics — forward-looking capex/production guidance
  • credit-metrics — credit ratings, leverage ratios

All upstream tables are restricted to wells with cost data (same policy as the REST and OData endpoints). All XBRL tables include every ticker present in xbrl.standardized.

Tip: The UI client pages (Upstream Client, Financial Client) have a one-click "Download" button for each table if you prefer browser-based access.

v2 — Full universe (per state)

v1 bulk downloads (above) are restricted to ~100K wells with cost data. v2 bulk downloads cover the full ~770K-well universe, mirroring the OData v2 data model. Same Enterprise / legacy-API-unlimited plan gate.

Layout

  • One zip per state covering wells, permits, production, casing, surveys, formations, file links, and locations.
  • Standalone production-raw CSVs per state (lease-level RRC). Texas is split into 13 per-RRC-district files because it's 77M rows on its own.
  • Weekly cadence for everything except permits, which regenerates nightly. State zips are rebuilt on every run so they're never more than a day stale.

Endpoints

GET /api/bulk-download/v2 · Public · No auth required

v2 manifest. Lists per-state zip bundles and standalone CSV entries with byte sizes and generation timestamps.

GET /api/bulk-download/v2/zip/:state · Auth required · Enterprise / legacy only

Signed URL for a per-state zip bundle. :state is the 2-letter code (TX, NM, OK, ND, CO, WY, UT, MT, KS, LA, WV).

GET /api/bulk-download/v2/table/:key · Auth required · Enterprise / legacy only

Signed URL for one v2 catalog entry. :key matches manifest entries (e.g. v2-tx-production-raw-d08, v2-nm-wells).

# 1. Discover available bundles
curl https://api.afeleaks.com/api/bulk-download/v2

# 2. Get a signed URL for the Texas state zip
curl -H "X-API-Key: afe_your_key" \
  https://api.afeleaks.com/api/bulk-download/v2/zip/TX

# 3. Pull one per-district production-raw file (TX D8 = Midland Permian)
curl -H "X-API-Key: afe_your_key" \
  https://api.afeleaks.com/api/bulk-download/v2/table/v2-tx-production-raw-d08

The Upstream Client UI page surfaces the full v2 catalog with a per-state download button — the same flow as v1. Pick whichever is easier for your workflow.

💡 API Examples

Get Cost Data for Texas Wells

🔑 Using API Key

curl -H "X-API-Key: afe_your_key" \
  "https://api.afeleaks.com/api/cost-data?state=TX&limit=100"

🔥 Using Firebase Token

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.afeleaks.com/api/cost-data?state=TX&limit=100"

Get Production Data with Pagination

🔑 Using API Key

curl -H "X-API-Key: afe_your_key" \
  "https://api.afeleaks.com/api/production?limit=1000&offset=5000"

🔥 Using Firebase Token

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.afeleaks.com/api/production?limit=1000&offset=5000"

Get Financial Data for Specific Company

🔑 Using API Key

curl -H "X-API-Key: afe_your_key" \
  "https://api.afeleaks.com/api/financials/num?cik=0000078003&form=10-K"

🔥 Using Firebase Token

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.afeleaks.com/api/financials/num?cik=0000078003&form=10-K"

📝 Programming Language Examples

📊 R (with API Key) 

library(httr)
library(jsonlite)

# Using permanent API key
api_key <- "afe_your_generated_key_here"

resp <- GET(
  url = "https://api.afeleaks.com/api/wells",
  query = list(limit = 10, state = "TX"),
  add_headers(`X-API-Key` = api_key)
)

if (status_code(resp) == 200) {
  data <- content(resp, "parsed")
  wells_df <- data$data
} else {
  print(paste("Error:", status_code(resp)))
}

🐍 Python (with API Key) 

import requests
import pandas as pd

# Using permanent API key
api_key = "afe_your_generated_key_here"
headers = {"X-API-Key": api_key}

response = requests.get(
    "https://api.afeleaks.com/api/wells",
    params={"limit": 10, "state": "TX"},
    headers=headers
)

if response.status_code == 200:
    data = response.json()
    wells_df = pd.DataFrame(data["data"])
else:
    print(f"Error: {response.status_code}")

⚡ JavaScript (with API Key) 

// Using permanent API key
const apiKey = "afe_your_generated_key_here";

fetch('https://api.afeleaks.com/api/wells?limit=10&state=TX', {
  headers: {
    'X-API-Key': apiKey
  }
})
.then(response => response.json())
.then(data => {
  console.log(`Retrieved ${data.data.length} wells`);
  console.log('Wells:', data.data);
})
.catch(error => console.error('Error:', error));

📈 Excel/Power BI 

// Power Query M code
let
    apiKey = "afe_your_generated_key_here",
    url = "https://api.afeleaks.com/api/wells?limit=1000",
    headers = [#"X-API-Key" = apiKey],
    response = Web.Contents(url, [Headers = headers]),
    json = Json.Document(response),
    data = json[data],
    table = Table.FromList(data, Splitter.SplitByNothing(), null, null, ExtraValues.Error)
in
    table

🤖 MCP Server AI Client Integration

Corporate and API subscribers can connect AI tools directly to AFE Leaks data using the Model Context Protocol (MCP). Once connected, just ask questions naturally — your AI calls our database tools automatically.

Supported Clients

Claude Desktop
Cursor
Claude Code
Codex
Streamable HTTP

Two hosted transports: /sse for Claude Desktop, Cursor, and Claude Code; /mcp (Streamable HTTP) preferred for Codex. Works with any MCP-compatible client.

Companion Skill File

Drop this markdown file into Claude.ai Projects, Claude Code (~/.claude/skills/afeleaks/SKILL.md), Cursor (.cursor/rules/), or Codex (AGENTS.md) to teach your AI client our tool families, operator aliases, basin synonyms, coverage caveats, and workflow recipes — so it picks the right tool faster and wastes fewer credits exploring.

Download skill (.md) Preview in browser

Setup Instructions

Claude Desktop Settings → Developer → Edit Config 

{
  "mcpServers": {
    "afeleaks": {
      "url": "https://mcp.afeleaks.com/sse?api_key=YOUR_API_KEY"
    }
  }
}

Cursor Settings → MCP Servers → Add Server

Type
SSE
URL
https://mcp.afeleaks.com/sse?api_key=YOUR_API_KEY

Claude Code Terminal command 

claude mcp add afeleaks --transport sse "https://mcp.afeleaks.com/sse?api_key=YOUR_API_KEY"

Codex Streamable HTTP · bearer token via env var

Codex prefers the Streamable HTTP endpoint at /mcp. Pass the API key as a bearer token through an environment variable so it never appears in shell history or request URLs.

export AFELEAKS_API_KEY="afe_..."

codex mcp add afeleaks \
  --url "https://mcp.afeleaks.com/mcp" \
  --bearer-token-env-var AFELEAKS_API_KEY

Restart Codex after running codex mcp add so it picks up the new server and loads the tool list.

Troubleshooting

401

API key missing. /mcp returned 401 because no ?api_key=... query param or Authorization: Bearer ... header was sent. For Codex, confirm the env var referenced by --bearer-token-env-var is exported in the shell that launched Codex.

403

Invalid key or insufficient access. The key is rejected, or the account does not have Corporate/API MCP access. Verify the key in Account Settings and confirm the subscription tier.

Codex

No tools showing up. Restart Codex after codex mcp add — the tool list is loaded on launch, not refreshed live.

Health

Server status. Hit https://mcp.afeleaks.com/health — a healthy response lists both sse and streamable-http transports.

Available Tools (34 total, 6 families)

The agent picks tools automatically — you don't call them directly. Every response carries a _usage envelope (see Credits & Usage below).

Well discovery & metadata — 7 tools

search_operators Fuzzy operator-name resolution with cost-data coverage counts
search_wells Find API numbers by prefix, lease, or operator (full well universe)
lookup_well Single-well detail: metadata + costs + production in one call
query_dataverse_wells Broad well discovery across the full ~3M Dataverse well universe
query_dataverse_permits Permit lifecycle, depths, horizontal/directional flags, applications
query_well_locations Lat/lng and WKT geometry for mapping wellbore paths
get_basin_info Basin → county/state crosswalk for geographic filtering

Costs — 4 tools

query_well_costs Aggregated AFE vs Actual stats (avg and median in one call) with group_by
query_cost_details Line-item breakdowns (drilling, completion, casing, stimulation, cement, …)
query_vendor_costs Vendor-level cost detail (who got paid for what)
compare_costs Side-by-side comparisons across operators, basins, years, reservoirs

Production & performance — 4 tools

query_production Oil / gas / water by well — cumulative, monthly avg, or peak
query_well_eur Estimated ultimate recovery by well or filter set
build_type_curve Synthesize a normalized type curve from a well selection
query_well_tests IP / well-test results (initial rates, choke, pressure)

Completion & engineering — 5 tools

query_completion_metrics Fluid volume, proppant mass, stages — summarized across FracFocus + frac summaries
query_completion_raw Raw completion filings: perf interval, TVD/MD, frac company, choke, text
query_formations Formation tops and reservoir depths
query_casing Casing program detail (string, OD, depths, cement)
query_surveys Directional survey data (inclination, azimuth, MD/TVD)

Corporate financials (SEC / XBRL) — 12 tools

query_financials Income, balance sheet, cash flow by ticker
list_financial_metrics Discover the catalog of standardized metric names
query_financial_reserves Proved reserves disclosures (PUD, PDP, by category)
query_operational_metrics Standardized production volumes, realized prices, unit costs
query_property_metrics Acreage, drilled inventory, property-level disclosures
query_guidance_metrics Forward-looking company guidance by basin and target period
query_credit_metrics Debt, revolver, notes, covenants, ratings, liquidity (latest snapshot)
query_hedges Hedge book — tranche-level swaps, collars, puts with price + volume
query_cost_disclosures Well-cost disclosures pulled from SEC filings
query_executive_comp_incentives Executive compensation and incentive plan structure
search_xbrl_companies Find companies in the SEC universe (~146 covered)
query_xbrl_raw Raw XBRL query against any SEC filing — escape hatch for custom facts

Synthesis & knowledge — 2 tools

query_vault_knowledge Query the AFE Leaks research vault (notes, write-ups, analyses)
create_corporate_profile Auto-synthesize a full corporate profile (multi-tool chained query)

Plus get_mcp_credit_balance — a free utility tool that returns your remaining credit balance without consuming any.

Example Prompts

Once connected, just ask your AI client questions like these — it will pick the right tools (often chaining several) automatically:

"What's the average well cost in the Delaware Basin since 2023?"

→ query_well_costs

"Compare Diamondback vs Devon drilling costs for 2-mile laterals"

→ search_operators → compare_costs

"Show me EOG's revenue, EBITDA, and free cash flow trend over the last 2 years"

→ query_financials

"Look up well 42-461-40916"

→ lookup_well

"Build a type curve for Comstock's Haynesville wells with >2-mile laterals"

→ search_wells → build_type_curve

"What does Ovintiv's 2026 oil hedge book look like?"

→ query_hedges

"Summarize Diamondback's executive comp incentive plan"

→ query_executive_comp_incentives

"Pull a full corporate profile for Permian Resources"

→ create_corporate_profile (chains many tools)

Credits & Usage

_usage

Every tool response carries a _usage envelope with args_tokens, result_tokens, credits_charged, and credit_balance_after. Credits scale with payload size — narrow filters cost less than broad scans.

Free

get_mcp_credit_balance is free — calling it never consumes credits. Ask your AI "what's my MCP credit balance?" anytime to confirm remaining usage.

Top up

Out of credits? Buy more or review usage history at MCP Credits. Low-balance email alerts fire automatically before the next call would fail.

Idempotent

Duplicate calls don't double-charge. Each tool invocation generates an idempotency key — retries from a flaky client are detected and the original debit is reused.

Requirements

  • Corporate or API subscription tier
  • API key (generate from Account Settings, starts with afe_)
  • Subject to plan-specific rate limits, quotas, and endpoint restrictions
  • API credentials are confidential and may not be shared or redistributed

🚀 Quick Start Guide

Get up and running with the AFE Leaks API in minutes

1

Get Your API Credentials

Choose your authentication method and get your credentials.

🔑 Generate API Key (Recommended) → 🔥 Get Firebase Token →
2

Make Your First Request

Test the API with a simple request to get well data.

🔑 With API Key

curl -H "X-API-Key: afe_your_key" \
  "https://api.afeleaks.com/api/wells?limit=10"

🔥 With Firebase Token

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.afeleaks.com/api/wells?limit=10"
3

Integrate Into Your Workflow

Use the API clients or build custom integrations for your specific needs.

Upstream Client → Financial Client →

Need Help with Integration?

Our team can help you integrate AFE Leaks data into your existing systems and provide custom solutions.

Contact Support Consulting Services