Historical Prices

Status: ✅ Available | 📈 Time-Series | 🔄 Multiple Intervals

Access historical price data for oil and commodity markets with customizable time ranges and intervals.

Endpoints

/v1/prices/historical is the canonical endpoint for full archives. It requires by_code, defaults to interval=daily, and supports up to 500 rows per page. The fixed-window endpoints default to raw collected points and cap raw pages at 100 rows. Publication frequency varies by commodity; a raw point is not necessarily a real-time market tick.

Authentication

See Authentication Guide for API key setup.

Custom Historical Parameters

These parameters apply to GET /v1/prices/historical:

Historical depth is entitlement-aware even when you omit all date bounds. Use GET /v1/commodities/{code} to see your_access, source cadence, coverage, and direct links to the canonical OpenAPI operation and this guide.

Interval Parameter

The interval parameter controls time-based aggregation for historical data. When specified, prices are averaged within each time bucket, reducing data transfer and improving performance for charting and dashboard applications.

When an interval is supplied, each returned point has type set to the bucket average (e.g. daily_average), source set to aggregated, and an added price_type field.

Benefits:

• Reduced Data Transfer: Fewer data points for the same time range (e.g., 30 days ≈ 30 daily averages vs. several thousand raw ~5–10 minute points)
• Lower Rate Limit Usage: Aggregated responses use the same rate limit as raw data
• Optimized for Charting: Pre-aggregated data is ideal for time-series visualizations
• Consistent Formatting: All prices rounded to 2 decimal places for currency consistency

Response

Success (200) - Raw Data

data.prices is an array of raw spot points, roughly 5–10 minutes apart:

{
  "status": "success",
  "data": {
    "prices": [
      {
        "price": 67.84,
        "formatted": "$67.84",
        "currency": "USD",
        "code": "WTI_USD",
        "created_at": "2026-07-02T13:54:43.160Z",
        "updated_at": "2026-07-02T13:54:43.160Z",
        "type": "spot_price",
        "unit": "barrel",
        "source": "market_reporting"
      },
      {
        "price": 67.79,
        "formatted": "$67.79",
        "currency": "USD",
        "code": "WTI_USD",
        "created_at": "2026-07-02T13:46:11.402Z",
        "updated_at": "2026-07-02T13:46:11.402Z",
        "type": "spot_price",
        "unit": "barrel",
        "source": "market_reporting"
      }
    ]
  }
}

Success (200) - With Interval Aggregation

When using the interval parameter, points are bucket averages — type becomes the average type, source is aggregated, and a price_type field is added:

{
  "status": "success",
  "data": {
    "prices": [
      {
        "price": 67.94,
        "formatted": "$67.94",
        "currency": "USD",
        "code": "WTI_USD",
        "created_at": "2026-07-02T00:00:00.000Z",
        "type": "daily_average",
        "price_type": "daily_average",
        "source": "aggregated"
      },
      {
        "price": 68.41,
        "formatted": "$68.41",
        "currency": "USD",
        "code": "WTI_USD",
        "created_at": "2026-07-01T00:00:00.000Z",
        "type": "daily_average",
        "price_type": "daily_average",
        "source": "aggregated"
      }
    ]
  }
}

Response Fields

Pagination

Historical endpoints return paginated results for performance. /v1/prices/historical defaults to and caps pages at 500 rows; fixed-window raw endpoints cap pages at 100 rows. Page through larger ranges with page=N. The total-count header is X-Total (not X-Total-Count).

OPEC Reference Basket

Use OPEC_BASKET_USD for the official OPEC Reference Basket price. The series is sourced from OPEC's official daily XML archive, uses source: "opec.org", and carries source_date for the OPEC reference date.

curl "https://api.oilpriceapi.com/v1/prices/historical?by_code=OPEC_BASKET_USD&start_date=2003-01-01&interval=daily" \
  -H "Authorization: Token YOUR_API_KEY"

OPEC Basket historical data is available on paid plans through the normal historical endpoints. Plan historical-depth limits still apply.

Examples

Basic Usage

# Get past 24 hours of raw WTI data (all individual price points)
curl "https://api.oilpriceapi.com/v1/prices/past_day?by_code=WTI_USD" \
  -H "Authorization: Token YOUR_API_KEY"

# Get past week with pagination
curl "https://api.oilpriceapi.com/v1/prices/past_week?by_code=WTI_USD&page=1&per_page=50" \
  -H "Authorization: Token YOUR_API_KEY"

