Commodities

Use this when you need the price history of a raw ingredient, for example to track input costs, check a supplier’s quote against the market, or feed a forecast. The Commodities API is two endpoints used together. First you list price series to find the one you want. Then you ask for that series’ values by date.

Step	Endpoint	Name	Scope	Price
1	`GET /v1/commodities`	List Commodities	`search-commodities`	Free
2	`GET /v1/commodities/metric-values`	Get Commodity Metric Values	`get-commodity-prices`	$0.01

What’s covered

Every price is grouped the way USDA Market News groups it: a category, then a commodity inside it. Pass either one, or both, to List Commodities. ?category=grains&commodity=corn lists every corn price series.

Category	Commodities	Supply-chain steps	How often	Units
`dairy`	`butter`, `butteroil`, `cheese`, `cottage_cheese`, `cream`, `cream_cheese`, `sour_cream`, `yogurt`, `ice_cream`, `milk`, `flavored_milk`, `eggnog`, `condensed_skim_milk`, `nonfat_dry_milk`, `skim_milk_powder`, `whole_milk_powder`, `dry_whole_milk`, `buttermilk_powder`, `dry_whey`, `whey_protein_concentrate`, `lactose`, `casein`, `milk_replacer`	Farm, wholesale, retail	Daily to annual	`usd_per_lb`, `usd_per_cwt`, `usd_per_metric_ton`, `usd_each`, `ratio_to_cme_butter`, `usd_per_lb_over_cme_butter`
`poultry`	`chicken`, `turkey`, `shell_eggs`, `liquid_eggs`, `frozen_eggs`, `dried_eggs`, `egg_whites`, `egg_yolks`	Farm, wholesale, retail	Daily, weekly, monthly	`usd_per_lb`, `usd_each`, `usd_per_dozen`, `usd_per_carton`
`meat`	`beef`, `pork`, `lamb`	Wholesale	Daily, weekly	`usd_per_cwt`
`grains`	`wheat`, `corn`, `barley`, `oats`, `sorghum`, `millet`, `rye`, `triticale`, `soybeans`, `sunflower_seeds`, `canola`, `flaxseed`, `dry_beans`, `dry_peas`, `lentils`	Farm, wholesale	Daily, weekly	`usd_per_bushel`, `usd_per_cwt`, `usd_per_ton`
`fruits`	`apples`, `avocados`, `bananas`, `blackberries`, `blueberries`, `breadfruit`, `cantaloupes`, `cherimoya`, `cherries`, `clementines`, `coconuts`, `dragon_fruit`, `grapefruit`, `grapes`, `honeydews`, `kiwifruit`, `lemons`, `limes`, `mangoes`, `melons`, `nectarines`, `oranges`, `papaya`, `peaches`, `pears`, `pepino`, `persimmons`, `pineapples`, `plantains`, `plums`, `pomegranates`, `quenepas`, `rambutan`, `raspberries`, `strawberries`, `tangelos`, `tangerines`, `watermelons`	Wholesale	Daily	`usd_per_package`
`vegetables`	`anise`, `artichokes`, `asparagus`, `beets`, `bok_choy`, `broccoli`, `brussels_sprouts`, `cabbage`, `calabaza`, `carrots`, `cauliflower`, `celery`, `chayote`, `chinese_cabbage`, `cilantro`, `cucumbers`, `eggplant`, `endive`, `escarole`, `ginger_root`, `green_beans`, `greens`, `leeks`, `lettuce`, `malanga`, `okra`, `onions`, `parsley`, `peas`, `peppers`, `potatoes`, `radishes`, `rhubarb`, `spinach`, `squash`, `sweet_corn`, `sweet_potatoes`, `taro`, `tomatillos`, `tomatoes`, `turmeric`, `yampi`, `yams`, `yuca`	Wholesale	Daily	`usd_per_package`, `usd_per_lb`, `usd_per_cwt`, `usd_per_bunch`

