--- title: "Get latest price for a commodity" method: GET path: "/v1/prices/latest" tags: ["Prices"] --- # Get latest price for a commodity `GET /v1/prices/latest` ## Request - Base URL: `https://api.oilpriceapi.com` - URL: `https://api.oilpriceapi.com/v1/prices/latest` - Auth: API key in header `Authorization` Retrieve the most recent price for a specific commodity or a comma-separated basket. The container-freight composite, Shanghai–Genoa and Shanghai–Los Angeles codes and their legacy `DREWRY_WCI_*` names resolve to the same stored series in a basket. Each group returns one quote, even when both names are requested. The returned `code` remains the actual stored code; `requested_code` and `alias_of` disclose a different requested name when the basket did not also request the served code. Missing groups are accounted for under the names requested, and stale data is not made fresh. ## Query parameters - `partial` boolean - `by_code` 'ALUMINUM_USD' | 'AMMONIA_USD' | 'ASPHALT_USD' | 'AZERI_LIGHT_USD' | 'BAKKEN_DUC_WELLS' | 'BAKKEN_FRAC_SPREADS' | 'BIODIESEL_USD' | 'BONNY_LIGHT_USD' | 'BRENT_CRUDE_USD' | 'CANADA_RIG_COUNT' | 'CAPP_COAL_USD' | 'CME_COAL_USD' | 'COAL_USD' | 'COKING_COAL_USD' | 'COPPER_USD' | 'CUSHING_STORAGE' | 'DIESEL_USD' | 'DUBAI_CRUDE_USD' | 'DUTCH_TTF_EUR' | 'DUTCH_TTF_NATURAL_GAS_USD' | 'EAGLEFORD_DUC_WELLS' | 'EAGLEFORD_FRAC_SPREADS' | 'ESPO_CRUDE_USD' | 'ETHANOL_USD' | 'ETHYLENE_USD' | 'EUR_USD' | 'USD_NOK' | 'EUR_NOK' | 'EU_CARBON_EUR' | 'UK_CARBON_GBP' | 'GASOLINE_RBOB_USD' | 'GASOLINE_USD' | 'GBP_USD' | 'GOLD_USD' | 'SILVER_USD' | 'GOLD_AM_USD' | 'GOLD_AM_GBP' | 'GOLD_AM_EUR' | 'GOLD_PM_USD' | 'GOLD_PM_GBP' | 'GOLD_PM_EUR' | 'SILVER_FIX_USD' | 'SILVER_FIX_GBP' | 'SILVER_FIX_EUR' | 'HEATING_OIL_USD' | 'HFO_380_USD' | 'ILLINOIS_COAL_USD' | 'INTERNATIONAL_RIG_COUNT' | 'IRON_ORE_USD' | 'JET_A1_NWE_USD' | 'JET_FUEL_USD' | 'JKM_LNG_USD' | 'JOHAN_SVERDRUP_USD' | 'LEAD_USD' | 'LOUISIANA_LIGHT_USD' | 'MARS_USD' | 'MGO_05S_USD' | 'METHANOL_USD' | 'MURBAN_CRUDE_USD' | 'NAPHTHA_USD' | 'NICKEL_USD' | 'NATURAL_GAS_GBP' | 'NATURAL_GAS_STORAGE' | 'NATURAL_GAS_USD' | 'NEWCASTLE_COAL_USD' | 'NORTH_DAKOTA_WELL_PERMITS' | 'NYMEX_APPALACHIAN_USD' | 'NYMEX_WESTERN_RAIL_USD' | 'OKLAHOMA_WELL_PERMITS' | 'PALLADIUM_USD' | 'PERMIAN_DUC_WELLS' | 'PERMIAN_FRAC_SPREADS' | 'POLYETHYLENE_USD' | 'POLYPROPYLENE_USD' | 'PLATINUM_USD' | 'PRB_COAL_USD' | 'TAPIS_CRUDE_USD' | 'TIN_USD' | 'TEXAS_WELL_PERMITS' | 'ULSD_DIESEL_USD' | 'URALS_CRUDE_USD' | 'URANIUM_USD' | 'UREA_USD' | 'US_RIG_COUNT' | 'VLSFO_USD' | 'WCS_CRUDE_USD' | 'WTI_USD' | 'ZINC_USD' - `by_type` 'spot_price' | 'daily_average_price' ## Response `200` Latest price data. A single `by_code` returns a flat `data` object (LatestPriceResponse); multiple comma-separated codes return `data.prices[]` (LatestPricesResponse). - union - LatestPriceResponse - `status` string - `data` object: A single commodity price point. Returned as the flat `data` object for a single-commodity request, or as an element of `data.prices` for multi-commodity / historical requests. - `benchmark` PriceBenchmark: Semantic identity and provenance for WTI or Brent benchmark prices. Explicit contract identity is included only when known. WTI retains its early-roll policy; the selected delivery month may differ from the earliest unexpired contract. Compare contract_month and observed_at when comparing quotes. - `id` string: Stable benchmark identifier - `name` string: Benchmark instrument name - `instrument_type` string - `quote_type` string - `unit` string - `contract_month` string: Selected delivery month when explicitly known; omitted for an unidentified publisher-managed contract - `roll_method` string: How the selected observation identifies its contract - `roll_signal` string: Stored signal used in contract selection, when available. A signal does not by itself mean a roll occurred. - `observed_at` string, date-time, nullable: Source market observation time; null when unavailable, never substituted with collection time - `observation_time_basis` 'upstream_market' | 'unavailable' - `collected_at` string, date-time: Time the selected price row was collected - `source_tier` string: Selection tier of the observation - `price` number, float - `formatted` string - `currency` string: ISO currency code for priced series (`USD`, `EUR`, ...). Index-type codes return `INDEX` instead: the value is an index level, not a money amount, and `formatted` carries no currency symbol (`"4340.00"`). Index-type codes are `BALTIC_DRY_INDEX`, `BALTIC_CAPESIZE_INDEX`, `BALTIC_PANAMAX_INDEX`, `BALTIC_SUPRAMAX_INDEX` and `SCFI_INDEX`, all with `unit: index`. This measure and formatting also apply to daily, weekly and monthly aggregates from the historical and past-window endpoints. The Drewry World Container Index composite (`CONTAINER_FREIGHT_COMPOSITE_USD`) and its lanes are priced in dollars per 40ft container and return `USD` with `unit: usd_per_40ft`. - `code` string - `requested_code` string: Legacy alias requested on latest-price reads when a different code is served; omitted when the batch also requests that served code. - `alias_of` string: The served series code corresponding to requested_code on latest-price reads. - `contract_month` string, nullable: For WTI_USD and BRENT_CRUDE_USD benchmark quotes, the selected backing row's delivery month (YYYY-MM), matching benchmark.contract_month when known. Null when the publisher-managed quote does not identify a month. This identifies the contract served; it does not necessarily mean the nearest unexpired contract, because a benchmark may roll before expiry. - `created_at` string, date-time - `updated_at` string, date-time - `type` string - `unit` string: Pricing unit (`barrel`, `gallon`, `mmbtu`, `usd_per_tonne`, ...). `index` for the index-type codes listed under `currency`; `usd_per_40ft` for the Drewry World Container Index composite and lane codes. - `source` string: Customer-safe source label. Non-government market sources are returned as `market_reporting`. - `observed_at` string, date-time, nullable: Validated source observation timestamp when known; null when no genuine source timestamp is available. - `source_date` string, date: Source observation date when available. - `as_of` string, date-time: Timestamp when the value was last a genuine source observation. - `collected_at` string, date-time: Timestamp when OilPriceAPI collected or produced this row. - `ingested_at` string, date-time, nullable: Collection timestamp for an individual raw observation; null for aggregated averages, which have no single ingestion instant. - `stale` boolean: Whether `as_of` exceeds this series' expected publication cadence. - `age_days` integer: Whole days between `as_of` and response generation. - `synthetic` boolean: True only for carried-forward heartbeat rows rather than genuine source observations. - `price_type` string: Underlying price type for aggregated historical rows. - `data_status` 'current' | 'delayed' | 'stale' | 'degraded' | 'provisional': Freshness classification of the price, derived from the source session (`observed_at`) against the series' expected publication cadence (`freshness.expected_max_age_seconds`), not from the time OilPriceAPI collected the row. - `current`: `freshness.age_seconds` is within `expected_max_age_seconds`. - `delayed`: past the expected cadence but inside the stale limit; the last print is still served. - `stale`: past the stale limit; `stale` is `true`. - `degraded`: the series' data-gap circuit breaker is open (`freshness.circuit_breaker_open: true`) while the value is not yet stale. - `provisional`: the served print is held from a single source and has not yet been confirmed by a second independent source. Reserved for the Baltic session-ledger codes (`BALTIC_DRY_INDEX`, `BALTIC_CAPESIZE_INDEX`, `BALTIC_PANAMAX_INDEX`, `BALTIC_SUPRAMAX_INDEX`); not served as of 2026-10-10. Index-type codes print once per London business day (Baltic indices) or once a week (`SCFI_INDEX` on Friday, `CONTAINER_FREIGHT_COMPOSITE_USD` on Thursday), so `delayed` between prints is the normal state for them, not an error. To tell "old because weekly" from "old because broken", compare `freshness.age_seconds` with `freshness.expected_max_age_seconds`. Live example (2026-10-10, `/v1/prices/latest?by_code=BALTIC_CAPESIZE_INDEX`): `price: 4340.0`, `formatted: "4340.00"`, `currency: "INDEX"`, `unit: "index"`, `observed_at: "2026-10-09T12:00:00.000Z"`, `data_status: "current"`, `freshness: {status: "current", age_seconds: 81475, expected_max_age_seconds: 324000}`. - `freshness` object - `status` string - `age_seconds` integer - `expected_max_age_seconds` integer - `changes` object: Price change over rolling windows. Keys are 24h/7d/30d/90d. - `24h` PriceChange - `amount` number, float - `percent` number, float - `previous_price` number, float - `7d` PriceChange - `amount` number, float - `percent` number, float - `previous_price` number, float - `30d` PriceChange - `amount` number, float - `percent` number, float - `previous_price` number, float - `90d` PriceChange - `amount` number, float - `percent` number, float - `previous_price` number, float - `metadata` object - `source` string - `source_description` string - LatestPricesResponse - `status` string - `data` object - `prices` PriceData[] - `benchmark` PriceBenchmark: Semantic identity and provenance for WTI or Brent benchmark prices. Explicit contract identity is included only when known. WTI retains its early-roll policy; the selected delivery month may differ from the earliest unexpired contract. Compare contract_month and observed_at when comparing quotes. - `id` string: Stable benchmark identifier - `name` string: Benchmark instrument name - `instrument_type` string - `quote_type` string - `unit` string - `contract_month` string: Selected delivery month when explicitly known; omitted for an unidentified publisher-managed contract - `roll_method` string: How the selected observation identifies its contract - `roll_signal` string: Stored signal used in contract selection, when available. A signal does not by itself mean a roll occurred. - `observed_at` string, date-time, nullable: Source market observation time; null when unavailable, never substituted with collection time - `observation_time_basis` 'upstream_market' | 'unavailable' - `collected_at` string, date-time: Time the selected price row was collected - `source_tier` string: Selection tier of the observation - `price` number, float - `formatted` string - `currency` string: ISO currency code for priced series (`USD`, `EUR`, ...). Index-type codes return `INDEX` instead: the value is an index level, not a money amount, and `formatted` carries no currency symbol (`"4340.00"`). Index-type codes are `BALTIC_DRY_INDEX`, `BALTIC_CAPESIZE_INDEX`, `BALTIC_PANAMAX_INDEX`, `BALTIC_SUPRAMAX_INDEX` and `SCFI_INDEX`, all with `unit: index`. This measure and formatting also apply to daily, weekly and monthly aggregates from the historical and past-window endpoints. The Drewry World Container Index composite (`CONTAINER_FREIGHT_COMPOSITE_USD`) and its lanes are priced in dollars per 40ft container and return `USD` with `unit: usd_per_40ft`. - `code` string - `requested_code` string: Legacy alias requested on latest-price reads when a different code is served; omitted when the batch also requests that served code. - `alias_of` string: The served series code corresponding to requested_code on latest-price reads. - `contract_month` string, nullable: For WTI_USD and BRENT_CRUDE_USD benchmark quotes, the selected backing row's delivery month (YYYY-MM), matching benchmark.contract_month when known. Null when the publisher-managed quote does not identify a month. This identifies the contract served; it does not necessarily mean the nearest unexpired contract, because a benchmark may roll before expiry. - `created_at` string, date-time - `updated_at` string, date-time - `type` string - `unit` string: Pricing unit (`barrel`, `gallon`, `mmbtu`, `usd_per_tonne`, ...). `index` for the index-type codes listed under `currency`; `usd_per_40ft` for the Drewry World Container Index composite and lane codes. - `source` string: Customer-safe source label. Non-government market sources are returned as `market_reporting`. - `observed_at` string, date-time, nullable: Validated source observation timestamp when known; null when no genuine source timestamp is available. - `source_date` string, date: Source observation date when available. - `as_of` string, date-time: Timestamp when the value was last a genuine source observation. - `collected_at` string, date-time: Timestamp when OilPriceAPI collected or produced this row. - `ingested_at` string, date-time, nullable: Collection timestamp for an individual raw observation; null for aggregated averages, which have no single ingestion instant. - `stale` boolean: Whether `as_of` exceeds this series' expected publication cadence. - `age_days` integer: Whole days between `as_of` and response generation. - `synthetic` boolean: True only for carried-forward heartbeat rows rather than genuine source observations. - `price_type` string: Underlying price type for aggregated historical rows. - `data_status` 'current' | 'delayed' | 'stale' | 'degraded' | 'provisional': Freshness classification of the price, derived from the source session (`observed_at`) against the series' expected publication cadence (`freshness.expected_max_age_seconds`), not from the time OilPriceAPI collected the row. - `current`: `freshness.age_seconds` is within `expected_max_age_seconds`. - `delayed`: past the expected cadence but inside the stale limit; the last print is still served. - `stale`: past the stale limit; `stale` is `true`. - `degraded`: the series' data-gap circuit breaker is open (`freshness.circuit_breaker_open: true`) while the value is not yet stale. - `provisional`: the served print is held from a single source and has not yet been confirmed by a second independent source. Reserved for the Baltic session-ledger codes (`BALTIC_DRY_INDEX`, `BALTIC_CAPESIZE_INDEX`, `BALTIC_PANAMAX_INDEX`, `BALTIC_SUPRAMAX_INDEX`); not served as of 2026-10-10. Index-type codes print once per London business day (Baltic indices) or once a week (`SCFI_INDEX` on Friday, `CONTAINER_FREIGHT_COMPOSITE_USD` on Thursday), so `delayed` between prints is the normal state for them, not an error. To tell "old because weekly" from "old because broken", compare `freshness.age_seconds` with `freshness.expected_max_age_seconds`. Live example (2026-10-10, `/v1/prices/latest?by_code=BALTIC_CAPESIZE_INDEX`): `price: 4340.0`, `formatted: "4340.00"`, `currency: "INDEX"`, `unit: "index"`, `observed_at: "2026-10-09T12:00:00.000Z"`, `data_status: "current"`, `freshness: {status: "current", age_seconds: 81475, expected_max_age_seconds: 324000}`. - `freshness` object - `status` string - `age_seconds` integer - `expected_max_age_seconds` integer - `changes` object: Price change over rolling windows. Keys are 24h/7d/30d/90d. - `24h` PriceChange - `amount` number, float - `percent` number, float - `previous_price` number, float - `7d` PriceChange - `amount` number, float - `percent` number, float - `previous_price` number, float - `30d` PriceChange - `amount` number, float - `percent` number, float - `previous_price` number, float - `90d` PriceChange - `amount` number, float - `percent` number, float - `previous_price` number, float - `metadata` object - `request_id` string - `timestamp` string, date-time - `version` string ## Other responses - `400`: Invalid commodity code. Body is `{"status":"fail","data":{"error":"invalid_code",...,"invalid_codes":[...]}}`. - `401`: Unauthorized — missing or invalid API key. Body is `{"error":{"code":"UNAUTHORIZED","message":...,"request_id":...}}` (no top-level `status`). - `429`: Rate limit exceeded - `500`: Unexpected server error. Retry transient failures with bounded backoff and retain the request ID when contacting support. ## Changes - **2026-10-20** `dc3f91f8926d`: 4 info - added the optional property `oneOf[#/components/schemas/LatestPriceResponse]/data/allOf[#/components/schemas/PriceData]/alias_of` to the response with the `200` status - added the optional property `oneOf[#/components/schemas/LatestPriceResponse]/data/allOf[#/components/schemas/PriceData]/requested_code` to the response with the `200` status - added the optional property `oneOf[#/components/schemas/LatestPricesResponse]/data/prices/items/alias_of` to the response with the `200` status - added the optional property `oneOf[#/components/schemas/LatestPricesResponse]/data/prices/items/requested_code` to the response with the `200` status - **2026-10-20** `b987321524a8`: 2 breaking, 6 info - the response property `oneOf[#/components/schemas/LatestPriceResponse]/data/allOf[#/components/schemas/PriceData]/observed_at` became nullable for the status `200` - the response property `oneOf[#/components/schemas/LatestPricesResponse]/data/prices/items/observed_at` became nullable for the status `200` - added the optional property `oneOf[#/components/schemas/LatestPriceResponse]/data/allOf[#/components/schemas/PriceData]/benchmark` to the response with the `200` status - added the optional property `oneOf[#/components/schemas/LatestPriceResponse]/data/allOf[#/components/schemas/PriceData]/contract_month` to the response with the `200` status - …4 more - …earlier changes not shown [Operation history](https://skmtc.dev/oilpriceapi/apis/oil-price-api-v1/changes/v1/prices/latest/get.md) --- [API](https://skmtc.dev/oilpriceapi/apis/oil-price-api-v1.md) - [All operations](https://skmtc.dev/oilpriceapi/apis/oil-price-api-v1/llms.txt) - [OpenAPI document](https://skmtc.dev/oilpriceapi/apis/oil-price-api-v1/revisions/7f8b4d763210?raw)