# OilPriceAPI — Complete Technical Reference for AI Agents > Base URL: https://api.oilpriceapi.com > Auth: `Authorization: Token YOUR_API_KEY` or `Authorization: Bearer YOUR_API_KEY` > Format: JSON (all responses) > Offer: 7-day, 10,000-request core commodity API trial with no credit card; then Free with 200 requests/month > Sign up: https://www.oilpriceapi.com/auth/signup > Reviewed product facts: https://api.oilpriceapi.com/product-facts.json > OpenAPI Spec: https://api.oilpriceapi.com/swagger.json > YAML Spec: https://api.oilpriceapi.com/.well-known/openapi.yaml > Freshness: Latest available values include source timestamps; refresh cadence and access vary by source, market hours, dataset, plan, and account entitlement > Data rights: https://www.oilpriceapi.com/legal/data-usage Cookbook (runnable, production-verified Python examples; code MIT, data per Data Usage Policy): https://github.com/OilpriceAPI/cookbook — machine index: https://raw.githubusercontent.com/OilpriceAPI/cookbook/main/recipes.json ## Authentication Every authenticated request requires the header: Authorization: Token YOUR_API_KEY Both `Token` and `Bearer` prefixes are accepted. New accounts start with the 7-day, 10,000-request core commodity API trial; after the trial, the Free plan includes 200 requests per month. Dataset access varies by plan and account entitlement. Sign up at: https://www.oilpriceapi.com/auth/signup The demo endpoint requires NO authentication — use it to test connectivity first. ## Response Format All successful responses return: { "status": "success", "data": { ... } } Error responses return: { "status": "fail", "data": { "error": "error_type", "message": "Human-readable explanation" } } ## Rate Limit Headers Every response includes these headers: X-RateLimit-Limit — Your monthly request limit X-RateLimit-Effective-Limit — Your request capacity including credits X-RateLimit-Credits-Included — Credits included in current capacity X-RateLimit-Remaining — Requests remaining this month X-RateLimit-Used — Requests consumed this month X-RateLimit-Reset — Unix timestamp when your limit resets X-RateLimit-Tier — Plan, trial, credit, or courtesy identifier X-RateLimit-Window — Current quota window, such as monthly or trial X-RateLimit-State — Current quota state Quota headers never include user email, organization name, or workspace name. ## Endpoints ### Discovery: GET /sample — No-key Sample Prices Returns representative public prices for WTI, Brent, and natural gas. This endpoint requires no API key and is safe for agent discovery. curl "https://api.oilpriceapi.com/sample?by_code=WTI_USD&measure=spot_price" Supported `by_code` values: - WTI_USD - BRENT_CRUDE_USD - NATURAL_GAS_USD Supported `measure` values: - spot_price - change_24h - source_timestamp ### Discovery: GET /v1/x402/prices/latest — x402 Measurement Preview Measurement-only x402 preview endpoint for agent demand discovery. This route currently returns HTTP 402 and records whether clients attempt the flow. Live `PAYMENT-REQUIRED` negotiation, `PAYMENT-SIGNATURE` verification, settlement, and paid fulfillment are planned for the payments sprint. curl "https://api.oilpriceapi.com/v1/x402/prices/latest?by_code=WTI_USD&measure=spot_price" Planned discovery price point: $0.01 USDC per successful request. ### 1. GET /v1/demo/prices — Demo Prices (NO AUTH REQUIRED) Returns prices for popular commodities. Use this to test before signing up. curl https://api.oilpriceapi.com/v1/demo/prices Sample response: { "status": "success", "data": { "prices": [ { "price": 78.41, "formatted": "$78.41", "currency": "USD", "code": "BRENT_CRUDE_USD", "created_at": "2026-03-09T14:30:00.000Z", "updated_at": "2026-03-09T14:32:00.000Z", "type": "spot_price", "unit": "barrel", "source": "multi_source" }, { "price": 72.01, "formatted": "$72.01", "currency": "USD", "code": "WTI_USD", "created_at": "2026-03-09T14:30:00.000Z", "updated_at": "2026-03-09T14:32:00.000Z", "type": "spot_price", "unit": "barrel", "source": "multi_source" } ] } } ### 2. GET /v1/prices/latest — Latest Price for a Commodity Returns the most recent price for one or more commodity codes. Parameters: - `by_code` (string, optional) — Commodity code. Default: BRENT_CRUDE_USD. Alias: `code`. - Multiple codes: comma-separated, e.g. `by_code=BRENT_CRUDE_USD,WTI_USD` Single commodity: curl -H "Authorization: Token YOUR_API_KEY" \ "https://api.oilpriceapi.com/v1/prices/latest?by_code=BRENT_CRUDE_USD" Sample response: { "status": "success", "data": { "price": { "price": 78.41, "formatted": "$78.41", "currency": "USD", "code": "BRENT_CRUDE_USD", "created_at": "2026-03-09T14:30:00.000Z", "updated_at": "2026-03-09T14:32:00.000Z", "type": "spot_price", "unit": "barrel", "source": "multi_source" } } } Multiple commodities: curl -H "Authorization: Token YOUR_API_KEY" \ "https://api.oilpriceapi.com/v1/prices/latest?by_code=BRENT_CRUDE_USD,WTI_USD,NATURAL_GAS_USD" Sample response: { "status": "success", "data": { "prices": [ { "price": 78.41, "formatted": "$78.41", "currency": "USD", "code": "BRENT_CRUDE_USD", "created_at": "2026-03-09T14:30:00.000Z", "updated_at": "2026-03-09T14:32:00.000Z", "type": "spot_price", "unit": "barrel", "source": "multi_source" }, { "price": 72.01, "formatted": "$72.01", "currency": "USD", "code": "WTI_USD", "created_at": "2026-03-09T14:30:00.000Z", "updated_at": "2026-03-09T14:32:00.000Z", "type": "spot_price", "unit": "barrel", "source": "multi_source" }, { "price": 4.12, "formatted": "$4.12", "currency": "USD", "code": "NATURAL_GAS_USD", "created_at": "2026-03-09T14:28:00.000Z", "updated_at": "2026-03-09T14:30:00.000Z", "type": "spot_price", "unit": "MMBtu", "source": "multi_source" } ] } } ### 3. POST /v1/prices/batch — Batch Price Lookup (Recommended for Agents) Fetch multiple commodity prices in a single request. Counts as 1 request against your quota. Body (JSON): `{ "codes": ["CODE1", "CODE2", ...] }` Maximum: 50 codes per request. curl -X POST \ -H "Authorization: Token YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"codes": ["BRENT_CRUDE_USD", "WTI_USD", "GOLD_USD", "NATURAL_GAS_USD"]}' \ "https://api.oilpriceapi.com/v1/prices/batch" Sample response: { "status": "success", "data": { "prices": [ { "price": 78.41, "formatted": "$78.41", "currency": "USD", "code": "BRENT_CRUDE_USD", "created_at": "2026-03-09T14:30:00.000Z", "updated_at": "2026-03-09T14:32:00.000Z", "type": "spot_price", "unit": "barrel", "source": "multi_source" }, { "price": 72.01, "formatted": "$72.01", "currency": "USD", "code": "WTI_USD", "created_at": "2026-03-09T14:30:00.000Z", "updated_at": "2026-03-09T14:32:00.000Z", "type": "spot_price", "unit": "barrel", "source": "multi_source" }, { "price": 2948.50, "formatted": "$2,948.50", "currency": "USD", "code": "GOLD_USD", "created_at": "2026-03-09T14:25:00.000Z", "updated_at": "2026-03-09T14:28:00.000Z", "type": "spot_price", "unit": "troy_ounce", "source": "multi_source" }, { "price": 4.12, "formatted": "$4.12", "currency": "USD", "code": "NATURAL_GAS_USD", "created_at": "2026-03-09T14:28:00.000Z", "updated_at": "2026-03-09T14:30:00.000Z", "type": "spot_price", "unit": "MMBtu", "source": "multi_source" } ], "count": 4, "requested": 4 } } ### 4. GET /v1/prices/all — All Commodity Prices Returns the latest price for every commodity in a single call. curl -H "Authorization: Token YOUR_API_KEY" \ "https://api.oilpriceapi.com/v1/prices/all" ### 5. GET /v1/prices/past_day — 24-Hour Historical (Paid Tier) Parameters: - `by_code` (string) — Commodity code. Default: BRENT_CRUDE_USD. - `interval` (string) — Aggregation: `raw`, `hourly`, or `daily`. curl -H "Authorization: Token YOUR_API_KEY" \ "https://api.oilpriceapi.com/v1/prices/past_day?by_code=BRENT_CRUDE_USD&interval=hourly" Sample response: { "status": "success", "data": { "prices": [ { "price": 77.95, "formatted": "$77.95", "currency": "USD", "code": "BRENT_CRUDE_USD", "created_at": "2026-03-08T15:00:00.000Z", "type": "hourly_average" }, { "price": 78.10, "formatted": "$78.10", "currency": "USD", "code": "BRENT_CRUDE_USD", "created_at": "2026-03-08T16:00:00.000Z", "type": "hourly_average" } ] } } ### 6. GET /v1/prices/past_week — 7-Day Historical (Paid Tier) Parameters: `by_code`, `interval` (raw, hourly, daily). curl -H "Authorization: Token YOUR_API_KEY" \ "https://api.oilpriceapi.com/v1/prices/past_week?by_code=WTI_USD&interval=daily" ### 7. GET /v1/prices/past_month — 30-Day Historical (Paid Tier) Parameters: `by_code`, `interval` (raw, daily, weekly). curl -H "Authorization: Token YOUR_API_KEY" \ "https://api.oilpriceapi.com/v1/prices/past_month?by_code=NATURAL_GAS_USD&interval=daily" ### 8. GET /v1/prices/past_year — 365-Day Historical (Paid Tier) Parameters: `by_code`, `interval` (daily, weekly, monthly). curl -H "Authorization: Token YOUR_API_KEY" \ "https://api.oilpriceapi.com/v1/prices/past_year?by_code=BRENT_CRUDE_USD&interval=monthly" Sample response: { "status": "success", "data": { "prices": [ { "price": 74.32, "formatted": "$74.32", "currency": "USD", "code": "BRENT_CRUDE_USD", "created_at": "2025-04-01T00:00:00.000Z", "type": "monthly_average" }, { "price": 75.18, "formatted": "$75.18", "currency": "USD", "code": "BRENT_CRUDE_USD", "created_at": "2025-05-01T00:00:00.000Z", "type": "monthly_average" } ] } } ### 8b. Point-in-Time (Vintage) History — ?as_of= (Paid Tier) Publishers restate numbers after first release. Add `as_of=` to any past_* endpoint to see the series as it was knowable at that instant: rows collected later are absent, and values revised later are rolled back to what was published at the time (revision correction coverage since 2026-07-28). Built for backtests — no lookahead bias. curl -H "Authorization: Token YOUR_API_KEY" \ "https://api.oilpriceapi.com/v1/prices/past_month?by_code=DIESEL_USD&as_of=2026-08-06" Rules: ISO8601 date or datetime; must not be in the future; requires interval=raw (the default). Response carries X-Vintage-As-Of and X-Vintage-Revision-Coverage-Since headers. Values from before we began collecting a series have no vintages, by construction. ### 9. GET /v1/commodities — List All Commodity Codes Returns every available commodity code with metadata (currency, unit, category). curl -H "Authorization: Token YOUR_API_KEY" \ "https://api.oilpriceapi.com/v1/commodities" Sample response: { "status": "success", "data": { "commodities": [ { "code": "BRENT_CRUDE_USD", "name": "Brent Crude Oil", "currency": "USD", "unit": "barrel", "category": "oil" }, { "code": "WTI_USD", "name": "WTI Crude Oil", "currency": "USD", "unit": "barrel", "category": "oil" } ] } } ### 10. GET /v1/prices/latest?by_code=...&format=csv — CSV Format Append `format=csv` to any endpoint to receive CSV output instead of JSON. curl -H "Authorization: Token YOUR_API_KEY" \ "https://api.oilpriceapi.com/v1/prices/latest?by_code=BRENT_CRUDE_USD&format=csv" ### 11. GET /v1/prices — Price Index Returns paginated price history for a commodity. curl -H "Authorization: Token YOUR_API_KEY" \ "https://api.oilpriceapi.com/v1/prices?by_code=BRENT_CRUDE_USD&page=1&per_page=100" ### 12. Marine Fuel Endpoints GET /v1/prices/marine-fuels — All marine fuel prices GET /v1/prices/marine-fuels/latest — Latest marine fuel prices GET /v1/prices/marine-fuels/ports — Available port list GET /v1/prices/marine-fuels/historical — Historical marine fuel prices ### 13. Storage & Drilling Intelligence GET /v1/storage/cushing — Cushing, OK storage levels (Reservoir Mastery tier) GET /v1/drilling/latest — Rigs vs frac spreads, upstream activity (Scale $299/mo or drilling plan) ### 14. GET /v1/natural-gas/hubs — US Physical Gas Hubs (Developer $19/mo and up) US physical natural gas hubs priced as basis to Henry Hub (USD/MMBtu): Waha, SoCal Citygate, Chicago Citygate, Algonquin Citygate, Eastern Gas South (formerly Dominion South), Houston Ship Channel. Hub histories differ in depth — each hub carries history_since / history_days; check before requesting a long window. GET /v1/natural-gas/hubs — every live hub + basis to Henry Hub GET /v1/natural-gas/hubs/:hub — one hub + basis history (?past=30d|6m|1y) curl -H "Authorization: Token YOUR_API_KEY" \ "https://api.oilpriceapi.com/v1/natural-gas/hubs/waha?past=30d" ### 15. Futures Endpoints (Professional $99/mo and up) Contract slugs: ice-brent (BZ), ice-wti (CL), ice-gasoil, natural-gas (NG), ttf-gas (TTF), lng-jkm (JKM), eua-carbon (EUA), uk-carbon (UKA). GET /v1/futures/:slug — latest front-month + contracts GET /v1/futures/:slug/curve — full forward curve, all contract months ### 16. GET /v1/spreads/:type — Refining & Trading Spreads (Professional $99/mo and up) Crack spreads, 3-2-1, refining margins, basis differentials. ### 17. Fuel Surcharge Endpoints (all plans, including Free) GET /v1/fuel-surcharge — all carriers, latest GET /v1/fuel-surcharge/:carrier/latest — one LTL carrier GET /v1/fuel-surcharge/:carrier/history — one carrier's history GET /v1/fuel-surcharge/parcel/:carrier/latest — parcel carriers GET /v1/fuel-surcharge/parcel/:carrier/history ### 18. Energy Intelligence (Reservoir Mastery premium tier) GET /v1/rig-counts/latest — Baker Hughes US rig counts GET /v1/ei/opec_productions/latest — OPEC country-level production GET /v1/ei/oil_inventories/latest — EIA weekly petroleum stocks GET /v1/ei/oil_inventories/summary — headline totals + WoW change GET /v1/ei/oil_inventories/by_product — per-product breakdown GET /v1/ei/forecasts/latest — EIA STEO price forecasts Well permits (well-permits add-on or enterprise plan; bounded free preview): GET /v1/ei/well-permits/latest GET /v1/ei/well-permits/search GET /v1/ei/well-permits/by-state GET /v1/ei/well-permits/by-operator GET /v1/well-production/states/:state_code GET /v1/well-production/wells/:api_number ### 19. GET /v1/market_brief — Multi-Commodity Market Brief (all plans; per-tier commodity caps) curl -H "Authorization: Token YOUR_API_KEY" \ "https://api.oilpriceapi.com/v1/market_brief" ### 20. Alerts & Subscriptions (account-tied; per-tier limits) GET/POST /v1/alerts — persistent price alerts (CRUD) DELETE /v1/alerts/:id GET/POST /v1/subscriptions — recurring price watches for agents DELETE /v1/subscriptions/:id GET /v1/subscriptions/:id/events — poll snapshots Subscription interval floors by tier: free 1h, developer 30m, starter 15m, professional and up 5m. ### 21. Data Quality (summary: any key; per-commodity reports: paid plans) Per-series quality grades and dimension scores (completeness, freshness), computed per period from measured data — not marketing copy. GET /v1/data-quality/summary — catalogue-wide grade distribution GET /v1/data-quality/reports/:code — one series' quality report ### 22. Account & Plans GET /v1/dashboard — your plan tier, usage, remaining quota, reset date GET /v1/pricing — live plan ladder (public, no key required) ## Commodity Codes — Complete List ### Crude Oil BRENT_CRUDE_USD Brent Crude Oil (USD/barrel) — global benchmark WTI_USD WTI Crude Oil (USD/barrel) — US benchmark DUBAI_CRUDE_USD Dubai Crude (USD/barrel) — Asia/Middle East benchmark OPEC_BASKET_USD OPEC Reference Basket (USD/barrel) URALS_CRUDE_USD Urals Crude (USD/barrel) — Russian export grade. Daily data from Oct 2025; sparse before that. LOUISIANA_LIGHT_USD Louisiana Light Sweet (USD/barrel) MARS_USD Mars Blend (USD/barrel) — Gulf of Mexico sour TAPIS_CRUDE_USD Tapis Crude (USD/barrel) — Asia-Pacific light sweet AZERI_LIGHT_USD Azeri Light (USD/barrel) — Caspian/Mediterranean benchmark BASRAH_MEDIUM_USD Basrah Medium (USD/barrel) — Iraqi export BASRAH_HEAVY_USD Basrah Heavy (USD/barrel) — Iraqi heavy grade WCS_CRUDE_USD Western Canadian Select (USD/barrel) ANS_WEST_COAST_USD Alaska North Slope (USD/barrel) MIDLAND_WTI_USD Midland WTI (USD/barrel) — Permian Basin ### Natural Gas NATURAL_GAS_USD Henry Hub Natural Gas (USD/MMBtu) — US benchmark DUTCH_TTF_EUR Dutch TTF Gas (EUR/MWh) — European benchmark DUTCH_TTF_NATURAL_GAS_USD Dutch TTF in USD NATURAL_GAS_GBP UK Natural Gas (GBp/therm) — NBP benchmark JKM_LNG_USD JKM LNG (USD/MMBtu) — Asian LNG benchmark NATURAL_GAS_WAHA Waha Hub Natural Gas (USD/MMBtu) — see also /v1/natural-gas/hubs NYMEX_APPALACHIAN_USD Appalachian Natural Gas (USD/MMBtu) NYMEX_WESTERN_RAIL_USD Western Rail Natural Gas (USD/MMBtu) ### Refined Products GASOLINE_USD Gasoline (USD/gallon) GASOLINE_RBOB_USD RBOB Gasoline (USD/gallon) HEATING_OIL_USD Heating Oil (USD/gallon) DIESEL_USD Diesel (USD/gallon) — wholesale ULSD_DIESEL_USD Ultra-Low Sulfur Diesel (USD/gallon) JET_FUEL_USD Jet Fuel US Gulf Coast (USD/gallon) JET_A1_NWE_USD Unavailable since 2026-07; preserved for historical/audit lookup only. Use JET_FUEL_USD or JET_FUEL_A4A_USD for active aviation fuel data. ETHANOL_USD Ethanol (USD/gallon) PROPANE_MONT_BELVIEU_USD Propane Mont Belvieu (USD/gallon) ### Chemicals & Petrochemicals ASPHALT_USD Asphalt (USD/ton, EIA monthly) ETHYLENE_USD Ethylene (USD/ton, derived from CNY via live forex) ETHYLENE_CNY Ethylene (CNY/ton, Chinese domestic market) METHANOL_USD Methanol (USD/ton, derived from CNY via live forex) METHANOL_CNY Methanol (CNY/ton, Zhengzhou Commodity Exchange) NAPHTHA_USD Naphtha (USD/barrel) POLYETHYLENE_USD Polyethylene (USD/ton, derived from CNY via live forex) POLYETHYLENE_CNY Polyethylene (CNY/ton, Dalian Commodity Exchange) POLYPROPYLENE_USD Polypropylene (USD/ton, derived from CNY via live forex) POLYPROPYLENE_CNY Polypropylene (CNY/ton, Dalian Commodity Exchange) UREA_USD Urea (USD/ton) ### Diesel Retail (US Regional) DIESEL_RETAIL_USD US Average Diesel Retail (USD/gallon) DIESEL_RETAIL_EAST_COAST_USD East Coast Diesel Retail DIESEL_RETAIL_MIDWEST_USD Midwest Diesel Retail DIESEL_RETAIL_GULF_COAST_USD Gulf Coast Diesel Retail DIESEL_RETAIL_ROCKY_MOUNTAIN_USD Rocky Mountain Diesel Retail DIESEL_RETAIL_WEST_COAST_USD West Coast Diesel Retail DIESEL_RETAIL_CALIFORNIA_USD California Diesel Retail ### Coal COAL_USD Thermal Coal (USD/ton) NEWCASTLE_COAL_USD Newcastle Coal (USD/ton) — Asia-Pacific benchmark CAPP_COAL_USD Central Appalachian Coal (USD/ton) PRB_COAL_USD Powder River Basin Coal (USD/ton) CME_COAL_USD CME Coal (USD/ton) COKING_COAL_USD Coking/Metallurgical Coal (USD/ton) ILLINOIS_COAL_USD Illinois Basin Coal (USD/ton) CAPP_COAL_ANNUAL_USD CAPP Coal Annual Contract (USD/ton) PRB_COAL_ANNUAL_USD PRB Coal Annual Contract (USD/ton) ILLINOIS_COAL_ANNUAL_USD Illinois Coal Annual Contract (USD/ton) ### Marine Fuels VLSFO_USD Very Low Sulfur Fuel Oil (USD/ton) MGO_05S_USD Marine Gasoil 0.5% Sulfur (USD/ton) HFO_180_USD Heavy Fuel Oil 180 CST (USD/ton) HFO_380_USD Heavy Fuel Oil 380 CST (USD/ton) ### Asia-Pacific Products (Singapore) SINGAPORE_GASOIL_USD Singapore Gasoil/Platts (USD/barrel) — MOPS middle distillate benchmark SINGAPORE_JET_KEROSENE_USD Unavailable since 2026-07; preserved for historical/audit lookup only until source QA is restored. SINGAPORE_MOGAS_92_USD Singapore Mogas 92/Platts (USD/ton) — MOPS RON 92 gasoline benchmark ### Carbon Allowances EU_CARBON_EUR EU ETS Carbon Allowance (EUR/tCO2) UK_CARBON_GBP UK ETS Carbon Allowance (GBP/tCO2) ### Precious Metals GOLD_USD Gold Spot (USD/troy oz) SILVER_USD Silver Spot (USD/troy oz) PLATINUM_USD Platinum Spot (USD/troy oz) PALLADIUM_USD Palladium Spot (USD/troy oz) ### LBMA Fixes (London Bullion Market Association) GOLD_AM_USD LBMA Gold AM Fix (USD/troy oz) GOLD_AM_GBP LBMA Gold AM Fix (GBP/troy oz) GOLD_AM_EUR LBMA Gold AM Fix (EUR/troy oz) GOLD_PM_USD LBMA Gold PM Fix (USD/troy oz) GOLD_PM_GBP LBMA Gold PM Fix (GBP/troy oz) GOLD_PM_EUR LBMA Gold PM Fix (EUR/troy oz) SILVER_FIX_USD LBMA Silver Fix (USD/troy oz) SILVER_FIX_GBP LBMA Silver Fix (GBP/troy oz) SILVER_FIX_EUR LBMA Silver Fix (EUR/troy oz) ### Base Metals COPPER_USD Copper (USD/ton) — LME benchmark ALUMINUM_USD Aluminum (USD/ton) — LME benchmark ZINC_USD Zinc (USD/ton) — LME benchmark NICKEL_USD Nickel (USD/ton) — LME benchmark LEAD_USD Lead (USD/ton) — LME benchmark TIN_USD Tin (USD/ton) — LME benchmark IRON_ORE_USD Iron Ore (USD/ton) — 62% Fe CFR China benchmark ### Nuclear URANIUM_USD Uranium (USD/lb) ### Forex Pairs EUR_USD Euro / US Dollar GBP_USD British Pound / US Dollar USD_CNY US Dollar / Chinese Yuan EUR_NOK Euro / Norwegian Krone USD_NOK US Dollar / Norwegian Krone ### Futures (Scale / Add-on Access) BRENT_FUTURES Brent Crude Futures (front-month) BRENT_FUTURES_CONTINUOUS Brent Futures Continuous (auto-rolled) WTI_FUTURES WTI Crude Futures (front-month) WTI_FUTURES_CONTINUOUS WTI Futures Continuous (auto-rolled) NATGAS_FUTURES Natural Gas Futures GASOIL_FUTURES ICE Gasoil Futures EU_CARBON_FUTURES EU Carbon Futures GOLD_FUTURES COMEX Gold Futures ### Storage Data (Scale / Add-on Access) CUSHING_STORAGE Cushing, OK Crude Storage (million barrels) NATURAL_GAS_STORAGE US Natural Gas Storage (Bcf) ### Drilling Intelligence (Scale / Add-on Access) US_RIG_COUNT Baker Hughes US Active Rig Count CANADA_RIG_COUNT Baker Hughes Canada Active Rig Count INTERNATIONAL_RIG_COUNT Baker Hughes International Rig Count US_FRAC_SPREAD_COUNT US Frac Spread Count ### Regional Drilling Data (Scale / Add-on Access) PERMIAN_WELLS_DRILLED Permian Basin wells drilled PERMIAN_WELLS_COMPLETED Permian Basin wells completed PERMIAN_DUC_WELLS Permian Basin drilled uncompleted wells PERMIAN_FRAC_SPREADS Permian Basin frac spread count BAKKEN_WELLS_DRILLED Bakken wells drilled BAKKEN_WELLS_COMPLETED Bakken wells completed BAKKEN_DUC_WELLS Bakken drilled uncompleted wells BAKKEN_FRAC_SPREADS Bakken frac spread count EAGLEFORD_WELLS_DRILLED Eagle Ford wells drilled EAGLEFORD_WELLS_COMPLETED Eagle Ford wells completed EAGLEFORD_DUC_WELLS Eagle Ford drilled uncompleted wells EAGLEFORD_FRAC_SPREADS Eagle Ford frac spread count NIOBRARA_WELLS_DRILLED Niobrara wells drilled NIOBRARA_WELLS_COMPLETED Niobrara wells completed NIOBRARA_DUC_WELLS Niobrara drilled uncompleted wells HAYNESVILLE_WELLS_DRILLED Haynesville wells drilled HAYNESVILLE_WELLS_COMPLETED Haynesville wells completed HAYNESVILLE_DUC_WELLS Haynesville drilled uncompleted wells APPALACHIA_WELLS_DRILLED Appalachia wells drilled APPALACHIA_WELLS_COMPLETED Appalachia wells completed APPALACHIA_DUC_WELLS Appalachia drilled uncompleted wells ANADARKO_WELLS_DRILLED Anadarko wells drilled ANADARKO_WELLS_COMPLETED Anadarko wells completed ANADARKO_DUC_WELLS Anadarko drilled uncompleted wells ### Well Permit Data (Scale / Add-on Access) TEXAS_WELL_PERMITS Texas well permits issued NORTH_DAKOTA_WELL_PERMITS North Dakota well permits issued OKLAHOMA_WELL_PERMITS Oklahoma well permits issued ### Shorthand Aliases BRENT → BRENT_CRUDE_USD WTI → WTI_USD GOLD → GOLD_USD NATGAS → NATURAL_GAS_USD TTF → DUTCH_TTF_EUR ## Price Field Explanation The `price` field is the actual market price in the commodity's native currency. No conversion or division is needed. Examples: - BRENT_CRUDE_USD price: 78.41 means $78.41 per barrel - GOLD_USD price: 2948.50 means $2,948.50 per troy ounce - NATURAL_GAS_USD price: 4.12 means $4.12 per MMBtu - EU_CARBON_EUR price: 68.50 means 68.50 EUR per tonne of CO2 - NATURAL_GAS_GBP price: 80.0 means 80.0 pence per therm (NOT pounds) ## Pricing Plans Plan Price Requests/Month ─────────────────────────────────────────────── Free $0 200 Developer $19/mo 10,000 Starter $49/mo 50,000 Professional $99/mo 100,000 Scale $299/mo 1,000,000 Enterprise Custom Custom Annual billing: 2 months free on all paid plans. Historical depth and futures, storage, drilling, and other dataset access vary by plan and account entitlement. Use the pricing page and account response for the current effective access. ## Error Codes HTTP Status Meaning ───────────────────────────────────────────────────────── 200 Success 400 Invalid parameters (bad commodity code, invalid interval, etc.) 401 Missing or invalid API key 402 Free tier quota exhausted — upgrade to continue 403 Feature requires a paid addon or higher tier 429 Paid tier monthly limit exceeded 503 Temporary server overload — retry after 5 seconds 504 Query timeout — narrow your request (shorter date range) ## SDKs Python: pip install oilpriceapi JavaScript: npm install oilpriceapi Go: go get github.com/OilpriceAPI/oilpriceapi-go Ruby: gem install oilpriceapi C#: NuGet package "OilPriceAPI" ## MCP Server (for Claude, Cursor, AI Coding Tools) npm install -g oilpriceapi-mcp Configure in your MCP client to give AI agents direct access to commodity price data. ## Integrations Google Sheets: https://docs.oilpriceapi.com/integrations/google-sheets Power BI: https://docs.oilpriceapi.com/integrations/power-bi Zapier: https://docs.oilpriceapi.com/integrations/zapier n8n: https://docs.oilpriceapi.com/integrations/n8n ## Agent Best Practices 1. Use POST /v1/prices/batch for multiple commodities — counts as 1 request. 2. Cache responses for at least 60 seconds. Prices update every 1-2 minutes. 3. Check X-RateLimit-Remaining before making additional requests. 4. Start with GET /v1/demo/prices — no auth needed, perfect for testing. 5. Free tier (200 req/month) is sufficient for validation and prototyping. 6. Use `interval=daily` on historical endpoints for manageable response sizes. 7. Parse the `price` field directly — it is the real market price, no conversion needed. 8. On 429 or 503 errors, wait 5 seconds and retry once. ## Quick Start for Agents Step 1 — Test connectivity (no auth): curl https://api.oilpriceapi.com/v1/demo/prices Step 2 — Sign up for a free API key: https://www.oilpriceapi.com/auth/signup Step 3 — Fetch a live price: curl -H "Authorization: Token YOUR_API_KEY" \ "https://api.oilpriceapi.com/v1/prices/latest?by_code=BRENT_CRUDE_USD" Step 4 — Fetch multiple prices efficiently: curl -X POST \ -H "Authorization: Token YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"codes": ["BRENT_CRUDE_USD", "WTI_USD", "GOLD_USD"]}' \ "https://api.oilpriceapi.com/v1/prices/batch" ## Support Email: karl@oilpriceapi.com Docs: https://docs.oilpriceapi.com Health: https://api.oilpriceapi.com/health Status: https://api.oilpriceapi.com/status.html