A few groupings follow USDA rather than the grocery aisle: eggs are under poultry, and soybeans, oilseeds and dry beans are under grains, because USDA reports them in its grain bids. Where USDA splits one crop into types, such as bell and jalapeño peppers or grape and plum tomatoes, the crop is the commodity and the type is one of its attributes. Sweet corn is sweet_corn under vegetables; corn under grains is field corn. Fruit and vegetables include every product the USDA has priced within two years of its newest report, each with its full history.

Find a series in four layers

Each price series answers four questions, and List Commodities can narrow on each one:

Layer	Question	Parameters	Example
1. Product	What is priced?	`category`, `commodity`	`category=poultry&commodity=shell_eggs`
2. Attributes	Which kind of it?	`attributes[<word>]`	`attributes[size_class]=large`
3. Market	Where and at what step is it sold?	`region`, `market_level`, `freight`	`region=us_southwest&market_level=retail`
4. Series	How is the number published?	`frequency`, `price_type`, `unit`, `measure`	`frequency=weekly&price_type=avg`

Each result is one series: its id and metric_name, the product it prices (its category, commodity and attributes), then one field for each market and series layer, named exactly like the parameter that filters it. You never have to take a metric_name apart, because every part of it is also its own field.

List commodities

GET /v1/commodities lists price series, narrowed by any of the four layers, one page at a time. It is free.

Parameter	Type	Required	Description
`category`	string	No	Layer 1. One of `dairy`, `poultry`, `meat`, `grains`, `fruits` or `vegetables`. Any other value returns `400`. Leave it out to list every category.
`commodity`	string	No	Layer 1. One commodity word from the table above, such as `corn`, `beef` or `shell_eggs`. A word no product has returns an empty page.
`attributes[<word>]`	string	No	Layer 2. The value one attribute must have, such as `attributes[cheese_form]=block`. Repeat it for each attribute: `attributes[cheese_form]=block&attributes[cheese_style]=cheddar`. A word no product has returns `400`.
`region`	string	No	Layer 3. Where the price is paid, such as `us`, `us_chicago` or `us_southwest`.
`market_level`	string	No	Layer 3. `farm`, `wholesale` or `retail`.
`freight`	string	No	Layer 3. `fob`, `delivered` or `not_stated`.
`frequency`	string	No	Layer 4. `daily`, `weekly`, `biweekly`, `monthly` or `annual`.
`price_type`	string	No	Layer 4. `low`, `high`, `avg`, `mostly_low`, `mostly_high`, `close` or `value`.
`unit`	string	No	Layer 4. Such as `usd_per_lb`, `usd_per_dozen` or `usd_per_package`.
`measure`	string	No	Layer 4. The USDA’s own name for the number, such as `wtd_avg_price`.
`limit`	integer	No	Series per page, 1 to 500. Default 100.
`cursor`	string	No	The `next_cursor` from the previous page.

curl --globoff --request GET \
  --url 'https://data-api.orbbit.co/v1/commodities?category=dairy&commodity=cheese&attributes[cheese_style]=cheddar&region=us_chicago&frequency=daily&limit=1' \
  --header 'authorization: Bearer YOUR_API_KEY'

{
  "data": [
    {
      "id": "data_commodity_metric_01m5jbewxffcs9j3neja9k8s4a",
      "metric_name": "cheese_block_cheddar_40_lb_us_chicago_wholesale_daily_close_price_usd_per_lb",
      "product": {
        "category": "dairy",
        "commodity": "cheese",
        "attributes": { "size": "40 lb", "cheese_form": "block", "cheese_style": "cheddar" }
      },
      "region": "us_chicago",
      "market_level": "wholesale",
      "freight": "not_stated",
      "frequency": "daily",
      "price_type": "close",
      "unit": "usd_per_lb",
      "measure": "close_price",
      "source": "usda-mars",
      "first_observed_on": "2021-02-24",
      "last_observed_on": "2026-10-20"
    }
  ],
  "next_cursor": "cheese_block_cheddar_40_lb_us_chicago_wholesale_daily_close_price_usd_per_lb"
}

Use first_observed_on and last_observed_on to see how far back a series goes and how fresh it is before you ask for its values. When next_cursor is null, you have reached the last page. The --globoff flag stops curl from reading the square brackets in attributes[...] as a pattern.

Get commodity metric values

GET /v1/commodities/metric-values returns dated values for one or more series. It costs $0.01 per call, however many series you ask for.

Parameter	Type	Required	Description
`metric_names`	string	One of the two	One or more `metric_name`s from List Commodities, comma-separated.
`ids`	string	One of the two	One or more series `id`s from List Commodities, comma-separated. You can send both; together they name at most 100 series.
`start_date`	string	No	First date to include, as `YYYY-MM-DD`. Leave it out to get each series’ recent stretch (see below).
`end_date`	string	No	Last date to include, as `YYYY-MM-DD`. Leave it out to run to each series’ newest value.

When you leave out the dates

If you leave out start_date, each series returns a recent stretch. How long depends on how often the series is published:

Series `frequency`	Default range
`daily`, `weekly`, `biweekly`	The last 1 year
`monthly`	The last 5 years
`annual`	The last 10 years

The stretch is counted back from end_date if you pass it. If you don’t, it is counted back from the series’ own newest value, not from today, so a series that stopped updating still returns its last stretch. Each series is counted on its own, so two series in one call can start on different dates. Pass start_date to get an exact range, or an early date such as start_date=1990-01-01 to get a series’ full history.

curl --request GET \
  --url 'https://data-api.orbbit.co/v1/commodities/metric-values?metric_names=cheese_block_cheddar_40_lb_us_chicago_wholesale_daily_close_price_usd_per_lb&start_date=2026-10-16&end_date=2026-10-20' \
  --header 'authorization: Bearer YOUR_API_KEY'

{
  "data": [
    {
      "id": "data_commodity_metric_01m5jbewxffcs9j3neja9k8s4a",
      "metric_name": "cheese_block_cheddar_40_lb_us_chicago_wholesale_daily_close_price_usd_per_lb",
      "product": {
        "category": "dairy",
        "commodity": "cheese",
        "attributes": { "size": "40 lb", "cheese_form": "block", "cheese_style": "cheddar" }
      },
      "region": "us_chicago",
      "market_level": "wholesale",
      "freight": "not_stated",
      "frequency": "daily",
      "price_type": "close",
      "unit": "usd_per_lb",
      "measure": "close_price",
      "source": "usda-mars",
      "first_observed_on": "2021-02-24",
      "last_observed_on": "2026-10-20",
      "start_date": "2026-10-16",
      "end_date": "2026-10-20",
      "values": [
        { "date": "2026-10-16", "value": 1.6825 },
        { "date": "2026-10-19", "value": 1.73 },
        { "date": "2026-10-20", "value": 1.8 }
      ]
    }
  ]
}

Understanding the response

data has one entry per series you asked for, in the order you asked.
Each entry describes the series with the same fields as List Commodities, then adds start_date, end_date and values.
start_date and end_date are the first and last dates used for that series. They are null only when you passed no dates and the series has no values at all.
unit tells you how to read value. For example, usd_per_lb is dollars per pound.
values is in date order, with one value per date. Days with no value, such as weekends for a daily series, are left out.
value is the number the USDA published, in the series’ unit. A price the USDA publishes in cents is given in dollars.
A date range with no values returns the series with an empty values array, not an error.

To compare series side by side, pass several names separated by commas, for example a Chicago and a national cheddar price over the same weeks. If any name is wrong, the whole request fails with 400, and the message names the ones it doesn’t know. So a typo never silently drops a series.

400 Unknown metric

{
  "error": {
    "type": "invalid_request",
    "message": "Unknown metrics: cheddar_close"
  }
}

Series fields

Returned by both endpoints, inside data[].

