Oil price API: benchmark history
Benchmark historyOne benchmark day by day, or averaged by week, month or year.
PlansEvery plan
Cost1 call per request
ReturnsUp to 5,000 points
UpdatedDaily
What it is for
One benchmark day by day, or averaged by week, month or year, oldest first.
Brent reaches back to 1987. interval=month gives long charts in few points; convert with currency, or restate in today's money with real.
Good for
- Long run price charts
- Monthly averages for reports
- Crude next to pump prices
price_historyParameters 1 in the path, 6 in the query
| Name | Where and type | Required | What it does | Example |
|---|---|---|---|---|
benchmark | path string | required | Goes in the address itself. | brent |
interval | query one of | default day | day, week, month or year. One of day, week, month, year. | month |
from | query date | optional | First date, YYYY-MM-DD. | 2024-01-01 |
to | query date | optional | Last date, YYYY-MM-DD. | 2024-12-31 |
currency | query ISO 4217 | optional | Convert every price to this currency on its own day, such as usd. | usd |
real | query string | optional | Restate every price in the money of one month with the country's consumer price index: latest, or a month as YYYY-MM such as 2020-01. | latest |
limit | query integer | default 100 | Most recent points when no from is given. Up to 5,000. | 3 |
Try it runs against the live API with your key
No key yet? Get a free one; it is saved in this browser for every page.
The answer 200, application/json
| Field | Type | What it holds | Example |
|---|---|---|---|
benchmark | string | Benchmark code, such as brent | "brent" |
unit | string | litre, gallon or barrel | "barrel" |
currency | string | Three letter currency code | "USD" |
values | array | The points, oldest first | {"period":"2026-08","average":91.076,... |
Example answer real, from what we hold now; long lists cut to three
GET /v1/benchmarks/brent?interval=month&limit=3{ "data": { "benchmark": "brent", "name": "Brent crude, spot", "interval": "month", "unit": "barrel", "currency": "USD", "values": [ { "period": "2026-08", "average": 91.076, "high": 96.92, "low": 86.47, "days": 20 }, { "period": "2026-09", "average": 114.1591, "high": 130.8, "low": 96.02, "days": 22 }, { "period": "2026-10", "average": 124.83, "high": 135.51, "low": 114.82, "days": 19 } ] }, "meta": { "count": 3 } }
Errors every error has the same shape
| HTTP | Code | When | What to do |
|---|---|---|---|
| 401 | unauthorized | No key, or not a valid one | Send your key in the X-API-Key header; your account page shows it. |
| 400 | bad_request | A value is wrong or a required one is missing | The message names the parameter and the form it takes. |
| 422 | unknown_parameter | A parameter this endpoint does not take | Take it out; the parameters this endpoint takes are listed above. |
| 404 | not_found | No record by that benchmark | Check the code; the list endpoint gives every one that exists. |
| 429 | rate_limited | Too many calls this minute | Wait the seconds in the Retry-After header, then call again. |
| 429 | quota_exceeded | Today's calls are used up | Wait for the day to reset at midnight UTC, or move to a larger plan. |
Dates and times are UTC. A point's date is the day its price took effect, or the first day of its week or month for weekly and monthly series. Conversions use each day's own rate, so a converted series moves with both the price and the exchange rate.