Get Market Brief

Status: ✅ Available | ⚡ Real-time | 🤖 Built for AI agents

Returns a multi-commodity market snapshot in a single call: latest spot prices, 24-hour changes, 1-month forecasts (Brent, WTI, Natural Gas), and notable spreads. Optionally adds a plain-English narrative summary plus market context (active supply disruptions, key economic indicators).

This is the structured "morning brief" primitive used by the OilPriceAPI MCP server (opa_get_market_brief). It composes existing price data — it adds no new data sources and makes no LLM call — and counts as 1 request against your quota (same model as /prices/batch).

GET/v1/market-brief

An underscore alias, /v1/market_brief, is also accepted.

Authentication

See Authentication Guide for API key setup.

Authorization: Token YOUR_API_KEY
# Bearer is also accepted:
Authorization: Bearer YOUR_API_KEY

Parameters

Parameter	Type	Required	Description
`codes`	string	Yes	Comma-separated commodity codes (e.g. `BRENT_CRUDE_USD,WTI_USD`). Shorthand aliases are resolved (`WTI` → `WTI_USD`).
`narrative`	boolean	No	When `true`, adds a plain-English `summary` plus a `context` block (disruptions, economic indicators). Default: `false`.

Codes per brief (per plan)

The number of commodity codes allowed in a single brief scales with your plan:

Plan	Codes per brief
Free	3
Developer	8
Starter	15
Professional	30
Scale	50

The narrative is available on all tiers (including Free) — it is the deliberate hook for AI-agent use. Exceeding your code cap returns a BRIEF_CODE_LIMIT error (see below) with an upgrade URL.

Response

Success (200)

{
  "status": "success",
  "data": {
    "as_of": "2026-06-21T14:30:00Z",
    "codes": ["BRENT_CRUDE_USD", "WTI_USD"],
    "commodities": [
      {
        "code": "BRENT_CRUDE_USD",
        "name": "Brent Crude",
        "price": 78.42,
        "currency": "USD",
        "unit": "barrel",
        "change_24h_pct": 1.23,
        "change_24h_abs": 0.95,
        "as_of": "2026-06-21T14:25:00Z",
        "source": "oilprice.business_insider",
        "stale": false,
        "forecast_1m": {
          "point": 80.1,
          "low": 74.5,
          "high": 85.8,
          "confidence": 0.68
        }
      },
      {
        "code": "WTI_USD",
        "name": "WTI Crude",
        "price": 74.1,
        "currency": "USD",
        "unit": "barrel",
        "change_24h_pct": 1.05,
        "change_24h_abs": 0.77,
        "as_of": "2026-06-21T14:25:00Z",
        "source": "oilprice.business_insider",
        "stale": false,
        "forecast_1m": {
          "point": 75.9,
          "low": 70.2,
          "high": 81.4,
          "confidence": 0.65
        }
      }
    ],
    "spreads": [
      {
        "pair": "BRENT_CRUDE_USD/WTI_USD",
        "label": "Brent-WTI",
        "value": 4.32,
        "currency": "USD"
      }
    ]
  }
}

When narrative=true, the data object also includes:

{
  "summary": "Crude benchmarks firmed overnight, with Brent up 1.2% ...",
  "context": {
    "disruptions": [
      {
        "title": "Red Sea shipping diversions",
        "severity": "elevated",
        "region": "Middle East"
      }
    ],
    "indicators": [{ "name": "US Dollar Index", "value": 104.2 }]
  }
}

Response Fields

