---
title: "Get paginated historical price data"
method: GET
path: "/v1/prices/historical"
tags: ["Prices", "Premium"]
---

# Get paginated historical price data

`GET /v1/prices/historical`

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:
```bash
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"
```

## Query parameters

- `by_code` string, required
- `by_type` string
- `by_source` string
- `start_date` string, date
- `end_date` string, date
- `past` string
- `interval` 'raw' | '1h' | 'hourly' | 'h' | '1d' | 'daily' | 'd' | 'day' | '1w' | 'weekly' | 'w' | 'week' | '1m' | 'monthly' | 'm' | 'month'
- `page` integer
- `per_page` integer

## Response `200`

Paginated historical price data available to the authenticated account.

- HistoricalPricesResponse
  - `status` 'success', required
  - `data` object, required
    - `prices` PriceData[], required
      - `price` number, float
      - `formatted` string
      - `currency` string
      - `code` string
      - `created_at` string, date-time
      - `updated_at` string, date-time
      - `type` string
      - `unit` string
      - `source` string — Customer-safe source label. Non-government market sources are returned as `market_reporting`.
      - `observed_at` string, date-time — Source observation timestamp when the upstream series supplies one.
      - `source_date` string, date — Source observation date when available.
      - `as_of` string, date-time — Timestamp when the value was last a genuine source observation.
      - `collected_at` string, date-time — Timestamp when OilPriceAPI collected or produced this row.
      - `stale` boolean — Whether `as_of` exceeds this series' expected publication cadence.
      - `age_days` integer — Whole days between `as_of` and response generation.
      - `synthetic` boolean — True only for carried-forward heartbeat rows rather than genuine source observations.
      - `price_type` string — Underlying price type for aggregated historical rows.
      - `data_status` string — Freshness classification of the price.
      - `freshness` object
        - `status` string
        - `age_seconds` integer
        - `expected_max_age_seconds` integer
      - `changes` object — Price change over rolling windows. Keys are 24h/7d/30d/90d.
        - `24h` PriceChange
          - `amount` number, float
          - `percent` number, float
          - `previous_price` number, float
        - `7d` PriceChange
          - `amount` number, float
          - `percent` number, float
          - `previous_price` number, float
        - `30d` PriceChange
          - `amount` number, float
          - `percent` number, float
          - `previous_price` number, float
        - `90d` PriceChange
          - `amount` number, float
          - `percent` number, float
          - `previous_price` number, float
    - `metadata` object — Present for bounded or relative windows; describes the applied interval, entitlement-aware window, pagination, and availability.
    - `missing` object[] — Requested commodity codes with no matching data in the applied window.

## Other responses

- `400` — Missing or invalid code, date, interval, or relative window.
- `401` — Unauthorized - Invalid API key
- `402` — Payment required - Paid subscription needed for historical data
- `429` — Rolling rate limit exceeded. Retry with bounded backoff.
- `500` — Unexpected server error. Retry transient failures with bounded backoff and retain the request ID when contacting support.

---

[API](https://skmtc.net/oilpriceapi/apis/oil-price-api-v1.md) · [All operations](https://skmtc.net/oilpriceapi/apis/oil-price-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/oilpriceapi/oil-price-api-v1/revisions/5a5ce424cacc/schema)