Changelog

All notable changes to the OilPriceAPI are documented here.

The format is based on Keep a Changelog.

September 2026

Added

  • Denmark diesel list prices, daily since 2002 — DIESEL_LIST_OK_DK_DKK (OK Danmark's station diesel list price) and DIESEL_TRUCK_LIST_OK_DK_DKK (OK's truck-station list, which matches the Danish majors' daily diesel list). DKK per litre, duties and 25% VAT included, before customer discounts, one value per calendar day with as_of on the day it applies; the same price ex VAT and ex duties is in each row's metadata. History back to 2002-08-23 via /v1/prices/historical.

Changed

  • Live-freshness refusal on gasoil and Henry Hub natural-gas futures — when the market is open and intraday data falls behind the freshness bound, /v1/futures/ice-gasoil and /v1/futures/natural-gas return 503 LIVE_DATA_STALE with the market-hours context (freshness_status, market_status, stale_by_minutes, market_timezone, …) instead of serving stale ticks (their /intraday endpoints refuse under the same rule). Distinct from the 96-hour DATA_TOO_STALE bound, which is checked first and applies at all hours.

  • Interval aliases — every historical endpoint accepts the same alias spellings per family (1h/h/hour/1hour, 1d/d/day/1day, 1w/w/week/1week, 1m/m/month/1month), case-insensitively, and an unknown spelling on /v1/prices/historical returns 400 listing valid_intervals. Endpoints that previously tolerated unknown intervals keep their fallback behaviour.

  • Gasoil crack at weekends — /v1/spreads/gasoil-crack now uses the same 96-hour serving bound as the futures endpoints, so weekend and holiday closures serve the last trading session instead of returning 404.

August 2026

Added

  • European gasoil crack — GET /v1/spreads/gasoil-crack: ICE Low Sulphur Gasoil (USD/tonne ÷ 7.45) against ICE Brent in USD/bbl, with each leg's contract_month and the conversion applied.
  • Point-in-time history — past_day, past_week, past_month and past_year accept ?as_of=<ISO 8601> (requires interval=raw) and answer with X-Vintage-As-Of and X-Vintage-Revision-Coverage-Since headers. Revisions are tracked from 2026-07-28. past_day?at=YYYY-MM-DD returns one calendar day, and /v1/prices/YYYY-MM-DD is an alias that serves that lookup directly (no redirect; the near-miss aliases stopped redirecting in September 2026). See Historical.
  • Swap disclosures — SINGAPORE_JET_KEROSENE_USD and SINGAPORE_MOGAS_92_USD are calendar-month average futures, not spot prices. /v1/prices/latest and /v1/commodities/{code} return an instrument_disclosure object for them (with contract_month when known); past_* and historical carry metadata.instrument_disclosures[]. Omitted from CSV.
  • Withheld historical values — historical responses carry metadata.quarantine when verified-unreliable dates were excluded from the window. Source rows are not deleted.
  • Discovery hint — /v1/prices/latest may include an additive metadata.discover {endpoint, description} for accounts using few endpoints; safe to ignore.
  • Machine-readable tier limits — GET /v1/meta/limits (alias /limits.json, no key) returns the current Free, trial and paid-plan limits with their windows. Product facts are published under schema 2.0.0 with /schemas/product-facts-v2.schema.json. GET /v1/health is a keyless liveness alias.
  • Futures bars carry open_interest alongside volume; /v1/futures/*/curve contracts carry expiry_date, and contracts past their last trading day are excluded from the curve.
  • Futures OHLC history to five years — days on /v1/futures/*/ohlc accepts up to 1825; larger values are served as 1825 with truncated: true, days_requested and days_served.
  • Rig counts — /v1/rig-counts/historical accepts period and by_period windows up to 15 years (weekly data held back to 2013-01-04); the period object reports coverage_from, coverage_to, earliest_available, observations and complete; responses paginate at 100 with Link headers.
  • Well permits freshness — as_of on /v1/ei/well-permits/* is the newest permit_date held (not the request time), with data_age_days, stale and as_of_basis; multi-state responses add by_state_as_of and stale_states.
  • Well production — /v1/well-production/summary national reports data_available and provisional instead of null or zero while state filings are still landing; GET /v1/well-production/wells/:api_number 404s include reason (unknown_state_prefix, state_not_covered, well_not_in_source) with state and source.
  • Drilling intelligence — per-state current_activity_status, indexing_recommendation and current_activity_reason on /v1/pseo/drilling-intelligence/states/:state/full and /v1/ei/well-permits/states/:state_code.
  • Spreads history — /v1/spreads/crack/historical reports coverage (from, to, observations, complete) and data_revised_at.
  • Six physical crude benchmarks — BONNY_LIGHT_USD, ESPO_CRUDE_USD and JOHAN_SVERDRUP_USD join MURBAN_CRUDE_USD, MARS_USD and LOUISIANA_LIGHT_USD; each has its own publication cadence, so read as_of, data_status and stale per series.
  • Better invalid_code errors — the 400 body includes did_you_mean[] with code, name, description, available and, when false, unavailable_reason; when a suggested code is not in the default /v1/commodities listing the message points at ?include_unavailable=true. WCS, CANADIAN_CRUDE, CANADIAN_CRUDE_USD, WESTERN_CANADIAN_SELECT and WESTERN_CANADIAN_SELECT_USD resolve to WCS_CRUDE_USD.
  • Query-parameter authentication — ?api_key= is accepted on GET/HEAD for clients that cannot send headers (Google Sheets IMPORTDATA); an Authorization header always wins.
  • Marine fuels — /v1/prices/marine-fuels/latest and /historical accept port_code (the OpenAPI name); port remains an alias.

Changed

  • Quota errors by plan — the Free tier returns 402 Payment Required (PAYMENT_REQUIRED) when its daily quota is used up; paid plans and trials return 429 with MONTHLY_QUOTA_EXCEEDED / TRIAL_LIMIT_EXCEEDED, distinct from the rolling-window RATE_LIMIT_EXCEEDED. Every quota block carries current_usage, reset (the real window end), efficiency and reduce_usage — the free ways to need fewer requests — and the Free-tier 402 also sizes recommended_plan on attempted volume. Full body on Rate Limiting.
  • A 304 Not Modified no longer counts against your quota (it still uses a rate-limit slot). Send If-None-Match with the ETag from your previous response.
  • X-RateLimit-Window (daily_counter, monthly_counter, trial_counter) and X-RateLimit-State headers say which window the X-RateLimit-* counters describe. The X-Monthly-Remaining header never existed; use X-RateLimit-Remaining.
  • Futures on the Free tier — free-plan calls to /v1/futures/* count against the daily allowance and return 402 FREE_TIER_LIMIT_EXCEEDED past it. Futures Data is included in Professional and above and available to other paid plans as a $39/month add-on; the 403 names the add-on and links to billing.
  • Stale futures are refused, not warned — /v1/futures/* returns 503 DATA_TOO_STALE (data_age_hours, max_age_hours: 96, last_updated) when the newest quote is older than 96 hours. Quotes 1–96 hours old are served with data_age_warning.
  • settlement on futures bars is the exchange-published settlement when captured and null otherwise; it is no longer a copy of close.
  • Spreads on trial — active 7-day trials can call /v1/spreads/*.
  • /v1/commodities default listing omits codes not backed by data even where they remain callable; pass ?include_unavailable=true for every configured code with has_data and a reason.
  • Suspended or over-quota keys are throttled to 5 requests per rolling 60 seconds rather than left unthrottled.
  • Congressional trades marked not live — /v1/indicators/congressional-trades returns 404 DATA_NOT_AVAILABLE until its source is configured and is excluded from the public OpenAPI contract.

Documentation

  • Every remaining reference to the retired monthly free-tier allowance now reads 50 requests per day, across the API reference, integration guides, comparison pages, tools and blog; the lint rule that guards this copy now catches the phrasings it previously missed.
  • Futures and spreads pages match the current response shapes (settlement, open_interest, expiry_date, days ceiling, plan and add-on access); the stale spreads entitlement caveat is gone.
  • /api-reference/ei/drilling-intelligence, /api-reference/spreads/gasoil-crack and /api-reference/prices/demo are in the sidebar.

Changed (earlier in August)

  • Free tier is now 50 requests per day, replacing the previous 200 requests per month (effective 2026-08-05). The window changed as well as the number: the allowance now resets daily rather than monthly, so a 402 Payment Required on the Free tier clears at the next daily reset instead of the next month. In monthly terms the allowance is roughly 7.5x larger than before. Paid plans are unchanged and remain monthly: Developer 10,000/month, Starter 50,000/month, Professional 100,000/month, Scale 1,000,000/month. See Rate Limiting for the full table.

July 2026

Added

  • UK carbon (UKA) forward curve — GET /v1/futures/uk-carbon/curve, term-structure analysis parallel to eua-carbon/curve. Note the URL slug is uk-carbon (contract codes remain UKA_FUTURES_*).
  • Fuel Surcharge API reference for carrier-published LTL and parcel surcharge schedules:
  • API reference coverage for spreads, market indicators, bunker and maritime fuels, gas/LNG futures, UK carbon futures, webhooks, alerts, account status, API keys, subscriptions, organizations, and price utility endpoints.
  • Data-rights guidance for internal use, public display, redistribution, and downstream productization review.
  • Documentation guardrails for unsupported market-data claims and phantom endpoint drift.

Changed

  • Published OpenAPI examples now use Authorization: Token YOUR_API_KEY for API keys, retain Bearer only for JWT sessions, advertise only the production API server, and explain recovery for payment, rate-limit, and transient server errors.
  • Commodity catalog pages now use source-timestamped freshness language, omit stale generated price/date snapshots, and provide direct Python and JavaScript quickstarts for every catalog entry.
  • Replaced broad "real-time" claims with source timestamp and documented update-cadence language where users need to evaluate freshness.
  • Removed phantom /v1/drilling/* paths and corrected marine fuel paths in the published OpenAPI file.
  • Standardized data-source labels. The source / data_source fields in API responses now report a consistent value for non-government data: series drawn from published market reporting return market_reporting, while government-sourced series continue to name their agency (for example EIA, OPEC). This aligns our responses with our Data Provenance & Rights policy: OilPriceAPI is a data collection and delivery service, and we are not affiliated with or a licensed distributor of any exchange or price-reporting agency. If your integration branches on the source string, update it to treat market_reporting as the label for non-government sources. The underlying prices and endpoints are unchanged.

June 2026

Added

May 2026

Added

  • ICE JKM LNG futures — GET /v1/futures/lng-jkm (with /historical, /curve, /ohlc, /intraday, /spreads)
  • UK carbon (UKA) futures — GET /v1/futures/uk-carbon (with /historical)
  • Excel API gateway — GET /v1/excel/run and GET /v1/prices/excel-latest backing the Excel add-in
  • Developer plans now allow up to 3 API keys
  • Futures responses expose front-month contract-selection semantics

April 2026

Added

  • Calculated Metrics API — GET /v1/spreads/*: crack spreads, basis spreads, curve structure, refinery margin, and physical (spot-vs-futures) premium, each with /historical and /all variants
  • Market intelligence — market annotations, CFTC positioning, and storage analytics
  • Well Production Data — TX RRC well-level scraper and Enterprise API (foundation for the June four-state launch)
  • 21 new physical commodity spot prices (EIA, EEX, NGI, ACER sources)
  • Macro economic indicators (FRED integration) and an economic release calendar
  • GET /v1/futures/ice-brent now returns the front-month contract and its codes
  • /v1/prices auto-downsamples long windows for intraday commodity codes

December 2025

Added

  • 7-day free trial with 10,000 requests, followed by the Free tier with 200 requests/month
  • New onboarding email sequence for first-time users
  • Improved documentation with multi-language code examples

Changed

  • Trial accounts now receive full API access during trial period
  • Updated Quick Start guide with troubleshooting section

November 2025

Added

  • 8 new coal commodity endpoints:
    • COAL_USD - Newcastle Thermal Coal
    • COAL_EUR - Rotterdam Coal
    • COKING_COAL_USD - Premium Hard Coking Coal
    • COAL_SOUTH_AFRICA_USD - Richards Bay Coal
    • COAL_INDONESIA_USD - Indonesian Coal (ICI4)
    • COAL_CHINA_USD - China Qinhuangdao Coal
    • COAL_AUSTRALIA_USD - Australian Thermal Coal
    • ANTHRACITE_USD - Anthracite Coal

Improved

  • Coal price update frequency now daily (previously weekly)

October 2025

Added

  • WebSocket streaming for real-time price updates (Professional+ plans)
  • WS_CONNECT endpoint at wss://api.oilpriceapi.com/cable
  • Real-time subscription channels for individual commodities

Changed

  • WebSocket connections now require Professional plan or higher
  • Improved connection stability with automatic reconnection

September 2025

Improved

  • Rate limit headers now include X-RateLimit-Used and X-RateLimit-Tier
  • Response time headers added to all endpoints

Correction (July 2026)

Earlier revisions of this changelog listed an "X-App-URL header bonus" (10% extra monthly requests) and related telemetry headers under this month. That feature was never built and does not exist in the API. Sending X-App-URL has no effect on your quota. The entry has been removed. See Authentication for the headers the API actually reads.

August 2025

Added

  • Bunker fuel endpoints for maritime industry:
    • VLSFO_USD - Very Low Sulphur Fuel Oil
    • HSFO_USD - High Sulphur Fuel Oil
    • MGO_USD - Marine Gas Oil
    • Bunker prices for 20+ major ports worldwide

Improved

  • Added source-specific refresh scheduling and timestamps for bunker-fuel values

July 2025

Added

  • Energy Intelligence endpoints (premium plans):
    • /v1/rig-counts/latest - Active rig counts by region
    • /v1/drilling-intelligence/well-permits - Well permit datasets
    • /v1/drilling-intelligence/summary - Energy intelligence summary

Fixed

  • Resolved intermittent 504 timeouts on historical endpoints
  • Fixed pagination on /v1/prices/past_month endpoint

June 2025

Added

  • Futures pricing endpoints:
    • /v1/futures/wti - WTI crude oil futures
    • /v1/futures/brent - Brent crude futures
    • /v1/futures/natural-gas - Natural gas futures
  • Contract expiration dates in futures responses

Changed

  • Historical data endpoints now support date range queries
  • Added start_date and end_date parameters

May 2025

Added

  • Currency conversion for all commodities:
    • _USD, _EUR, _GBP suffixes available
    • Real-time forex rates applied
  • New currency parameter on all price endpoints

Improved

  • Response times reduced by 40% with edge caching
  • Added Cloudflare CDN for global performance

April 2025

Added

  • Natural gas regional pricing:
    • NATURAL_GAS_EUR - European TTF
    • NATURAL_GAS_ASIA - JKM Asian LNG
    • DUTCH_TTF_GAS_EUR - Dutch TTF Natural Gas

Fixed

  • Corrected Business Insider data source parsing
  • Fixed timezone issues in created_at timestamps

March 2025

Added

  • Refined products expansion:
    • JET_FUEL_USD - Jet Fuel (Kerosene)
    • GASOLINE_USD - RBOB Gasoline
    • HEATING_OIL_USD - Heating Oil No. 2
    • DIESEL_USD - Ultra Low Sulfur Diesel

Changed

  • All prices now include metadata.source_description
  • Improved source accuracy documentation

February 2025

Added

  • Account endpoint /v1/account for usage tracking
  • Request analytics in dashboard
  • Geographic usage breakdown

Improved

  • Rate limit error messages now include reset time
  • Added Retry-After header on 429 responses

January 2025

Launch

  • OilPriceAPI v1 launched
  • Core endpoints:
    • /v1/prices/latest - Current prices
    • /v1/prices/past_day - 24-hour history
    • /v1/prices/past_week - 7-day history
    • /v1/prices/past_month - 30-day history
    • /v1/commodities - List all commodities
  • Initial commodities: WTI, Brent, Natural Gas
  • Token-based authentication
  • Rate limiting with usage headers

API Versioning Policy

  • v1 is stable: No breaking changes without 90-day notice
  • Deprecations: Announced via email and changelog
  • New features: Added without version bump
  • Breaking changes: Will trigger v2 with migration guide

Support

Last Updated: