> ## Documentation Index
> Fetch the complete documentation index at: https://data-docs.orbbit.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Commodities

> USDA market prices for food commodities, by region and date.

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. |

```bash Request theme={null}
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'
```

```json Response theme={null}
{
  "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.

```bash Request theme={null}
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'
```

```json Response theme={null}
{
  "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.

```json 400 Unknown metric theme={null}
{
  "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](https://data-docs.orbbit.co/api-reference/commodities/list-commodities.md) and [Get Commodity Metric Values](https://data-docs.orbbit.co/api-reference/commodities/get-commodity-metric-values.md).
* Copy a working feature: see the [Food Commodity Prices cookbook examples](https://github.com/orbbit-tech/orbbit-data-cookbook/tree/main/examples/food-commodity-prices).
* Handle errors: see [Errors](https://data-docs.orbbit.co/errors.md).
* Let your AI assistant do it: see [Use With Claude](https://data-docs.orbbit.co/for-agents/use-with-claude.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.