---
title: "GetTradeFlows"
method: GET
path: "/api/trade/v1/get-trade-flows"
tags: ["TradeService"]
---

# GetTradeFlows

`GET /api/trade/v1/get-trade-flows`

## Request

- Base URL: `https://api.worldmonitor.app`
- URL: `https://api.worldmonitor.app/api/trade/v1/get-trade-flows`
- Auth: one of:
  - API key in header `X-WorldMonitor-Key`
  - API key in header `X-Api-Key`

Get bilateral merchandise trade flows.

## Query parameters

- `reporting_country` string
- `partner_country` string
- `years` integer
- `jmespath` string

## Response `200`

OK

- WorldmonitorTradeV1GetTradeFlowsResponse: Response containing trade flow records.
  - `flows` WorldmonitorTradeV1TradeFlowRecord[]
    - `reportingCountry` string: WTO member code of reporting country.
    - `partnerCountry` string: WTO member code of partner country.
    - `year` integer: Year of observation.
    - `exportValueUsd` number, double: Merchandise export value in millions USD.
    - `importValueUsd` number, double: Merchandise import value in millions USD.
    - `yoyExportChange` number, double: Year-over-year export change (percentage).
    - `yoyImportChange` number, double: Year-over-year import change (percentage).
    - `productSector` string: Product sector or HS chapter.
  - `fetchedAt` string: ISO 8601 timestamp when data was fetched from WTO.
  - `upstreamUnavailable` boolean: True when flows could not be served because of a fault — a seeded pair whose cache entry is gone, or a cache read that failed. False when flows are served AND when the request names a combination that is simply not part of seeded coverage, which is a contract answer rather than an outage.
  - `unavailableReason` 'TRADE_FLOW_UNAVAILABLE_REASON_UNSPECIFIED' | 'TRADE_FLOW_UNAVAILABLE_REASON_INVALID_REQUEST' | 'TRADE_FLOW_UNAVAILABLE_REASON_NOT_COVERED' | 'TRADE_FLOW_UNAVAILABLE_REASON_SEED_MISSING' | 'TRADE_FLOW_UNAVAILABLE_REASON_COVERAGE_UNKNOWN' | 'TRADE_FLOW_UNAVAILABLE_REASON_CACHE_UNAVAILABLE': TradeFlowUnavailableReason says why no rows were returned. The distinction that matters is NOT_COVERED — a contract answer, nothing is broken and a retry cannot help — against every other member, which names a fault.
  - `coverageStartYear` integer: First and last calendar year covered by `flows`. Both are 0 when no flows are returned. This is the effective window after slicing to `years`, which may be narrower than the requested lookback when the seed starts later.
  - `coverageEndYear` integer

## Other responses

- `400`: Validation error
- `401`: Missing or invalid API key.
- `403`: API access requires an active subscription (the API key's subscription is inactive or expired).
- `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)