Skip to main content

API workflow guardrail

Understand what a historical price row means before you model it

Historical price endpoints can return daily aggregates or raw observations. The right interpretation depends on the interval, record type, and whether your workflow needs a spot benchmark or a futures contract.

Start with one request Compare futures fields

First decision

Choose the response mode that matches the question you are trying to answer.

Use interval=daily when one UTC-date row per code is enough for the analysis.

Use interval=raw&by_type=spot_price when you need observation-level rows.

Use futures routes when open, high, low, close, settlement, or contract month matters.

Daily historical rows

Best for one-row-per-date reports and simple trend analysis.

curl -H "Authorization: Token YOUR_API_KEY" \
  "https://api.oilpriceapi.com/v1/prices/historical?by_code=BRENT_CRUDE_USD&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD&interval=daily"

One row per UTC date for the requested code and date range.

The price is OilPriceAPI's arithmetic average of available spot_price observations for that UTC date.

The row is not an official exchange settlement, market close, opening price, or volume-weighted average.

Raw observation rows

Best when the aggregation rule belongs in your own model.

curl -H "Authorization: Token YOUR_API_KEY" \
  "https://api.oilpriceapi.com/v1/prices/historical?by_code=URALS_CRUDE_USD&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD&interval=raw&by_type=spot_price"

Each row is one stored observation for the requested code and record type.

A UTC date can contain multiple observations, depending on the source and ingestion cadence.

Use raw rows when you need to inspect source timestamps or apply your own aggregation rule.

Field semantics

Read the metadata before treating the price as a market event

The same field names can appear in different response modes. Check the interval and row metadata before using a value as a settlement, benchmark, or observation in downstream analysis.

Common fields

Treat these as response semantics, not permission language.

price

The returned value for the selected interval. In daily mode it is the daily arithmetic average; in raw mode it is the observation value.

type

The row shape or aggregation method, such as daily_average for daily historical rows.

price_type

The underlying record class used for the row, such as spot_price.

source

For daily rows, aggregated means OilPriceAPI computed the row. For raw rows, source identifies the observation pipeline or source label returned by the API.

created_at

For daily rows, the UTC bucket timestamp. For raw rows, the observation timestamp returned by the API.

Spot and futures

Futures OHLC fields are a separate workflow

If you need contract month, open, high, low, close, settlement, or curve context, use futures-specific documentation and endpoints. Those fields are distinct from spot historical rows and are not a substitute for an unsupported spot product.

Open futures data guide

Pre-modeling checklist

Use this before moving a response into a customer report, dashboard, or spreadsheet.

Confirm the commodity code before comparing two datasets.

Check whether your workflow needs a spot benchmark, a daily average, or a futures contract.

Use raw observations when your report needs a custom averaging rule.

Treat missing dates as a coverage question first; source availability varies by code and date range.

Keep redistribution and display requirements tied to your package and source approval.