# Get CSV format
curl "https://api.oilpriceapi.com/v1/prices/past_year?by_code=WTI_USD&format=csv" \
  -H "Authorization: Token YOUR_API_KEY"

Using Interval Aggregation

# Get past month as daily averages (~30 points instead of thousands of raw points)
curl "https://api.oilpriceapi.com/v1/prices/past_month?by_code=BRENT_CRUDE_USD&interval=1d" \
  -H "Authorization: Token YOUR_API_KEY"

# Get past year as weekly averages for long-term trending
curl "https://api.oilpriceapi.com/v1/prices/past_year?by_code=WTI_USD&interval=1w" \
  -H "Authorization: Token YOUR_API_KEY"

# Get past week as hourly averages for intraday analysis
curl "https://api.oilpriceapi.com/v1/prices/past_week?by_code=NATURAL_GAS_USD&interval=1h" \
  -H "Authorization: Token YOUR_API_KEY"

# Get past year as monthly averages for annual trends
curl "https://api.oilpriceapi.com/v1/prices/past_year?by_code=BRENT_CRUDE_USD&interval=1m" \
  -H "Authorization: Token YOUR_API_KEY"

JavaScript/TypeScript

// Get past week with daily aggregation
async function getWeeklyPrices() {
  const response = await fetch(
    "https://api.oilpriceapi.com/v1/prices/past_week?by_code=WTI_USD&interval=1d",
    {
      headers: {
        Authorization: "Token YOUR_API_KEY",
      },
    },
  );

  const data = await response.json();
  return data.data.prices; // Returns ~7 daily averages
}

// Get optimized data for charting (monthly averages for past year)
async function getChartData(commodityCode = "WTI_USD") {
  const response = await fetch(
    `https://api.oilpriceapi.com/v1/prices/past_year?by_code=${commodityCode}&interval=1m`,
    {
      headers: { Authorization: "Token YOUR_API_KEY" },
    },
  );

  const data = await response.json();

  // Format for chart libraries (e.g., Chart.js, Recharts)
  return data.data.prices.map((price) => ({
    date: new Date(price.created_at),
    value: price.price,
    formatted: price.formatted,
  }));
}

// Handle pagination for raw (non-aggregated) data
async function getAllRawData(
  endpoint = "past_week",
  commodityCode = "WTI_USD",
) {
  let allData = [];
  let page = 1;
  let totalPages = 1;

  while (page <= totalPages) {
    const response = await fetch(
      `https://api.oilpriceapi.com/v1/prices/${endpoint}?by_code=${commodityCode}&page=${page}`,
      {
        headers: { Authorization: "Token YOUR_API_KEY" },
      },
    );

    totalPages = parseInt(response.headers.get("X-Total-Pages"));
    const data = await response.json();

    if (data.data?.prices) {
      allData.push(...data.data.prices);
    }

    page++;
  }

  return allData;
}

Python

import requests
from datetime import datetime

# Get past month as daily averages
def get_monthly_averages(commodity_code='WTI_USD'):
    url = 'https://api.oilpriceapi.com/v1/prices/past_month'
    headers = {'Authorization': 'Token YOUR_API_KEY'}
    params = {
        'by_code': commodity_code,
        'interval': '1d'  # Daily aggregation
    }

    response = requests.get(url, headers=headers, params=params)
    data = response.json()

    return data['data']['prices']

# Get past year with weekly aggregation for trending
def get_yearly_trend(commodity_code='BRENT_CRUDE_USD'):
    url = 'https://api.oilpriceapi.com/v1/prices/past_year'
    headers = {'Authorization': 'Token YOUR_API_KEY'}
    params = {
        'by_code': commodity_code,
        'interval': '1w'  # Weekly aggregation
    }

    response = requests.get(url, headers=headers, params=params)
    data = response.json()

    # Format for data analysis
    prices = []
    for price in data['data']['prices']:
        prices.append({
            'date': datetime.fromisoformat(price['created_at'].replace('Z', '+00:00')),
            'price': price['price'],
            'type': price['type']
        })

    return prices

Errors

Rate Limits

All plans share the same request rate limit of 60 requests per rolling 60-second window per API key. Plans differ by monthly request quota, not by a per-endpoint rate ladder. Bursts within the window are fine. See Rate Limiting for details.

Related Endpoints

• Latest Prices - Current market prices
• Commodities List - Available commodity codes
• WebSocket Streaming - Real-time updates