OilPriceAPI Docs
Quick Start
API Reference
  • SDKs and languages
  • Tutorials
  • Articles
  • Documentation directory
  • Quick reference
  • API explorer
  • FAQ
  • Changelog
  • Status
  • Dashboard
GitHub
Quick Start
API Reference
  • SDKs and languages
  • Tutorials
  • Articles
  • Documentation directory
  • Quick reference
  • API explorer
  • FAQ
  • Changelog
  • Status
  • Dashboard
GitHub
  • Interactive Explorer

    • Interactive API Explorer
  • Price Data

    • API Reference
    • Get Latest Prices
    • Historical Prices
    • Batch Prices
    • Excel Latest Price Gateway
    • Price Widget Endpoints
    • Price Utility Endpoints
    • Demo API (No Authentication)
    • Natural Gas Intelligence
    • Energy News Feed
  • Commodities

    • List Commodities
    • Get Commodity Details
    • Denmark diesel list prices (OK Danmark)
    • Data Publication & Collection Schedules
  • AI Agents (MCP)

    • Get Market Brief
    • Subscriptions / Watches
    • Agent Subscriptions with MCP
  • Marine Fuels

    • Marine Fuel API
    • List Marine Fuel Ports
    • Get Port Details with Prices
    • Bunker Fuels
    • Maritime Fuels
  • Fuel Surcharges

    • Fuel Surcharge API
  • Premium Endpoints

    • All Prices API - One Call, All Commodities
    • Cushing Oil Storage Intelligence API
    • Drilling Intelligence API
    • Marine Fuels API
    • ICE Brent Futures API
    • Aviation Fuel Pilot
  • Spreads & Margins

    • Spreads & Margins
    • Crack Spreads
    • European Gasoil Crack
    • Basis Spreads
    • Refining Margins
    • Curve Structure
    • Physical Premiums
  • Market Indicators

    • Market Indicators
    • Fuel Switching
    • Price Context
    • Storage Analytics
    • CFTC Positioning
    • Market Annotations
  • Futures

    • Futures API
    • ICE Brent Futures
    • WTI Futures
    • Continuous Futures (Brent, WTI)
    • ICE Gas Oil Futures
    • NYMEX Natural Gas Futures
    • ICE EUA Carbon Futures
    • EU Carbon Futures
    • TTF Gas Futures
    • LNG JKM Futures
    • UK Carbon Futures
  • Dark Data (Premium)

    • Energy Intelligence API
    • Rig Counts
    • Well Permits
    • Well Production Beta
    • Drilling Intelligence (Public)
    • Oil Inventories
    • OPEC Production
    • Drilling Productivity
    • Forecasts (STEO)
  • Well Production (Beta)

    • Well Production Data
    • Well Production API Reference
  • Analytics

    • Analytics API
  • Webhooks API

    • Webhooks API Reference
    • Webhook Endpoint Reference
  • Alerts

    • Price Alerts API
  • Scheduled Deliveries

    • Scheduled Deliveries API
  • Account & Billing

    • Account API
    • API Keys
    • Subscriptions
    • Organizations

Futures API

Latest available and historical futures data for energy commodities. Access contract prices, spreads, curves, and OHLC data with source timestamps.

Available Commodities

CommodityExchangeBase EndpointContracts
Brent CrudeICE/v1/futures/ice-brent12 months
WTI CrudeNYMEX / ICE/v1/futures/ice-wti or /v1/futures/nymex-wti12 months
Gas OilICE/v1/futures/ice-gasoil12 months
Natural GasNYMEX/v1/futures/natural-gas12 months
EUA CarbonICE/v1/futures/eua-carbon12 months
EU CarbonICE/v1/futures/eu-carbon12 months
TTF GasICE Endex/v1/futures/ttf-gas12 months
LNG JKMICE/v1/futures/lng-jkm12 months
UK Carbon / UKAICE/v1/futures/uk-carbonBase, historical, and curve only
Brent / WTI continuousICE / NYMEX/v1/futures/continuous/{brent,wti}Auto-rolled front-month series; base and /historical only

Endpoint Types

Most futures products support 7 endpoint types. UK carbon currently supports the base, historical, and curve endpoints (curve verified live in production 2026-07-22); do not assume OHLC, intraday, spreads, or spread-history are available for UKA until the backend ships them. Note the canonical slug is uk-carbon — not uka-carbon.

EndpointDescriptionUse Case
/Current pricesReal-time contract prices
/historicalDate range dataBacktesting, analysis
/ohlcDaily OHLCCharting, technical analysis
/intraday5-minute intervalsIntraday trading
/spreadsCalendar spreadsSpread trading
/curveFutures curveContango/backwardation analysis
/spread-historyHistorical spreadsSpread trend analysis

Quick Start

