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

# List Commodities

> List the price series we track, like butter or corn, narrowed by category and commodity, attributes, market and series..

Requires the `search-commodities` scope.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/commodities
openapi: 3.1.0
info:
  title: Orbbit Data API
  version: '1.0'
  description: Commodity prices and packaged-food labels over one read-only REST API.
servers:
  - url: https://data-api.orbbit.co
    description: Production
security:
  - bearer: []
tags:
  - name: Commodities
  - name: Branded Food
paths:
  /v1/commodities:
    get:
      tags:
        - Commodities
      summary: List Commodities
      description: >-
        List the price series we track, like butter or corn, narrowed by
        category and commodity, attributes, market and series..


        Requires the `search-commodities` scope.
      operationId: list_commodities
      parameters:
        - name: category
          required: false
          in: query
          description: >-
            The food group: `dairy`, `poultry`, `meat`, `grains`, `fruits` or
            `vegetables`. Leave it out to list every group.
          schema:
            type: string
        - name: commodity
          required: false
          in: query
          description: >-
            The product being priced, as one exact word, such as `corn`, `beef`,
            `cheese` or `shell_eggs`. Leave it out to list every product.
          schema:
            type: string
        - name: attributes
          required: false
          in: query
          style: deepObject
          explode: true
          schema:
            type: object
            additionalProperties:
              type: string
            example: {}
          description: >-
            Details that set a product apart, such as the cut of meat or the
            size. Send each one in brackets, such as
            `attributes[meat_cut]=breasts&attributes[size_class]=large`. Only
            series matching every detail you send are listed.
        - name: region
          required: false
          in: query
          description: >-
            Where the price applies, such as `us`, `us_southwest` or
            `us_mississippi`.
          schema:
            type: string
        - name: market_level
          required: false
          in: query
          description: >-
            The step in the supply chain where the price is paid: `farm`,
            `wholesale` or `retail`.
          schema:
            type: string
        - name: freight
          required: false
          in: query
          description: >-
            USDA's shipping term: `fob` (at the seller's location), `delivered`
            or `not_stated`.
          schema:
            type: string
        - name: frequency
          required: false
          in: query
          description: >-
            How often USDA publishes the series: `daily`, `weekly`, `biweekly`,
            `monthly` or `annual`.
          schema:
            type: string
        - name: price_type
          required: false
          in: query
          description: >-
            Which number the series is: `low`, `high`, `avg`, `mostly_low`,
            `mostly_high`, `close` or `value`.
          schema:
            type: string
        - name: unit
          required: false
          in: query
          description: >-
            What each value is in, such as `usd_per_lb`, `usd_per_dozen` or
            `usd_per_package`.
          schema:
            type: string
        - name: measure
          required: false
          in: query
          description: USDA's own name for the number, such as `wtd_avg_price`.
          schema:
            type: string
        - name: limit
          required: false
          in: query
          description: >-
            How many series to return per page, from 1 to 500. The default is
            100.
          schema:
            type: integer
        - name: cursor
          required: false
          in: query
          description: >-
            To get the next page, pass the `next_cursor` from the previous
            reply. Leave it out for the first page.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCommoditiesResponseDto'
              example:
                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'
                  - id: data_commodity_metric_01m5jbexd5ed88x32k1yxhj57y
                    metric_name: >-
                      cheese_block_cheddar_40_lb_us_wholesale_weekly_cheese_40_price_usd_per_lb
                    product:
                      category: dairy
                      commodity: cheese
                      attributes:
                        size: 40 lb
                        cheese_form: block
                        cheese_style: cheddar
                    region: us
                    market_level: wholesale
                    freight: not_stated
                    frequency: weekly
                    price_type: value
                    unit: usd_per_lb
                    measure: cheese_40_price
                    source: usda-mpr
                    first_observed_on: '2012-03-03'
                    last_observed_on: '2026-10-10'
                next_cursor: >-
                  cheese_block_cheddar_40_lb_us_wholesale_weekly_cheese_40_price_usd_per_lb
        '400':
          description: >-
            An unknown parameter, a food group that is not one of the six, a
            detail no product has, or a limit that is out of range.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiErrorDto'
              example:
                error:
                  type: invalid_request
                  message: 'limit: Too big: expected number to be <=500'
        '401':
          description: The API key is missing, mistyped, unknown or revoked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiErrorDto'
              example:
                error:
                  type: unauthorized
                  message: 'Missing or malformed Authorization: Bearer header'
        '402':
          description: >-
            The balance, or this key's monthly spend limit, cannot cover this
            call.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiErrorDto'
              example:
                error:
                  type: insufficient_balance
                  message: Insufficient balance
        '403':
          description: This API key is not allowed to call this endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiErrorDto'
              example:
                error:
                  type: forbidden
                  message: This key is not scoped to search-commodities
      security:
        - bearer: []
