---
title: "GetFoodStocks"
method: GET
path: "/api/resilience/v1/get-food-stocks"
tags: ["ResilienceService"]
---

# GetFoodStocks

`GET /api/resilience/v1/get-food-stocks`

## Request

- Base URL: `https://api.worldmonitor.app`
- URL: `https://api.worldmonitor.app/api/resilience/v1/get-food-stocks`
- Auth: one of:
  - API key in header `X-WorldMonitor-Key`
  - API key in header `X-Api-Key`
  - HTTP bearer

Returns seeded PSD cereal balances with FAOSTAT gap fill. PRO-gated. Requires entitlement tier >= 1.

## Query parameters

- `countryCode` string
- `commodity` string
- `jmespath` string

## Response `200`

OK

- WorldmonitorResilienceV1GetFoodStocksResponse: GetFoodStocksResponse is the filtered seed snapshot.
  - `records` WorldmonitorResilienceV1FoodStockRecord[]
    - `countryCode` string: ISO 3166-1 alpha-2, or "WORLD" for the global balance sheet.
    - `commodity` string: Commodity slug: wheat, corn, rice, soybeans, barley, palmOil.
    - `marketingYear` string: Marketing year label stored verbatim, e.g. "2025/26". Never a calendar year.
    - `stocksToUse` number, double: Ending stocks divided by total use (0.18 = 18%). Read has_stocks_to_use BEFORE this value: proto3 has no presence for a bare double, so an unknown ratio and a genuine 0% are the same wire value. USDA/PSD estimates ending stocks only for selected countries, so a minor producer routinely reports real production and consumption with no stocks series at all — and 0.0% on a food-security surface reads as famine, not as "not measured".
    - `hasStocksToUse` boolean: False when stocks_to_use is a placeholder rather than a measurement.
    - `endingStocksTmt` number, double: Ending stocks in thousand metric tons. Read has_ending_stocks first, for the same reason as stocks_to_use above.
    - `hasEndingStocks` boolean: False when ending_stocks_tmt is a placeholder rather than a measurement.
    - `totalUseTmt` number, double: 1000 MT. PSD country: consumption + exports. WORLD: consumption. FAOSTAT: domestic-supply quantity.
    - `productionTmt` number, double: Production in thousand metric tons. Zero when unknown.
    - `consumptionTmt` number, double: 1000 MT. PSD: domestic consumption. FAOSTAT: domestic-supply quantity. Zero when unknown.
    - `importsTmt` number, double: Imports in thousand metric tons. Zero when unknown.
    - `exportsTmt` number, double: Exports in thousand metric tons. Zero when unknown.
    - `unit` string: Unit the raw quantities are stored in, typically "1000 MT".
    - `source` string: "psd" or "faostat". FAOSTAT Food Balances supplies production and domestic-supply, but no stocks.
  - `fetchedAt` string: ISO-8601 time the seeder wrote resilience:food-stocks:v1. Empty when unavailable.
  - `unavailable` boolean: True when the seed is missing or unreadable (not a confirmed zero).
  - `calorieWeightedStocksToUse` number, double: Calorie-weighted stocks-to-use for the requested country, or 0 when unknown / unfiltered.

## Other responses

- `400`: Validation error
- `401`: Missing or invalid API key.
- `403`: PRO entitlement access denied.
- `429`: Rate limit exceeded.
- `503`: Service unavailable. Billing-verification responses include code and X-Billing-Verification; other gateway infrastructure failures use the generic GatewayError shape.
- `default`: Gateway or handler error response.

---

[API](https://skmtc.dev/worldmonitor/apis/worldmonitor-api.md) · [All operations](https://skmtc.dev/worldmonitor/apis/worldmonitor-api/llms.txt) · [OpenAPI document](https://skmtc.dev/worldmonitor/apis/worldmonitor-api/revisions/e3dc8463a5c9?raw)