--- title: "Monthly US trade series for a partner and commodity" method: GET path: "/api/v1/census/trade/flows" tags: ["Global Economy & Trade"] --- # Monthly US trade series for a partner and commodity `GET /api/v1/census/trade/flows` Monthly US exports or imports for one partner (or the world) and one HS code (or all commodities), from 2013-01. Exports are FAS value; imports carry the customs value of general imports plus consumption and CIF values. An unpublished month is an empty `data` with `count: 0` and a `reason`. ## Query parameters - `flow` string — exports or imports - `partner` string — Partner: 'world', or a Census partner code from /census/trade/partners (5700 = China, 0003 = European Union). - `commodity` string — 'all', or an HS code of 2, 4 or 6 digits (27 = mineral fuels). - `from` string, nullable — First month YYYY-MM (default: 24 months before the latest published month). - `to` string, nullable — Last month YYYY-MM (default: open, to the latest published month). ## Response `200` One row per month with the value and the year-to-date value in USD. - EnvelopeCensusTradeFlowsData - `data` CensusTradeFlowsData, required - `flow` string, nullable — exports or imports. - `partner` Partner - `code` string, nullable — Census partner code (4 characters: 5700 = China, 0003 = European Union, 1XXX = North America) or 'world'. - `name` string, nullable — Partner name as Census publishes it. - `kind` string, nullable — country, group (a Census grouping such as the European Union or OPEC) or total (the world). - `commodity` Commodity - `code` string, nullable — HS code (2, 4 or 6 digits) or 'all'. - `level` string, nullable — HS2, HS4 or HS6; null for all commodities. - `description` string, nullable — Census short description of the HS code; null for all commodities. - `basis` string, nullable — Valuation basis of `value` for this flow. - `unit` string, nullable — Currency of every value: USD. - `from` string, nullable — First month requested, YYYY-MM. - `to` string, nullable — Last month requested, YYYY-MM; null for an open range. - `count` union — Number of items in this result set. - integer - number - `data` CensusTradeFlowsDatum[], nullable — One row per month, oldest first. - `month` string, nullable — Month, YYYY-MM. - `value` union — Value in the month, USD (exports: FAS; imports: customs value of general imports). - integer - number - `value_ytd` union — Year-to-date value through the month, USD. - integer - number - `consumption_value` union — Imports only: imports for consumption in the month, USD. - integer - number - `consumption_value_ytd` union — Imports only: year-to-date imports for consumption, USD. - integer - number - `cif_value` union — Imports only: CIF value of general imports in the month, USD. - integer - number - `cif_value_ytd` union — Imports only: year-to-date CIF value, USD. - integer - number - `dataset` string, nullable — Census dataset path the rows come from. - `source` string, nullable — Upstream data source identifier. - `reason` string, nullable — Present only when count is 0: why the answer is empty (an unpublished month names the latest month available). - `note` string, nullable — Present when the requested `to` was past the latest published month: the range was clamped to that month, and `to` carries the clamped value. - `meta` SugraMeta, required — Metadata attached to every /api/v1/* response envelope. - `endpoint` string, required — Requested endpoint path. - `data_time` string, required — ISO 8601 UTC timestamp of the source data, not of the request. - `response_time` string, required — ISO 8601 UTC timestamp when this response was produced. - `provider` string, required — API name and version. - `source` string, nullable — Identifier of the primary upstream source used for this response. - `attribution` string, nullable — Human-readable attribution mandated by an upstream source (e.g. a securities regulator or self-regulatory organization). Present only on responses whose source requires the owner and source to be clearly identified. Do not remove or alter it when using the response. - `fallback_used` boolean, nullable — True when the primary source failed and a fallback produced the data. - `fallback_chain` string[], nullable — Ordered list of sources attempted, in the order they were tried. - `cached` boolean, nullable — True when this response was served from the internal cache. - `stale` boolean, nullable — True when the cached response was returned after the upstream rate-limited or errored. Clients can use this to detect degraded data. ## Other responses - `401` — Missing or invalid `x-api-key` header. JSON body with a stable `code` distinguishing `missing_api_key` (no header sent) from `invalid_api_key` (header sent, key not accepted); any other 401 source carries the generic `unauthorized` with its detail as `reason`. Plus `hint`. `plan` is always null on 401 - an unauthenticated request has no plan; quota exhaustion is 429, not 401. - `422` — Validation Error - `429` — Daily rate limit exceeded. Check `X-RateLimit-Reset` for the next window. - `502` — The upstream source answered with an error or a malformed body. `detail` carries the source, the upstream status and a retry hint. - `503` — Upstream unreachable (typed `detail` object with source and retry hint) or the legacy blanket unavailability (string `detail`). - `504` — The upstream source did not answer within the client deadline. ## Changes - **2026-08-29** `18b96293341c` — 1 info - endpoint added [Change history](https://skmtc.dev/sugra/apis/sugra-api/changes/api/v1/census/trade/flows/get.md) --- [API](https://skmtc.dev/sugra/apis/sugra-api.md) · [All operations](https://skmtc.dev/sugra/apis/sugra-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/sugra/sugra-api/revisions/87582f2e0110/schema)