Frequently Asked Questions

Common questions about OilPriceAPI, organized by topic.

Data Freshness

How often does data update?

Update frequency varies by commodity type:

• Crude oil & futures: Every 5 minutes during trading hours
• Precious metals: Every 1 minute (24/5)
• Natural gas: Every 5-15 minutes
• Diesel & gasoline: Weekly (Mondays)
• Coal spot prices: Weekly (Tuesdays)

See our Data Freshness Guide for complete details by commodity.

Does the timestamp change even if the price hasn't changed?

Yes. The created_at timestamp updates on every refresh cycle (typically every 5 minutes for futures data) regardless of whether the price changed.

This is intentional - it confirms the API is actively polling data sources. The timestamp reflects "last checked" not "last changed."

To detect actual price changes, compare consecutive price values or use webhooks (which only trigger on price changes).

Why is my data timestamp several hours old?

Common reasons:

1. Markets closed: Futures don't update outside trading hours or on weekends
2. Data source delay: Some sources have inherent reporting delays
3. Weekly/monthly data: Some commodities only update weekly (diesel) or monthly (OPEC production)
4. Holiday: Exchange holidays affect data availability

Check the Data Freshness Guide for each commodity's expected update schedule.

How do I know if data is stale?

Compare created_at against the expected update frequency:

During weekends and market holidays, older timestamps are expected.

Historical Data

How far back does historical data go?

It varies by commodity. Examples:

Use the /v1/commodities endpoint to check data availability for specific commodities.

When is yesterday's closing price available?

Settlement prices are typically available within 30 minutes after market close. Some settlement prices may take 1-2 hours depending on the exchange.

Can I get tick-by-tick or minute-level data?

Our standard API provides 5-minute snapshots during trading hours. For higher-frequency data needs, contact sales@oilpriceapi.com to discuss enterprise options.

Timestamps & Timezones

What timezone are timestamps in?

All timestamps are UTC in ISO 8601 format:

2026-02-02T14:35:00Z

The Z suffix indicates UTC (Zulu time). Convert to your local timezone in your application.

How do I convert UTC to my local timezone?

from datetime import datetime
import pytz

utc_time = datetime.fromisoformat("2026-02-02T14:35:00Z".replace('Z', '+00:00'))
local_tz = pytz.timezone('America/New_York')
local_time = utc_time.astimezone(local_tz)
# Result: 2026-02-02 09:35:00-05:00 (EST)

API & Technical

What happens if a data source fails?

We use multiple sources per commodity with automatic failover. If the primary source fails, backup sources activate within 5 minutes. You'll still receive data, and we monitor source health 24/7.

Why am I getting cached responses?

Responses are cached for performance. Check the X-Cache header:

• HIT = served from cache
• MISS = fresh data fetch

Cache duration is typically 30-60 seconds for frequently-accessed data.

How do I get real-time price updates?

Two options:

1. Webhooks: Configure webhooks to receive push notifications when prices change. See Webhooks Documentation.
2. WebSocket: Connect to our WebSocket feed for streaming updates (Professional plan and above). See WebSocket Documentation.

What's the difference between price and value_units?

• price: Human-readable price (e.g., 76.42)
• value_units: Internal storage format (price × multiplier for precision)

Always use the price field for display and calculations.

Pricing & Plans

Do API requests count against my limit even if they return cached data?

Yes, all API requests count toward your monthly limit, regardless of whether the response was cached.

What happens when I reach my API limit?

You'll receive a 429 Too Many Requests response. Check the X-Monthly-Remaining header to monitor usage before hitting the limit.

Can I upgrade mid-month?

Yes. When you upgrade, your new limit takes effect immediately. The additional requests are prorated.

Data Coverage

Which commodities do you cover?

We cover 50+ commodities across:

• Crude Oil: WTI, Brent, Dubai, Urals, etc.
• Refined Products: Diesel, gasoline, jet fuel, heating oil
• Natural Gas: Henry Hub, UK NBP, Dutch TTF, JKM LNG
• Coal: Newcastle, CAPP, PRB, Illinois Basin
• Precious Metals: Gold, silver, platinum, palladium
• Carbon Credits: EU ETS, California
• Forex: Major currency pairs

See the Commodity Catalog for the complete list.

Do you cover marine bunker fuel prices?

Yes. We provide prices for major bunkering ports including Singapore, Rotterdam, Fujairah, and more. See Marine Fuel for details.

Do you have drilling and production data?

Yes. Our Energy Intelligence endpoints provide:

• Rig counts (Baker Hughes)
• Well permits (state agencies)
• DUC wells (EIA)
• Oil inventories (EIA WPSR)
• OPEC production (MOMR)

See Energy Intelligence for available endpoints.

Support

How do I report a data issue?

Email support@oilpriceapi.com with:

• Commodity code
• Timestamp of the issue
• Expected vs. observed value
• Screenshot if applicable

We respond within 1 business day.

Where can I get help with integration?

• Documentation: Start with our Quick Start Guide
• Examples: See Code Examples in multiple languages
• Email: support@oilpriceapi.com for specific questions
• Status: Check @oilpricehourly for service status

Still have questions?

Contact us at support@oilpriceapi.com - we typically respond within 1 business day.