What exactly does one commodity number measure?

A single stock trade print is unambiguous: a share changed hands at that price on that exchange at that moment. A commodity number is ambiguous twice over. You do not automatically know which price it is, and you do not automatically know which period it covers. Both ambiguities have bitten people badly, and both are visible in the data if you look.

Which price

There is no single price of oil — Commodities Foundations spends a whole lesson on why. There is a spot assessment, a front-month futures price, a second-month price, prices at different delivery points, and continuous series stitched together from successive contracts.

The endpoint tells you which one you have, in meta.name. For WTI that string is "Crude Oil Prices: West Texas Intermediate (WTI) - Cushing, Oklahoma". Read it as three separate facts: a grade (WTI, a specific light sweet crude), a location (the Cushing, Oklahoma pipeline hub), and by implication an assessment methodology. It is not "the price of oil". It is the price of one grade at one hub.

That matters because a series built by rolling futures contracts contains steps that are not price moves. On roll day the series switches from the expiring contract to the next one and the level jumps by the spread between them. If the curve is upward-sloping, the new contract is more expensive and the series steps up for no market reason at all. The Futures Curve course covers the mechanics and the cumulative cost; the data point here is narrower and sharper: a return computed across a roll date measures the roll, not the market.

Before you difference a commodity series, find out whether it is a spot assessment or a rolled contract series, and if it is rolled, on what schedule.

Which price, on the futures side

The COMM namespace answers the rolled question differently. CL.COMM is the continuous front contract, and the dated contracts sit beside it as ordinary /eod symbols with the expiry in the code: CLZ26-NYM.COMM is crude, December (Z) 2026, NYMEX. Each has its own OHLCV, so the curve on a given day is one call per maturity, and the roll a continuous series hides is a subtraction you can do yourself.

Two cautions come with it. A .COMM row states no unit. HG.COMM closed near 6.7 on 25 September 2026, dollars per pound, while COPPER on /commodities/historical reads over 13,000, dollars per metric ton; CL.COMM is dollars per barrel and RB.COMM dollars per gallon, both in a field called close. The unit is the exchange's contract specification, and you supply it. And a .COMM symbol is only a price. /fundamentals/GC.COMM answers 422, and the continuous gold series starts on 29 August 2000, so nothing on this path reaches the gold markets of the 1980s.

Which period

Now the second ambiguity, and this one is measurable to the cent.

Fetched on 2026-07-28, /commodities/historical/WTI returned:

• at /commodities/historical/WTI?interval=monthly — 486 observations, from 1986-01-01 to 2026-06-01
• at /commodities/historical/WTI?interval=annual — 40 observations, from 1986-01-01 to 2025-01-01

Check the consistency: 40 complete years times 12 months is 480, plus the six months of 2026 elapsed so far, is 486. Exactly the monthly count. And there is no 2026 annual row because the year is not finished. The two series agree perfectly about what exists.

They do not agree about what a year is.

The annual row dated 2008-01-01 carries 44.6. Here are the twelve monthly rows for 2008: 91.67, 101.78, 101.54, 113.70, 127.35, 139.96, 124.17, 115.55, 100.70, 68.10, 55.21, 44.60. They sum to 1,184.33, so the mean is 1,184.33 ÷ 12 = 98.69.

The annual figure is not the average. It is December's observation — 44.60, the last monthly row of the year — filed under a date label of 1 January.

The pattern holds elsewhere: annual 2007 reads 95.95, which is December 2007's monthly value; annual 2020 reads 48.35, which is December 2020's.

What that does to your numbers

Two consequences, and they compound.

A yearly chart built from this interval shows year-end snapshots, not yearly averages. For 2008 — a year that peaked near 140 in June and ended near 45 — the difference between the two readings is 44.60 against 98.69. The annual figure is less than half the average of the year it labels. Any narrative built on it will describe a different 2008 from the one that happened.

The date label is the start of the period and the value is the end of it. Join an annual commodity series to anything else on date and you have paired a January key with a December number — an eleven-month misalignment that no schema validator will catch, because the types are fine.

This is a description of what the endpoint returned on 2026-07-28, not a claim about what it should do. Re-run it before you rely on it, and record the date you checked.

Try it now

1. Here is BRENT at both cadences: the 2008 row of /commodities/historical/BRENT?interval=annual, then the twelve 2008 rows of ?interval=monthly. Compare the annual value against both the December monthly value and the mean of the twelve. Whichever it matches is the answer for a second series, and it is now documented in your own notes.

2. Here are Brent's two cadences again, now with their counts and both ends. Check whether the monthly count equals twelve times the annual count plus the elapsed months of the current year. It does not; use the four dates to find where the extra monthly rows sit and why they have no annual row, before you conclude that one of the two series has gaps. 3. Read `meta.name` aloud for the series you use most. Underline the grade and the location. Then ask whether the question you are answering is really about that grade at that location.

4. Here are two dated crude contracts on the same day, December 2026 and December 2030, then copper futures beside the COPPER series from the previous lesson, then crude and gasoline in one batched call. Say whether the crude curve sloped up or down that day and by how much per year of maturity. Then convert copper to one unit (one metric ton is 2,204.62 pounds) and say which of the four close values could be subtracted from each other as they stand.

5. Here is the first row the continuous gold future has. Write down the earliest year a gold study on this data can start, and where you would have to go for anything earlier.