v2

latestOpenAPI 3.0.4Commercial License2026-08-0718678294.5 KB

Prices

Premium

Get paginated historical price data

Retrieve the authenticated account's available history for one or more commodity codes. by_code is required. The account's historical-depth entitlement is enforced even when no dates are supplied.

The default interval is daily, and the default page size for aggregated history is 500. Responses are paginated; follow X-Page, X-Per-Page, X-Total, and X-Total-Pages rather than assuming one response contains the entire archive. Use interval=raw only when individual collected rows are required.

Use GET /v1/commodities/{code} to discover links, source publication cadence, and the requesting account's history entitlement.

Example:

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

get/v1/prices/historical

Query parameters

by_codestring required

Example:JET_FUEL_USD

One commodity code or a comma-separated list. Discover current codes with GET /v1/commodities.

by_typestring

Example:spot_price

Optional stored price type. When omitted, all price types are eligible.

by_sourcestring

Example:energy_institute

Optional internal source token filter. Prefer omitting this unless reproducing a source-specific workflow.

start_datestring date

Example:2025-01-01

Inclusive UTC start date. Aliases start, start_at, and startDate are accepted.

end_datestring date

Example:2025-12-31

Inclusive UTC end date. Aliases end, end_at, and endDate are accepted.

paststring

Example:1y

Relative window such as 30d, 6m, or 1y. Ignored when explicit dates are supplied.

interval'raw' | '1h' | 'hourly' | 'h' | '1d' | 'daily' | 'd' | 'day' | '1w' | 'weekly' | 'w' | 'week' | '1m' | 'monthly' | 'm' | 'month'

Example:daily

Aggregation interval. Common names and their short aliases are accepted.

pageinteger

Example:1

Page number for pagination

per_pageinteger

Example:500

Items per page. Values above 500 are clamped to 500.

Response

Paginated historical price data available to the authenticated account.

status'success' required

Example response

{
  "status": "success",
  "data": {
    "prices": [
      {
        "price": 68.58,
        "formatted": "$68.58",
        "currency": "USD",
        "code": "WTI_USD",
        "created_at": "2026-07-03T13:43:01.099Z",
        "updated_at": "2026-07-03T13:43:01.099Z",
        "type": "spot_price",
        "unit": "barrel",
        "source": "market_reporting",
        "observed_at": "2026-07-13T12:00:00.000Z",
        "source_date": "2026-07-13",
        "as_of": "2026-07-13T12:00:00.000Z",
        "collected_at": "2026-07-15T21:00:00.000Z",
        "age_days": 2,
        "price_type": "spot_price",
        "data_status": "current",
        "freshness": {
          "status": "current",
          "age_seconds": 275,
          "expected_max_age_seconds": 1800
        },
        "changes": {
          "24h": {
            "amount": 0.72,
            "percent": 1.06,
            "previous_price": 67.86
          },
          "7d": {
            "amount": 0.72,
            "percent": 1.06,
            "previous_price": 67.86
          },
          "30d": {
            "amount": 0.72,
            "percent": 1.06,
            "previous_price": 67.86
          },
          "90d": {
            "amount": 0.72,
            "percent": 1.06,
            "previous_price": 67.86
          }
        }
      }
    ]
  }
}