Oil price API: list series
List seriesEvery series we hold: retail, set, wholesale, crude, supply and more, searchable.
PlansEvery plan
Cost1 call per request
ReturnsPaged, 50 a page
UpdatedHourly
What it is for
Every series we hold, searchable: pump and set prices, wholesale, crude and products, supply, taxes, consumer price indexes and more, each with its code, unit, currency, frequency and date range.
Filter by family, country or product, or search the names with q. Every code it gives works with Series values.
Good for
- Finding the right code for a chart
- What a country has beyond pump prices
- Checking date ranges before a backfill
Parameters 4 in the query
| Name | Where and type | Required | What it does | Example |
|---|---|---|---|---|
family | query string | optional | retail, crude, refined, jet, marine, lpg, structure, tax, fundamentals, cpi, edible, lubricant. | crude |
country | query country | optional | Two letter country code, such as fr, gb or ke. | fr |
product | query string | optional | Product code, such as diesel. | diesel |
q | query string | optional | Words in the series name. | brent |
page, per_page, cursor | query paging | default 1, 50 | See Pagination. | per_page=100 |
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 |
|---|---|---|---|
series | string | Series code, or the series we hold | "crude.average.monthly" |
name | string | Our name for it | "Crude oil, average of Brent, Dubai a... |
family | string | retail, crude, refined and the rest | "crude" |
product | string | Product code | "crude_average" |
country | string | Two letter country code | null |
unit | string | litre, gallon or barrel | "barrel" |
currency | string | Three letter currency code | "USD" |
interval | string | day, week, month or year | "month" |
first_date | string | First point on record | "1960-01-01" |
last_date | string | Latest point | "2026-09-01" |
points | integer | How many points we hold | 801 |
Example answer real, from what we hold now; long lists cut to three
GET /v1/series?family=crude&per_page=2{ "data": [ { "series": "crude.average.monthly", "name": "Crude oil, average of Brent, Dubai and WTI, monthly", "family": "crude", "product": "crude_average", "country": null, "region": null, "market": "Monthly average", "unit": "barrel", "currency": "USD", "interval": "month", "first_date": "1960-01-01", "last_date": "2026-09-01", "points": 801 }, { "series": "crude.brent.europe", "name": "Brent crude oil, spot", "family": "crude", "product": "crude_brent", "country": null, "region": null, "market": "Europe", "unit": "barrel", "currency": "USD", "interval": "day", "first_date": "1987-05-20", "last_date": "2026-10-27", "points": 9117 } ], "meta": { "count": 2, "next_cursor": "bzI", "page": 1, "per_page": 2, "total": 7, "total_pages": 4, "next_page": 2, "prev_page": null } }
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. |
| 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.