---
title: "Get Volatility Supply Shocks"
method: POST
path: "/api/volatility/supply-shocks"
tags: ["volatility"]
---

# Get Volatility Supply Shocks

`POST /api/volatility/supply-shocks`

## Request

- Base URL: `https://tradedashboard.eu` (the document declares no server; this is the origin it was published from)
- URL: `https://tradedashboard.eu/api/volatility/supply-shocks`
- Auth: none declared

Detect abnormal collapses in trade volumes: for each partner/product
pair with enough sustained activity, flag periods where volume drops well
below the pair's historical average (> 2 sigma by default). Returns ranked
shock events per flow, each with timeline phases (baseline, decline,
disruption, recovery, ...), magnitude, abnormality score and the
underlying series. Tunable via the query params documented below; lower
thresholds surface more (weaker) shocks. Streams NDJSON.

## Query parameters

- `entity_level` 'partner' | 'reporter': Dimension to analyse. 'partner' — how concentrated/volatile is the reporter's trade across its trading partners? 'reporter' — how concentrated/volatile is a given partner's trade across EU member states? When 'reporter', the 'partner' query param is required.
- `partner` string, nullable: Partner country name (English). Required when entity_level='reporter'.
- `min_abnormality` number: Minimum statistical abnormality of the volume crash, in sigma. Lower values flag more (weaker) shocks; higher values flag only extreme events. Default 2.0.
- `relative_threshold` number: Minimum drop relative to peak volume to count as a collapse (e.g. 0.10 = 10% drop). Default 0.10.
- `min_active_years` integer: Consecutive years of regular trade required before a collapse can be flagged. Default 2.
- `cumulative_share` number: Only the top trading partners that together account for this share of total trade are analysed (e.g. 0.80 = top 80%). Default 0.80.
- `max_tolerated_gap` integer: Consecutive quiet periods allowed within an otherwise stable trading relationship. Default 2.

## Request body

- DashboardQuery: Shared request body for every analytical endpoint. One product (or a list of products to aggregate), one reporter (or group of reporters), a partner set, a period window and a frequency fully describe a slice of Eurostat Comext/PRODCOM data. Individual endpoints read extra, endpoint-specific options from the query string (e.g. ``entity_level``, ``flow``, ``partner``) rather than from this body.
  - `product` union, required: Combined Nomenclature customs code(s), 2–8 digits, or the literal 'TOTAL' meta-aggregate (all products combined). Pass a list to aggregate several codes: their volumes are summed and prices volume-weighted across every tab — except the Cross-section views, which keep each code separate.
    - string
    - string[]
  - `reporter` string: Declaring entity: an EU member state, an EU candidate country, Northern Ireland ('XI'), or one of the three aggregate presets ('European Union', 'Euro area', 'EU candidate countries'), or a predefined reporter group name.
  - `reporter_members` string[], nullable: Explicit member countries for a custom reporter group. Each entry must be an EU member state, EU candidate country, or Northern Ireland. When more than one member is supplied the frame is aggregated into a synthetic group named after 'reporter'.
  - `partner_set` string: Named partner preset, e.g. 'non-EU countries', 'EU countries', 'all countries', or a predefined partner group.
  - `partners` string[], nullable: Explicit partner-country list that overrides 'partner_set' when present.
  - `period_start` string: Inclusive start of the analysis window, ISO month 'YYYY-MM'.
  - `period_end` string: Inclusive end of the analysis window, ISO month 'YYYY-MM'. Defaults to roughly three months ago — the latest period Eurostat typically has fully reported.
  - `frequency` string: Resampling frequency for the series: 'month', 'quarter' or 'year'.
  - `n_top` integer: Number of top entities (by volume/value) to break out individually in charts.
  - `include_other` boolean: Bundle entities outside the top-N into a single 'Other' bucket.
  - `remove_outliers` boolean: Drop extreme unit-price outliers before computing weighted-average prices.
  - `midpoint` string, nullable: Split point 'YYYY-MM' for the Pattern Shifts tab: the window is cut in two here and the before/after change per entity is reported. Defaults to the middle of the period when omitted.
  - `lang` string: Language for translated labels in the response (en, de, fr, es, it, ro).
  - `prodcom_code` string, nullable: Specific PRODCOM dataset code to pin for the Net Import Reliance and Trade Intensity tabs, when a single CN code maps to several. Ignored elsewhere.

## Response `200`

Successful Response

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/tradedashboard/apis/eu-trade-explorer.md) · [All operations](https://skmtc.dev/tradedashboard/apis/eu-trade-explorer/llms.txt) · [OpenAPI document](https://skmtc.dev/tradedashboard/apis/eu-trade-explorer/revisions/b9abc715a5c2?raw)