components:
  schemas:
    ListCommoditiesResponseDto:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: >-
                  Orbbit's ID for the series. Pass it to `GET
                  /v1/commodities/metric-values` as `ids`.
              metric_name:
                type: string
                description: >-
                  The series' readable name, built from its facts. Pass it to
                  `GET /v1/commodities/metric-values` as `metric_names`.
              product:
                type: object
                properties:
                  category:
                    type: string
                    description: >-
                      USDA's food group: `dairy`, `poultry`, `meat`, `grains`,
                      `fruits` or `vegetables`.
                  commodity:
                    type: string
                    description: >-
                      The thing priced, as one word, such as `corn`, `beef` or
                      `shell_eggs`.
                  attributes:
                    type: object
                    propertyNames:
                      type: string
                    additionalProperties:
                      anyOf:
                        - type: string
                        - type: array
                          items:
                            type: string
                    description: >-
                      What sets the product apart, one word to a value, such as
                      `{ "meat_cut": "breasts", "size": "40 lb" }`. A list where
                      several values apply.
                description: The product being priced. One product can have many series.
              region:
                type: string
                description: >-
                  Where the price applies, such as `us`, `us_wisconsin` or
                  `us_chicago`.
              market_level:
                type: string
                description: >-
                  The step in the supply chain where the price is paid: `farm`,
                  `wholesale` or `retail`.
              freight:
                type: string
                description: >-
                  USDA's shipping term: `fob` (at the seller's location),
                  `delivered`, or `not_stated`.
              frequency:
                type: string
                description: >-
                  How often USDA publishes the series: `daily`, `weekly`,
                  `biweekly`, `monthly` or `annual`.
              price_type:
                type: string
                description: >-
                  Which number this is: `low`, `high`, `avg`, `mostly_low`,
                  `mostly_high`, `close`, or `value` for a number published on
                  its own.
              unit:
                type: string
                description: >-
                  What each value is in, such as `usd_per_lb`, `usd_per_cwt` or
                  `usd_each`.
              measure:
                type: string
                description: >-
                  USDA's own name for the number, unchanged, such as
                  `wtd_avg_price` or `price_max`.
              source:
                type: string
                description: >-
                  The USDA report system: `usda-mars` (Market News reports) or
                  `usda-mpr` (Livestock Mandatory Reporting).
              first_observed_on:
                anyOf:
                  - type: string
                  - type: 'null'
                description: The date of the series' oldest value, `YYYY-MM-DD`.
              last_observed_on:
                anyOf:
                  - type: string
                  - type: 'null'
                description: >-
                  The date of the series' newest value, `YYYY-MM-DD`. Orbbit
                  checks USDA for new values every day.
          description: The series on this page.
          x-nestjs_zod-uses-3-point-1-syntax: true
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          description: Pass as `cursor` to get the next page. `null` on the last page.
          x-nestjs_zod-uses-3-point-1-syntax: true
          x-nestjs_zod-empty-type: true
    PublicApiErrorDto:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
            message:
              type: string
          x-nestjs_zod-self-required: true
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: Your API key, which starts with `orbbit_data_`.

````

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