---
title: "Multi-commodity market brief"
method: GET
path: "/v1/market-brief"
tags: ["Market Brief"]
---

# Multi-commodity market brief

`GET /v1/market-brief`

## Request

- Base URL: `https://api.oilpriceapi.com`
- URL: `https://api.oilpriceapi.com/v1/market-brief`
- Auth: API key in header `Authorization`

Compact multi-commodity snapshot for agents and MCP clients: latest price, 24h change,
and a 1-month forecast per commodity, plus optional spreads and macro context.
The `codes` parameter is REQUIRED (comma-separated commodity codes).

## Query parameters

- `codes` string, required
- `narrative` boolean

## Response `200`

Market brief

- object
  - `status` string
  - `data` object
    - `as_of` string, date-time
    - `codes` string[]
    - `commodities` object[]
      - `code` string
      - `name` string
      - `price` number, float
      - `currency` string
      - `unit` string
      - `change_24h_pct` number, float, nullable
      - `change_24h_abs` number, float, nullable
      - `as_of` string, date-time
      - `source` string
      - `stale` boolean: True when the latest observation is past twice its series' expected publication gap — the same per-cadence judgement `data_status` reports on `/v1/prices/latest`, so both endpoints answer identically for the same row. A stale leg is excluded from `spreads`.
      - `data_status` 'current' | 'delayed' | 'stale' | 'degraded', nullable: Freshness of the observation against its own publication cadence. `delayed` is past the expected gap, `stale` is past twice it.
      - `forecast_1m` object, nullable
        - `point` number, float
        - `low` number, float
        - `high` number, float
        - `confidence` number, float
    - `spreads` object[]
    - `context` object, nullable: Present only when `narrative=true`.

## Other responses

- `400`: Missing/invalid `codes` parameter (`{"status":"fail","data":{"error":"VALIDATION_ERROR",...}}`).
- `401`: Unauthorized
- `500`: Unexpected server error. Retry transient failures with bounded backoff and retain the request ID when contacting support.

## Changes

- **2026-10-12** `1b0373823190`: 1 info
  - added the optional property `data/commodities/items/data_status` to the response with the `200` status

[Operation history](https://skmtc.dev/oilpriceapi/apis/oil-price-api-v1/changes/v1/market-brief/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)