Field	Type	Description
`as_of`	string	ISO 8601 timestamp the brief was generated (UTC)
`codes`	array	Resolved canonical codes included in the brief
`commodities[]`	array	One object per commodity (see below)
`commodities[].code`	string	Canonical commodity code
`commodities[].name`	string	Human-readable name
`commodities[].price`	number	Latest spot price
`commodities[].currency`	string	Price currency (USD, EUR, GBP, GBp)
`commodities[].unit`	string	Pricing unit (e.g. "barrel")
`commodities[].change_24h_pct`	number	24-hour percent change
`commodities[].change_24h_abs`	number	24-hour absolute change
`commodities[].as_of`	string	ISO 8601 timestamp of the underlying price (UTC)
`commodities[].source`	string	Data source identifier
`commodities[].stale`	boolean	`true` if the price is older than your tier's freshness floor
`commodities[].forecast_1m`	object	1-month forecast (Brent / WTI / Natural Gas only); omitted otherwise
`commodities[].forecast_1m.point`	number	Point estimate
`commodities[].forecast_1m.low`	number	Lower bound
`commodities[].forecast_1m.high`	number	Upper bound
`commodities[].forecast_1m.confidence`	number	Confidence (0–1)
`spreads[]`	array	Notable spreads between included commodities
`summary`	string	Plain-English summary (only when `narrative=true`)
`context`	object	Disruptions + indicators (only when `narrative=true`)

Errors

Code	Status	Description
`VALIDATION_ERROR`	400	`codes` parameter missing, or one or more codes invalid (response includes fuzzy suggestions)
`BRIEF_CODE_LIMIT`	422	Requested more codes than your plan allows; response includes `limit`, `requested`, and `upgrade_url`
`INVALID_API_KEY`	401	Missing or invalid API key
`RATE_LIMIT_EXCEEDED`	429	Rate limit exceeded

Example BRIEF_CODE_LIMIT response:

{
  "status": "error",
  "error": "BRIEF_CODE_LIMIT",
  "message": "Your plan allows up to 3 commodity codes per market-brief (requested: 5). Upgrade for more.",
  "limit": 3,
  "requested": 5,
  "upgrade_url": "https://oilpriceapi.com/pricing?utm_source=api&utm_medium=market_brief&utm_campaign=brief_code_limit"
}

Examples

# Structured brief for two crude benchmarks
curl "https://api.oilpriceapi.com/v1/market-brief?codes=BRENT_CRUDE_USD,WTI_USD" \
  -H "Authorization: Token YOUR_API_KEY"

# Add a plain-English narrative + market context
curl "https://api.oilpriceapi.com/v1/market-brief?codes=BRENT_CRUDE_USD,WTI_USD,NATURAL_GAS_USD&narrative=true" \
  -H "Authorization: Token YOUR_API_KEY"

# Python
import requests

def market_brief(codes, narrative=False):
    url = 'https://api.oilpriceapi.com/v1/market-brief'
    headers = {'Authorization': 'Token YOUR_API_KEY'}
    params = {'codes': ','.join(codes)}
    if narrative:
        params['narrative'] = 'true'

    response = requests.get(url, headers=headers, params=params)
    data = response.json()['data']

    for c in data['commodities']:
        print(f"{c['name']}: {c['price']} {c['currency']} "
              f"({c['change_24h_pct']:+}% 24h)")
    return data

market_brief(['BRENT_CRUDE_USD', 'WTI_USD'], narrative=True)

// JavaScript
async function marketBrief(codes, narrative = false) {
  const params = new URLSearchParams({ codes: codes.join(",") });
  if (narrative) params.set("narrative", "true");

  const response = await fetch(
    `https://api.oilpriceapi.com/v1/market-brief?${params}`,
    { headers: { Authorization: "Token YOUR_API_KEY" } },
  );

  const { data } = await response.json();
  for (const c of data.commodities) {
    console.log(
      `${c.name}: ${c.price} ${c.currency} (${c.change_24h_pct}% 24h)`,
    );
  }
  return data;
}

Best Practices

Batch commodities: request everything you need in one brief rather than many single-price calls — the brief counts as 1 request.
Use narrative for agents: when an AI agent needs a human-readable read of the market, narrative=true returns a ready-to-relay summary.
Check stale: on paid tiers a stale: true flag means the underlying price is older than your tier's freshness floor.
For recurring monitoring, create a Subscription / Watch instead of polling this endpoint on a schedule.

Subscriptions / Watches - Recurring, poll-based monitoring
Agent Subscriptions with MCP - AI-agent recipe
Get Latest Prices - Single-commodity spot price
Batch Prices - Multiple prices in one call