Physical price history API

Read weekly fuel or monthly commodity price history with periods, published units and revisions.

Endpoint and request

REST endpoint

GET /v1/commodities/physical/series/{series_id}/observations

Contract request

curl --request GET \
  --url "https://api.narwhalapi.com/v1/commodities/physical/series/worldbank-cmo-copper/observations?start=2026-07-01&end=2026-10-01&limit=100" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

MCP uses commodities_get_physical_observations. REST and MCP share the same schema, account quota, rights check, and problem shape.

Parameters

Name	Required	Type	Meaning
`series_id`	Yes	path · string	Use a stable ID returned by discovery, such as fuel-eia-usa-regular-gasoline or worldbank-cmo-copper.
`start`	No	query · YYYY-MM-DD	Inclusive start date. Supply start and end together, or omit both.
`end`	No	query · YYYY-MM-DD	Exclusive end date, later than start. Observations overlapping the date window are returned.
`limit`	No	query · integer, 1–500	Maximum items per page. Defaults to 100.
`cursor`	No	query · string	Use next_cursor from the previous page with the same filters and limit. Null means there are no more pages.

Source: U.S. Energy Information Administration. Source: The World Bank: World Bank Commodity Price Data (The Pink Sheet), CC BY 4.0

Response

Contract example

{
  "series_id": "worldbank-cmo-copper",
  "currency": "USD",
  "unit": "metric_ton",
  "unit_quantity": "1",
  "attribution": "The World Bank: World Bank Commodity Price Data (The Pink Sheet)",
  "observations": [
    {
      "period_start": "2026-07-01",
      "period_end": "2026-07-31",
      "price": "13543",
      "published_on": null,
      "revision": 1
    },
    {
      "period_start": "2026-08-01",
      "period_end": "2026-08-31",
      "price": "14326",
      "published_on": null,
      "revision": 1
    },
    {
      "period_start": "2026-09-01",
      "period_end": "2026-09-30",
      "price": "14474",
      "published_on": null,
      "revision": 1
    }
  ],
  "next_cursor": null
}

Field	Type	Required	Meaning
`series_id`	string	Yes	Stable ID returned by series discovery.
`currency`	string	Yes	Quote currency. Both US fuel and monthly benchmark series use USD.
`unit / unit_quantity`	strings	Yes	Published unit and the quantity priced. Fuel uses us_gallon. Monthly benchmarks use metric_ton, kilogram, barrel, cubic_meter, troy_ounce, mmbtu, dry_metric_ton_unit or sheet. The quantity is 1 except for plywood, which uses USD per 100 sheets. Values are not converted.
`attribution`	string or null	Yes	Keep the response attribution with the data. Source: U.S. Energy Information Administration. Source: The World Bank: World Bank Commodity Price Data (The Pink Sheet), CC BY 4.0
`observations`	array	Yes	Oldest-first observations. Each contains period_start, period_end, a decimal-string price, nullable published_on and revision.
`observations[].period_start / observations[].period_end`	dates	Yes	Inclusive observation dates. Fuel uses the Monday survey date for both. A monthly observation spans the whole month, such as 2026-09-01 to 2026-09-30.
`observations[].price`	decimal string	Yes	Published price in the series currency per unit_quantity units. Read it with the series price type and basis.
`observations[].published_on`	date or null	Yes	Publication date when available. Null is preserved when it is unknown.
`observations[].revision`	integer	Yes	Starts at 1 and increases when a later publication changes the value for that period.
`next_cursor`	string or null	Yes	Opaque continuation token. Null marks the final page.

Errors and quota

400 invalid_query, a code, area, date range, limit, or selector is invalid.
400 invalid_cursor, the cursor is invalid or does not match the request filters.
400 cursor_expired, the publication changed. Restart pagination without a cursor.
401 invalid_api_key, the Bearer key is missing or rejected.
404 physical_series_not_found, no complete approved data matches the request.
429 rate_limit_exceeded or quota_exhausted, the shared allowance is exhausted.
503 physical_reference_unavailable, a complete publication is unavailable.

Rejected requests and server errors do not consume monthly quota.

Coverage

20 weekly US retail fuel series: regular gasoline and No. 2 on-highway diesel, each for the US average and nine regions. Prices use USD per US gallon. History starts on 20 July 2026 and grows each week after the Monday survey. Source: U.S. Energy Information Administration. Monthly coverage includes 70 World Bank series across softs, oils and oilseeds, metals, grains, energy, fertilizers, forestry, and livestock and dairy. History reaches back to 1960, with later starts for some series. The latest available month is September 2026, but individual series can lag or have ended. Barley and sorghum end in August 2020; Mexican shrimp ends in October 2023. Check coverage_end for each series. All prices use USD and units as published. Source: The World Bank: World Bank Commodity Price Data (The Pink Sheet), CC BY 4.0

Available with a Narwhal API key.