---
title: "UK trade balance headlines"
method: GET
path: "/api/v1/ons/trade-balance"
tags: ["Statistical Agencies"]
---

# UK trade balance headlines

`GET /api/v1/ons/trade-balance`

UK trade in goods and services from Office for National Statistics. Trade in goods balance SA (BOKI, GBP millions) and total trade imports (goods plus services) SA (IKBI, GBP millions). Monthly, roughly six weeks after reference month.

## Query parameters

- `limit` integer — Number of most-recent monthly observations per series.

## Response `200`

Monthly trade in goods balance and total trade imports.

- EnvelopeOnsTradePayload
  - `data` OnsTradePayload, required
    - `goods_balance` OnsSeries, required — One curated ONS CDID series, unified shape regardless of parent dataset.
      - `cdid` string, required — ONS time series identifier (stable 4-char code, e.g. 'L55O', 'MGSX').
      - `title` string, nullable — Series title as published by ONS.
      - `unit` string, nullable — Unit of measure (e.g. '%', 'index 2015=100', 'GBP m', 'persons').
      - `frequency` string, required — Canonical frequency returned in `observations` ('monthly', 'quarterly', 'annual').
      - `observations` OnsObservation[], required — Observations at the canonical frequency, ordered oldest to newest.
        - `period` string, required — ISO 8601 start-of-period (YYYY-MM-DD). Months = first day of month, quarters = first day of quarter, years = January 1.
        - `period_label` string, required — Original ONS label, e.g. '2026 FEB', '2025 Q4', '2024', or rolling LFS label '2025 NOV-JAN'.
        - `value` number, nullable — Numeric observation value. Null if upstream reported an empty cell.
        - `frequency` string, required — Frequency of this row: 'monthly', 'quarterly', or 'annual'.
        - `update_date` string, nullable — ONS updateDate for the observation (ISO 8601 UTC).
      - `rollups` object — Optional higher/lower frequency rollups keyed by 'annual', 'quarterly', or 'monthly'.
    - `total_trade_imports` OnsSeries, required — One curated ONS CDID series, unified shape regardless of parent dataset.
      - `cdid` string, required — ONS time series identifier (stable 4-char code, e.g. 'L55O', 'MGSX').
      - `title` string, nullable — Series title as published by ONS.
      - `unit` string, nullable — Unit of measure (e.g. '%', 'index 2015=100', 'GBP m', 'persons').
      - `frequency` string, required — Canonical frequency returned in `observations` ('monthly', 'quarterly', 'annual').
      - `observations` OnsObservation[], required — Observations at the canonical frequency, ordered oldest to newest.
        - `period` string, required — ISO 8601 start-of-period (YYYY-MM-DD). Months = first day of month, quarters = first day of quarter, years = January 1.
        - `period_label` string, required — Original ONS label, e.g. '2026 FEB', '2025 Q4', '2024', or rolling LFS label '2025 NOV-JAN'.
        - `value` number, nullable — Numeric observation value. Null if upstream reported an empty cell.
        - `frequency` string, required — Frequency of this row: 'monthly', 'quarterly', or 'annual'.
        - `update_date` string, nullable — ONS updateDate for the observation (ISO 8601 UTC).
      - `rollups` object — Optional higher/lower frequency rollups keyed by 'annual', 'quarterly', or 'monthly'.
  - `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.
- `422` — Validation Error
- `429` — Daily rate limit exceeded. Check `X-RateLimit-Reset` for the next window.
- `503` — Upstream source is temporarily unavailable. Retry after a short delay.

---

[API](https://skmtc.net/sugra/apis/sugra-api.md) · [All operations](https://skmtc.net/sugra/apis/sugra-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sugra/sugra-api/versions/4e2740743eb4/schema)