Get Trade Flow Records
comtrade_get_trade_flowsRead-only
Fetch bilateral trade flow records — the primary data retrieval tool. Returns trade value in USD (primaryValue — FOB for exports, CIF for imports), quantity, net weight, and period/commodity/partner metadata for each row. Accepts multiple periods and commodity codes per call; pass partner_code 0 to get totals aggregated across all partners. Omit cmd_code or pass "TOTAL" to aggregate all commodities. Preview makes one paced request per served period, with a 500-record cap per request. Use comtrade_lookup_countries to resolve reporter/partner codes and comtrade_search_commodities to resolve HS codes. For SITC, supply codes from the selected SITC revision.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| freq | No | Frequency: A=annual, M=monthly. | A |
| period | Yes | One or more periods to query. Annual: "YYYY" (e.g. ["2022", "2023"]). Monthly: "YYYYMM" (e.g. ["202201", "202202"]). Serves the first 12 periods and discloses the remainder; input ceiling 120. | |
| cmd_code | No | HS or SITC commodity codes to query. Serves the first 20 codes and discloses the remainder; input ceiling 200. Pass ["TOTAL"] or omit to aggregate all commodities. Use comtrade_search_commodities for HS codes only. | |
| flow_code | Yes | Trade flow direction: M=imports, X=exports, RX=re-exports, RM=re-imports. | |
| partner_code | No | M49 code of the trade partner. Use 0 to aggregate across all partners (World total). Omit to get a disaggregated breakdown by partner country. | |
| reporter_code | Yes | M49 numeric code of the reporting country. Use comtrade_lookup_countries to resolve names to codes. | |
| classification | No | Goods classification: HS/H0–H6 or SITC S1–S4/SS. Defaults to combined HS. | HS |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Present when the call failed. Absent on success. | |
| shown | No | Number of records returned in this response. | |
| notice | No | Recovery hint when no records are returned. Absent on successful responses. | |
| records | No | Trade flow records. | |
| truncated | No | True when any preview response reached 500 and may be incomplete. | |
| totalCount | No | Sum of upstream response counts before local filtering; not a full match count when capped. | |
| truncationHint | No | Query narrowing and authenticated access guidance when possibly incomplete. | |
| referenceNotice | No | Notice when reference descriptions could not be loaded; codes and trade values remain available. | |
| unservedPeriods | No | Periods beyond the 12-period work cap; query them separately. | |
| unservedCmdCodes | No | Commodity codes beyond the 20-code work cap; query them separately. |