# Get current Brent futures prices
curl "https://api.oilpriceapi.com/v1/futures/ice-brent" \
  -H "Authorization: Token YOUR_API_KEY"
{
  "commodity": "BRENT_FUTURES",
  "source": "market_reporting",
  "updated_at": "2025-12-29T14:30:00.000Z",
  "trading_hours": "01:00-23:00 GMT",
  "contracts": [
    {
      "contract_month": "2026-02",
      "last_price": 74.52,
      "currency": "USD",
      "open": 74.15,
      "close": 74.45,
      "high": 74.85,
      "low": 74.0,
      "volume": 125432,
      "change_percent": 0.47,
      "days_to_expiry": 20,
      "contract_status": "front_month",
      "is_front_month": true,
      "is_nearest_contract": true,
      "expiry_date": "2026-01-30",
      "open_interest": 285432
    }
  ],
  "metadata": {
    "total_contracts": 12,
    "data_source": "market_reporting",
    "front_month_contract": "2026-02",
    "nearest_contract_month": "2026-02",
    "front_month_selection": {
      "method": "roll_warning_days",
      "roll_warning_days": 7,
      "nearest_contract": "2026-02",
      "nearest_days_to_expiry": 20,
      "front_month_contract": "2026-02",
      "rolled": false,
      "reason": "nearest still-trading contract 2026-02 is outside the 7-day roll window, so front_month and nearest_contract are the same contract"
    }
  }
}

/v1/futures/nymex-wti and its sub-paths (/historical, /ohlc, /intraday, /spreads, /curve, /spread-history) serve the same WTI family as /v1/futures/ice-wti, with an identical response. The family follows the NYMEX CL contract calendar. See WTI Futures.

Price fields: close is a capture, not a settlement

close is the last price we collected for the trading session, at close_captured_at. It is not the exchange settlement. settlement is the exchange settlement where one was captured, and null otherwise; it is never copied from close or last_price. settlement_date is the trading session a quote belongs to and does not mean a settlement price exists for it.

FieldMeaning
last_priceMost recent price we collected
closeLast price collected for the session, at close_captured_at (UTC, our collection time)
settlementExchange settlement where captured, otherwise null. On the latest curve it appears only for gas oil; for other markets it is on /historical
change_percentCaptured close versus captured open for the same session. open may be the first price we collected, not the session open
change_from_prior_close_percentCaptured close versus this contract's previous captured close, dated by prior_close_date
change_from_prior_settlement_percentSettlement versus the previous session's settlement (/historical daily rows). null when either is missing

For change_from_prior_close_percent, the prior close is the latest earlier weekday close for the same contract within 7 days, so weekends and missed sessions are bridged. Both fields are null when there is no such close. For *_CONTINUOUS codes the prior close can belong to the previous contract month on a roll day.

The latest curve endpoints carry close_captured_at, change_from_prior_close_percent and prior_close_date on each contract that has a captured close, and state these definitions in metadata.field_semantics.

Historical query parameters

These apply to /historical on every contract family (ice-brent, ice-wti/nymex-wti, ice-gasoil, natural-gas, eua-carbon/eu-carbon, uk-carbon, ttf-gas, lng-jkm).

ParameterDescription
from, toWindow as YYYY-MM-DD. Default: the last 30 days. start_date and end_date are accepted as aliases; send one spelling, not both
daysThe last N days ending today (1-730). Cannot be combined with from, to, start_date or end_date
contractsComma-separated contract months, such as 2026-02,2026-03. Default: every contract. contract_month is accepted for one month
intervaldaily (default), weekly or monthly. weekly and monthly replace trading_date with period_start/period_end and add avg_close and trading_days
formatjson (default) or csv. Anything else returns 400 INVALID_PARAMETER

The window can span at most 730 days, and to cannot be in the future.

Any other query parameter returns 400 UNKNOWN_PARAMETERS, with unrecognized_parameters, allowed_parameters and suggestions in the body. For example, period suggests days, and contract (singular) suggests contracts. Earlier, unknown parameters were ignored and the default 30-day window was returned with HTTP 200. The check runs after authentication and the futures entitlement check, and a rejected request does not count against your quota.

Continuous series accept from, to, start_date, end_date, days (1-7300), months (1-240) and interval, and return JSON only.

Daily history rows

With interval=daily, each row in contracts[].daily_data has trading_date, open, high, low, close, volume, open_interest, change_percent, settlement, open_captured_at, close_captured_at, change_from_prior_settlement_percent, settlement_available, change_from_prior_close_percent and prior_close_date. settlement_available is true only on rows that carry an exchange settlement. The response metadata object defines close, close_captured_at, settlement and the change fields.

CSV

format=csv returns text/csv as a download named futures_historical_<from>_<to>.csv. Daily columns:

contract_month,contract_code,date,open,high,low,close,change_percent

With interval=weekly or monthly:

contract_month,contract_code,period_start,period_end,open,high,low,close,avg_close,volume,trading_days

The CSV does not include settlement or the prior-close fields; use JSON for those.

Authentication

All futures endpoints require authentication:

Authorization: Token YOUR_API_KEY

Endpoints

  • ICE Brent Futures
  • WTI Futures (ice-wti, nymex-wti)
  • ICE Gas Oil Futures
  • NYMEX Natural Gas Futures
  • ICE EUA Carbon Futures
  • ICE EU Carbon Futures
  • TTF Gas Futures
  • LNG JKM Futures
  • UK Carbon Futures

