---
title: "Get the callable commodity catalog"
method: GET
path: "/v1/commodities"
tags: ["Commodities"]
---

# Get the callable commodity catalog

`GET /v1/commodities`

Retrieve metadata for callable commodity codes. Every item declares
`status` and `has_data`. Pass `include_unavailable=true` to inspect
discontinued, source-limited, and not-yet-served catalog entries.

## Query parameters

- `include_unavailable` boolean
- `include_discontinued` boolean

## Response `200`

List of all commodities

- CommoditiesResponse
  - `status` 'success', required
  - `data` object, required
    - `commodities` Commodity[], required
      - `code` string, required — Unique commodity identifier
      - `name` string, required — Human-readable commodity name
      - `currency` string, required — Base currency for pricing
      - `category` string, required — Commodity category
      - `description` string — Detailed description
      - `unit` string, required — Unit of measurement
      - `unit_description` string — Detailed unit description
      - `multiplier` integer — Deprecated — internal storage configuration detail retained for backward compatibility only. Do not build on it.
      - `validation` object — Deprecated — internal validation configuration retained for backward compatibility only. Do not build on it.
        - `min` number — Minimum valid price
        - `max` number — Maximum valid price
      - `price_change_threshold` number — Deprecated — internal alerting configuration retained for backward compatibility only. Do not build on it.
      - `data_source` string, nullable — Customer-safe source label; internal venue and scraper names are masked
      - `update_frequency` string, nullable — Expected source-specific refresh cadence
      - `status` 'available' | 'unavailable', required
      - `has_data` boolean, required
      - `unavailable_reason` 'never_had_data' | 'not_served' | 'withheld' | 'discontinued', nullable
      - `unavailable_detail` string, nullable
      - `sources` object[] — Compact per-source cadence summary (#5155). The detail endpoint /v1/commodities/{code} returns the full publication/collection blocks per source.
        - `label` string — Customer-safe source label; masked sources render 'market_reporting'
        - `role` string
        - `publication` object
          - `cadence` string
        - `collection` object
          - `frequency` string
    - `metadata` object, required
      - `availability` object
        - `returned` integer
        - `unavailable_excluded` integer
        - `note` string, nullable

## Other responses

- `401` — Unauthorized - Invalid API key
- `500` — Unexpected server error. Retry transient failures with bounded backoff and retain the request ID when contacting support.

---

[API](https://skmtc.net/oilpriceapi/apis/oil-price-api-v1.md) · [All operations](https://skmtc.net/oilpriceapi/apis/oil-price-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/oilpriceapi/oil-price-api-v1/revisions/5a5ce424cacc/schema)