Access historical price data for oil and commodity markets with customizable time ranges and intervals.
| Method | Endpoint | Description |
|---|
| GET | /v1/prices/past_day | Hourly prices for past 24 hours |
| GET | /v1/prices/past_week | Daily prices for past 7 days |
| GET | /v1/prices/past_month | Daily prices for past 30 days |
| GET | /v1/prices/past_year | Weekly prices for past 365 days |
See Authentication Guide for API key setup.
| Parameter | Type | Required | Description | Default | Example |
|---|
by_code | string | No | Commodity code to retrieve | BRENT_CRUDE_USD | WTI_USD, NATURAL_GAS_USD |
by_type | string | No | Price type to retrieve | spot_price | spot_price, daily_average_price |
interval | string | No | Time interval for data aggregation | raw | raw, 1h, 1d, 1w, 1m |
page | integer | No | Page number for pagination | 1 | 1, 2, 3 |
per_page | integer | No | Number of results per page (max: 100) | 100 | 10, 50, 100 |
format | string | No | Response format | json | json, csv |
| Interval | Description | Aggregation |
|---|
raw | No aggregation (default) | Individual price points |
1h, hourly | Hourly aggregation | OHLC data by hour |
1d, daily | Daily aggregation | OHLC data by day |
1w, weekly | Weekly aggregation | OHLC data by week |
1m, monthly | Monthly aggregation | OHLC data by month |
{
"status": "success",
"data": {
"WTI": {
"name": "West Texas Intermediate",
"currency": "USD",
"unit": "barrel",
"prices": [
{
"timestamp": "2025-07-18T10:00:00Z",
"price": 78.45,
"volume": 125420,
"open": 78.20,
"high": 78.55,
"low": 78.15,
"close": 78.45
}
],
"summary": {
"start": "2025-07-17T11:00:00Z",
"end": "2025-07-18T10:00:00Z",
"high": 79.20,
"low": 77.50,
"average": 78.35,
"change": 0.82,
"change_percent": 1.05
}
}
},
"meta": {
"request_id": "req_hist123",
"response_time_ms": 156,
"data_points": 24,
"interval": "1h"
}
}
| Field | Type | Description |
|---|
timestamp | string | ISO 8601 timestamp |
price | number | Price value |
volume | number | Trading volume |
open | number | Opening price |
high | number | Highest price |
low | number | Lowest price |
close | number | Closing price |
Historical endpoints return paginated results for performance:
| Header | Description | Example |
|---|
X-Total | Total number of records | 2016 |
X-Total-Pages | Total number of pages | 21 |
X-Page | Current page number | 1 |
X-Per-Page | Records per page | 100 |
Link | RFC 5988 pagination links | <...?page=2>; rel="next" |
curl "https://api.oilpriceapi.com/v1/prices/past_day?by_code=WTI_USD" \
-H "Authorization: Token YOUR_API_KEY"
curl "https://api.oilpriceapi.com/v1/prices/past_week?by_code=WTI_USD&page=1&per_page=50" \
-H "Authorization: Token YOUR_API_KEY"
curl "https://api.oilpriceapi.com/v1/prices/past_month?by_code=BRENT_CRUDE_USD&interval=1d" \
-H "Authorization: Token YOUR_API_KEY"
curl "https://api.oilpriceapi.com/v1/prices/past_year?by_code=WTI_USD&format=csv" \
-H "Authorization: Token YOUR_API_KEY"
async function getWeeklyPrices() {
const response = await fetch('https://api.oilpriceapi.com/v1/prices/past_week?by_code=WTI_USD', {
headers: {
'Authorization': 'Token YOUR_API_KEY'
}
});
const data = await response.json();
return data.data.WTI.prices;
}
async function getAllHistoricalData(endpoint = 'past_week') {
let allData = [];
let page = 1;
let totalPages = 1;
while (page <= totalPages) {
const response = await fetch(`https://api.oilpriceapi.com/v1/prices/${endpoint}?page=${page}`, {
headers: { 'Authorization': 'Token YOUR_API_KEY' }
});
totalPages = parseInt(response.headers.get('X-Total-Pages'));
const data = await response.json();
if (data.data?.WTI?.prices) {
allData.push(...data.data.WTI.prices);
}
page++;
}
return allData;
}
| Code | Status | Description |
|---|
INVALID_COMMODITY | 400 | Invalid commodity code provided |
INVALID_INTERVAL | 400 | Invalid interval parameter |
INVALID_API_KEY | 401 | Missing or invalid API key |
RATE_LIMIT_EXCEEDED | 429 | Rate limit exceeded |
| Plan | past_day | past_week | past_month | past_year |
|---|
| Free | 10/hour | 5/hour | 2/hour | 1/hour |
| Hobby | 100/hour | 50/hour | 20/hour | 10/hour |
| Professional | 1000/hour | 500/hour | 200/hour | 100/hour |
| Enterprise | Unlimited | Unlimited | Unlimited | Unlimited |