OIoilpriceapi
Prices
Premium

Get paginated historical price data

Changed on

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. Raw history defaults to 25 rows and applies a maximum of 100 per page. Raw responses expose X-Page, X-Per-Page, X-Has-Next and credential-free next/previous Link headers, including cache hits. data.metadata.pagination reports the effective page/per_page, has_next, has_previous, truncated and per_page_clamped. Raw responses do not compute a total count. Follow pages until has_next is false; a later page alone still does not represent the entire requested window. Raw history can include stored averages; use by_type=spot_price when collected quote rows are required, and inspect instrument/time metadata.

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

Request

  • Base URL
    https://api.oilpriceapi.com
  • Auth
    API key in header Authorization

Query parameters

by_codestring required
Example:JET_FUEL_USD

One commodity code or a comma-separated list of at most 5. A sixth code returns 422 TOO_MANY_COMMODITIES with max_codes and requested_count. 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": [
      {
        "benchmark": {
          "id": "nymex_wti_front_month",
          "instrument_type": "front_month_futures",
          "quote_type": "indicative_last_price",
          "unit": "barrel",
          "contract_month": "2026-12",
          "roll_method": "explicit_contract_curve",
          "roll_signal": "volume"
        },
        "price": 68.58,
        "formatted": "$68.58",
        "currency": "USD",
        "code": "WTI_USD",
        "requested_code": "ASPHALT_USD",
        "alias_of": "BITUMEN_USD",
        "contract_month": "2026-12",
        "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",
        "ingested_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
          }
        }
      }
    ]
  }
}

Changes

  • dc3f91f8926dRevision changes
    • info

      added the optional property /// to the response with the status

    • info

      added the optional property /// to the response with the status

  • b987321524a8Revision changes
    • breaking

      the response property /// became nullable for the status

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property /// to the response with the status