Enhanced Contract Data

Each contract includes additional fields for trading intelligence:

FieldTypeDescription
days_to_expiryintegerDays until contract expires
contract_statusstringCurrent contract status
is_front_monthbooleanWhether this is the front month contract
is_nearest_contractbooleanWhether this is the nearest contract still trading (see below)
expiry_datedateCalculated expiry date
open_interestintegerOpen interest (when available)

Contract Status Values

StatusDescription
front_monthPrimary trading contract (>7 days to expiry)
near_expiryContract expiring within 7 days
activeFuture contract with >30 days to expiry
expiredContract has expired

Front month vs. nearest contract

front_month is the contract the market has substantially rolled into. It moves to the next contract 7 days before the current one's last trading day (roll_warning_days), so for a few days each month the contract that is still trading is not the front_month.

If you run your own roll rule, use nearest_contract instead. It is the nearest unexpired contract and stays in place through its own last trading day. Both are returned side by side, and metadata.front_month_selection states which method chose front_month and whether the two currently differ:

{
  "front_month": { "contract_month": "2026-09", "is_front_month": true, "..." : "..." },
  "nearest_contract": { "contract_month": "2026-08", "contract_status": "near_expiry", "is_nearest_contract": true, "days_to_expiry": 6, "..." : "..." },
  "metadata": {
    "front_month_contract": "2026-09",
    "nearest_contract_month": "2026-08",
    "front_month_selection": {
      "method": "roll_warning_days",
      "roll_warning_days": 7,
      "nearest_contract": "2026-08",
      "nearest_days_to_expiry": 6,
      "front_month_contract": "2026-09",
      "rolled": true,
      "reason": "nearest contract 2026-08 is within 7 days of its last trading day (6 days remaining), so front_month has rolled to 2026-09; 2026-08 continues to trade until its expiry_date"
    }
  }
}
FieldMeaning
nearest_contractNearest contract still trading, held through its last trading day. Same shape as front_month.
metadata.front_month_selection.methodThe rule that chose the current front_month: roll_warning_days (proximity, with the 7-day early roll), december_benchmark (EU carbon's liquid December contract), liquidity_benchmark (EU carbon with no December listed: highest volume), or none (the only contract still trading is inside the roll window, so no front_month is designated).
metadata.front_month_selection.rolledtrue while front_month and nearest_contract are different contracts.
metadata.front_month_selection.reasonPlain-language explanation of the current selection.

To apply your own rule, take contracts[], filter on days_to_expiry / expiry_date, and ignore front_month entirely. Nothing about front_month changed when these fields were added.

Roll Indicator

When the front month is near expiry, the API includes a roll indicator:

{
  "roll_indicator": {
    "should_roll": true,
    "days_remaining": 4,
    "next_contract": "2026-04",
    "message": "Consider rolling to April 2026 contract"
  }
}

Trading Hours

ExchangeHours (Local)Hours (GMT)
ICE Brent01:00-23:0001:00-23:00
ICE WTI01:00-23:0001:00-23:00
ICE Gas Oil01:00-23:0001:00-23:00
ICE EUA Carbon07:00-17:00 CET06:00-16:00
NYMEX Nat Gas18:00-17:00 ET23:00-22:00

Data Updates

  • Intraday: Source-dependent refresh during trading hours
  • Settlement: Daily at 19:30 GMT
  • Historical: 30+ days retention

Access and Limits

Futures Data is included with Professional and Scale. An active trial may include futures access, but that access ends when the trial ends unless the account has a futures-entitled plan or add-on. Free includes spot data, not ongoing access to /v1/futures/*. The Free allowance of 50 requests per day applies to endpoints available on Free; it does not grant futures entitlement.

Other paid plans can add Futures Data for $39/month from Dashboard → Billing. A key without Futures Data receives 403; the response includes message, current_plan, required_plan, and access_url so the account owner can choose a supported plan or add-on. A rejected request does not count against the allowance.

Errors

StatusCodeWhen
401UNAUTHORIZEDMissing or invalid API key
403—Key has no Futures Data entitlement (see above)
503DATA_TOO_STALEThe newest quote for the family is more than 96 hours old. The body carries data_age_hours, max_age_hours (96), last_updated, and commodity. Quotes under 96 hours old are served; older-than-usual ones carry a data_age_warning string such as Data is 26.0 hours old.
503LIVE_DATA_STALEGasoil and Henry Hub natural-gas families only (their family-latest and /intraday endpoints): intraday data went stale while the market is open (distinct from the 96-hour bound above, which is checked first and applies at all hours). The error object carries the market-hours context — freshness_status, market_status, expected_live_updates, checked_at, market_timezone, and (when a timestamp exists) latest_data_at and stale_by_minutes — with commodity at the top level. A refresh is normally triggered automatically; retry after a few minutes.
503—No futures data held for the family

The 96-hour ceiling clears the longest weekend and holiday closures observed across the futures families (about 62 hours), so a normal weekend never triggers it.

Last Updated: 11/15/26, 8:08 PM
Next
ICE Brent Futures