Field	Type	Description
`id`	string	The series’ ID. Pass it to Get Commodity Metric Values as `ids`.
`metric_name`	string	The series’ readable name, the same in every environment. Pass it as `metric_names`.
`product.category`	string	The USDA category: `dairy`, `poultry`, `meat`, `grains`, `fruits` or `vegetables`.
`product.commodity`	string	The commodity priced, such as `cheese` or `corn`.
`product.attributes`	object	What sets the product apart, one word to a value, such as `{ "meat_cut": "breasts" }`. A value is a list when several apply.
`region`	string	Where the price is paid, such as `us`, `us_chicago`, `us_northeast` or `western_europe`.
`market_level`	string	The step in the supply chain: `farm`, `wholesale` or `retail`.
`freight`	string	Who pays shipping: `fob` (buyer collects from the seller), `delivered`, or `not_stated`.
`frequency`	string	How often a new value appears: `daily`, `weekly`, `biweekly`, `monthly` or `annual`. It sets the default date range.
`price_type`	string	The kind of number: `low`, `high`, `avg`, `mostly_low`, `mostly_high`, `close`, or `value` for a number published on its own.
`unit`	string	How to read each value, such as `usd_per_lb`, `usd_per_dozen`, `usd_per_cwt` (dollars per hundred pounds), `usd_per_bushel` or `usd_per_package`.
`measure`	string	The USDA’s own name for the number, unchanged, such as `wtd_avg_price` or `close_price`.
`source`	string	The USDA report family: `usda-mars` (Market News) or `usda-mpr` (Mandatory Price Reporting).
`first_observed_on`	string or null	Date of the earliest value, `YYYY-MM-DD`.
`last_observed_on`	string or null	Date of the newest value, `YYYY-MM-DD`.

Get Commodity Metric Values adds:

Field	Type	Description
`start_date`	string or null	The first date used for this series, `YYYY-MM-DD`: your `start_date`, or the start of the default range.
`end_date`	string or null	The last date used for this series, `YYYY-MM-DD`: your `end_date`, or the series’ newest value.
`values`	array	Values in date order.
`values[].date`	string	The value’s date, `YYYY-MM-DD`.
`values[].value`	number	The value, in the series’ unit.

Validation rules

Rule	Behavior
`metric_names` or `ids` is required	Leaving both out returns `400`.
At most 100 series	More, counting `metric_names` and `ids` together, returns `400`.
Every series must exist	One unknown name fails the whole request with `400 Unknown metrics: <names>`.
At most 50,000 values	A call that would return more returns `400` and asks you to narrow `start_date` and `end_date`, or ask for fewer series.
`category` must be one of six	Any other value returns `400 Unknown category <value>; category is one of dairy, poultry, meat, grains, fruits, vegetables`.
Every attribute word must exist	An `attributes[<word>]` no product has returns `400 Unknown attribute words: <words>`.
No unknown parameters	A parameter either endpoint doesn’t take returns `400`.
`limit`	Must be 1 to 500; anything else returns `400`.
Dates	`start_date` and `end_date` must be real calendar days written `YYYY-MM-DD`; `2026-02-30` is refused.
Date order	`start_date` later than `end_date` returns `400`.
Both dates included	A value dated exactly `start_date` or `end_date` is returned.

Summary

Detail	`GET /v1/commodities`	`GET /v1/commodities/metric-values`
Name	List Commodities	Get Commodity Metric Values
Scope	`search-commodities`	`get-commodity-prices`
Price	Free	$0.01 per call
Parameters	`category`, `commodity`, `attributes[<word>]`, `region`, `market_level`, `freight`, `frequency`, `price_type`, `unit`, `measure`, `limit`, `cursor`	`metric_names`, `ids`, `start_date`, `end_date`
Response	`{ data: [series], next_cursor }`	`{ data: [series with start_date, end_date, values] }`
Paged	Yes	No
Errors	`400`, `401`, `403`	`400`, `401`, `402`, `403`

What to do next

Try it live: List Commodities and Get Commodity Metric Values.
Copy a working feature: see the Food Commodity Prices cookbook examples.
Handle errors: see Errors.
Let your AI assistant do it: see Use With Claude.

Getting Started

For Agents

Market Data

Industry Data

What’s covered

Find a series in four layers

List commodities

Get commodity metric values

When you leave out the dates

Understanding the response

Series fields

Validation rules

Summary

What to do next

​What’s covered

​Find a series in four layers

​List commodities

​Get commodity metric values

​When you leave out the dates

​Understanding the response

​Series fields

​Validation rules

​Summary

​What to do next

What’s covered

Find a series in four layers

List commodities

Get commodity metric values

When you leave out the dates

Understanding the response

Series fields

Validation rules

Summary

What to do next