The GTA data endpoints record what governments announced; the US tariff endpoints (TAU) compute what a shipment pays, reconstructing the full US tariff stack in force on any date from 2025-01-20 onward. Price one shipment with the calculation kit, widen to whole portfolios with the aggregate views, and resolve the codes every call expects with the reference lists.
Updated 2026-07-12
Business question: What tariff rate does a shipment of a given product, from a given origin, actually pay on a given date under the current US regime?
Applied rate, not statutory MFN: TAU returns the rate implied by every measure in force on a given date (HTS, Section 232, IEEPA, Section 122, emergency tariffs, and Section 301, layered together), not the published Most-Favoured-Nation schedule rate alone.Data floor: 2025-01-20: the model reconstructs the regime stack from the US presidential transition onward; policy_date values before 2025-01-20 are rejected. Every TAU example on this page sits inside this 2025 tariff environment.Six instruments, one formula: a calculated rate decomposes into hts_rate, s232_rate, ieepa_rate, s122_rate, emergency_rate, and s301_rate, summed per a rate_formula identifier returned alongside the total (e.g. "HTS + IEEPA + S122 + Emergency + S301" when every layer but MFN is active for that date).Deals carry counterfactual rates: bilateral trade deals are modelled as toggleable adjustments on a scenario; toggling one off returns the counterfactual rate that would apply without it.GET with query parameters: every endpoint on this page is a GET request: filters are query-string parameters, not a request_data JSON body, unlike the GTA data family.Same auth header, live-reverified: TAU endpoints accept the identical Authorization: APIKey <your-key> header used throughout this quickstart. Reverified live against /api/v1/tau/reference/countries/: a bare APIKey: header returns 401 Unauthorized on TAU exactly as it does on the GTA family, confirming the header form carries over unchanged across both product surfaces.Business question: What decomposes a shipment's applied rate into its formula, and what would it be without a bilateral deal in force?
The plain single-rate lookup, GET /api/v1/tau/calculate/single/, answers what a shipment pays. This endpoint answers why: it returns the same baseline rate plus a self-contained calculation_kit object naming the formula, listing any parameters an integrator can tune client-side, and pricing every bilateral deal in force against its counterfactual.
hs_8digit=87032300 (passenger cars) from Germany returns an empty tunable_parameters list: the endpoint's own documentation says that happens "when the rate is fully determined by regime defaults," and that is exactly this case, so it will not exercise what this section needs to show. This example switches product to hs_8digit=72142000, a chapter-72 (iron and steel) line, and tests several bilateral-deal countries side by side: Germany, Japan, South Korea, and Switzerland all carry a deal on this product but with zero effect on the rate (their floor formulas do not bind on standard steel). The United Kingdom is the one candidate where the deal actually moves the number.
curl -s -X GET https://api.globaltradealert.org/api/v1/tau/calculate/single/kit/?hs_8digit=72142000&un_code=826&policy_date=2026-04-15 \
-H "Authorization: APIKey $GTA_API_KEY"import os
import requests
API_KEY = os.environ["GTA_API_KEY"]
response = requests.get(
"https://api.globaltradealert.org/api/v1/tau/calculate/single/kit/",
headers={"Authorization": f"APIKey {API_KEY}"},
params={"hs_8digit": "72142000", "un_code": "826", "policy_date": "2026-04-15"},
)
response.raise_for_status()
result = response.json()
Executed live 2026-07-11: 42.22% applied rate on the same steel line from the United Kingdom.
hs_8digit, un_code, policy_date: all three required, same semantics as /calculate/single/.scenario_id (optional, default 1): the read-only baseline scenario used throughout this page so far; a custom, toggleable scenario appears in the Scenarios and Deals section below.mfn_source, activate_proposals, disable_usmca_hts_weighting, exclude_s301_tariffs (all optional): analytical overrides on the MFN layer, parked-measure activation, USMCA weighting, and the China S301 layer respectively. None change the baseline reading shown here; treat them as parameter notes, not a second worked example.calculation_kit.formula_name (matching the baseline's own rate_formula) reads HTS + S232/IEEPA/S122 + Emergency + S301, the materials branch of the six-instrument formula introduced above. The response lists three tunable_parameters, each carrying a sensitivity hint an integrator can surface as a slider: content_share (metal content share, medium), us_metal_share (US-origin metal share, medium), and aircraft_share (WTO civil aircraft share, not applicable outside aircraft products). One discrete_options entry, annex_classification, lets a caller switch between the standard, reduced, and temporary-floor S232 tiers.
deals_in_force carries one entry: the UK Economic Prosperity Deal, effective 2025-06-30, which moves qualifying UK-content steel onto the reduced Annex I-B rate from 2026-04-06 onward. The 42.22% applied rate already reflects that deal; its counterfactual_final_rate of 49.6% is what this shipment would pay without it, a rate_delta_pp of -7.38.
Business question: What applied rate does every tariff line in a product chapter face from one origin, and how do you page through a result set too large for one call?
The kit endpoint prices one shipment in detail. Batch trades detail for breadth: it runs the same six-instrument engine across many product-country combinations in one call and returns a standard DRF-paginated envelope (count, next, previous, results), built for pulling a whole product line or a whole trading relationship a page at a time.
curl -s -X GET https://api.globaltradealert.org/api/v1/tau/calculate/batch/?hs_chapter=72&un_code=826&policy_date=2026-04-15&limit=5&offset=0 \
-H "Authorization: APIKey $GTA_API_KEY"import os
import requests
API_KEY = os.environ["GTA_API_KEY"]
response = requests.get(
"https://api.globaltradealert.org/api/v1/tau/calculate/batch/",
headers={"Authorization": f"APIKey {API_KEY}"},
params={
"hs_chapter": "72",
"un_code": "826",
"policy_date": "2026-04-15",
"limit": "5",
"offset": "0",
},
)
response.raise_for_status()
result = response.json()
Executed live 2026-07-11: 109 UK-origin tariff lines in chapter 72 (iron and steel) match; this call returns the first 5.
hs_8digit, un_code, hs_chapter: at least one required to scope the batch. The schema documents hs_8digit and un_code as comma-separated arrays; live behaviour disagrees on both. Two individually-valid HS8 codes supplied as repeated hs_8digit params return only the last one (count=1, not 2), and a comma-joined un_code value is rejected outright (400, "Incorrect type. Expected pk value, received str."). hs_chapter takes one two-digit value and has no such defect: it is the reliable way to pull a genuine multi-row portfolio in one call, which is what this example uses.limit (default 100, hard-capped 1000) / offset: standard page size and position.mfn_source, activate_proposals, disable_usmca_hts_weighting, exclude_s301_tariffs, scenario_id (all optional): the same overrides and scenario selector as the kit endpoint, as parameter notes only.Page 1: HS 72022150 at 11.5%, 72022900 at 10%, 72024910 at 1.9%, 72024950 at 3.1%, 72027000 at 14.5%. rate_formula varies row to row inside the same chapter: 72024910 and 72024950 carry HTS + S301 only, while the other three carry the full HTS + IEEPA + S122 + Emergency + S301 stack, meaning Section 232 does not reach every line in chapter 72. A single chapter-wide average would hide that split.
next returns a different five rowsPage 1's next field is https://api.globaltradealert.org/api/v1/tau/calculate/batch/?hs_chapter=72&limit=5&offset=5&policy_date=2026-04-15&un_code=826. Following it live, below, returns five different lines starting at 72029100, with previous now pointing back to the first page: real pagination, confirmed by executing it, not a documented claim.
curl -s -X GET https://api.globaltradealert.org/api/v1/tau/calculate/batch/?hs_chapter=72&un_code=826&policy_date=2026-04-15&limit=5&offset=5 \
-H "Authorization: APIKey $GTA_API_KEY"import os
import requests
API_KEY = os.environ["GTA_API_KEY"]
response = requests.get(
"https://api.globaltradealert.org/api/v1/tau/calculate/batch/",
headers={"Authorization": f"APIKey {API_KEY}"},
params={
"hs_chapter": "72",
"un_code": "826",
"policy_date": "2026-04-15",
"limit": "5",
"offset": "5",
},
)
response.raise_for_status()
result = response.json()
Executed live 2026-07-11: page 2 of 109, rows 6-10, first line HS 72029100 at 3.7%.
Business question: How did the applied rate on one product-origin combination move across a date range, and what happens to it across a policy transition?
The aggregate family steps back from one shipment to a full portfolio. aggregate/timeline samples canonical policy-change dates inside a date range (plus the range's own endpoints) and returns one trade-weighted row per date: the fastest way to see how a regime shift reads for a real product-country combination, rather than reading it only from the instrument facts stated in the how-it-works section above.
That section names the IEEPA-to-Section 122 transition as part of the six-instrument formula behind every applied rate. The Supreme Court's ruling zeroed IEEPA tariffs on 2026-02-20; Section 122 took effect four days later, on 2026-02-24, as the replacement mechanism. The example below straddles both dates deliberately, sampling 2026-02-15 to 2026-03-01 on the same UK chapter-72 steel line (hs_chapter=72, un_code=826) used in the kit and batch sections above.
curl -s -X GET https://api.globaltradealert.org/api/v1/tau/aggregate/timeline/?start_date=2026-02-15&end_date=2026-03-01&hs_chapter=72&un_code=826 \
-H "Authorization: APIKey $GTA_API_KEY"import os
import requests
API_KEY = os.environ["GTA_API_KEY"]
response = requests.get(
"https://api.globaltradealert.org/api/v1/tau/aggregate/timeline/",
headers={"Authorization": f"APIKey {API_KEY}"},
params={
"start_date": "2026-02-15",
"end_date": "2026-03-01",
"hs_chapter": "72",
"un_code": "826",
},
)
response.raise_for_status()
result = response.json()
Executed live 2026-07-11: 4 rows, one per canonical sample date inside the range, aggregated across 109 UK chapter-72 flows worth $0.45bn.
start_date, end_date (both required): the endpoint's own canonical-date logic already lands on both SCOTUS dates inside this window; no dates override was needed.hs_8digit, hs_chapter, un_code (all optional): filters restricting the aggregation. This example reuses the batch section's UK chapter-72 filter for continuity.countries (optional, up to 10 UN M49 codes): adds a per-country overlay rate to each row's country_rates field. Not exercised here, since un_code already restricts this example to one origin.dates (optional, up to 60 ISO dates): overrides the canonical sampling grid entirely. A parameter note only in this example; the default grid already surfaces both dates this section needs.sample_size, scenario_id, activate_proposals (all optional): the same overrides used throughout this page.2026-02-15: 21.05% applied, with avg_ieepa at 9.90pp. 2026-02-20 (IEEPA zeroed): the rate falls to 18.48%, with avg_ieepa at 0.0. 2026-02-24 (Section 122 effective): the rate returns to 21.05%, with avg_s122 now carrying the same 9.90pp avg_ieepa gave up. 2026-03-01 confirms the post-transition rate holds. avg_s232 (21.54pp) and avg_hts (0.17pp) stay fixed across all four dates: on this line, the SCOTUS transition moves only the IEEPA-to-S122 component, not the Section 232 metals tariff underneath it.
Business question: Which countries in a peer group face the highest, or lowest, trade-weighted applied rate right now?
aggregate/country_ranking ranks the members of a fixed country group (WORLD, G20, G7, BRICS, ASEAN, LDC) by trade-weighted applied rate on one policy date, aggregating across every product line the API holds for each country. It answers a portfolio question the single-shipment and batch endpoints above cannot: not what one shipment pays, but who, across a whole peer group, currently pays the most.
curl -s -X GET https://api.globaltradealert.org/api/v1/tau/aggregate/country_ranking/?policy_date=2026-04-15&group=G20&top_n=10 \
-H "Authorization: APIKey $GTA_API_KEY"import os
import requests
API_KEY = os.environ["GTA_API_KEY"]
response = requests.get(
"https://api.globaltradealert.org/api/v1/tau/aggregate/country_ranking/",
headers={"Authorization": f"APIKey {API_KEY}"},
params={"policy_date": "2026-04-15", "group": "G20", "top_n": "10"},
)
response.raise_for_status()
result = response.json()
Executed live 2026-07-11: 10 G20 members ranked by applied rate, aggregated across 17 trade flows.
policy_date (required): same regime-reconstruction semantics as the calculation endpoints above; must be on or after 2025-01-20.group (default G20): one of WORLD, G20, G7, BRICS, ASEAN, LDC.top_n (default 10, capped 50): row count returned.compare_date (optional): switches the ranking from absolute rate to rate delta (policy_date rate minus compare_date rate), surfacing winners and losers of a regime change rather than a current leaderboard. Not executed as a second worked example here; sanity-probed only (results/probe-log.jsonl), confirming it re-ranks by delta_pp rather than avg_rate, exactly as documented.sample_size (default 200, capped 1000), scenario_id, activate_proposals (all optional): the same overrides used throughout this page.China: 22.43% applied, $289.89bn traded. Indonesia: 16.29% ($22.89bn). Turkey: 15.57% ($12.49bn). Japan: 12.61% ($117.84bn). South Korea: 11.53% ($108.49bn). The ranking does not track trade volume: Japan and South Korea both trade far more with the US than Indonesia does, yet both rank below it because their applied rate is lower.
Business question: For one country, what does its full tariff exposure look like, by HS2 chapter and by individual product?
Country ranking above places a country within its peer group. Country brief opens up its exposure in detail: one call returns an HS2 chapter-level breakdown (trade-weighted rate, trade volume, flow count per chapter) plus the top-N individually most-exposed HS8 products, each carrying its own final rate and formula label, a compact one-page country exposure view.
This example uses China (un_code=156). Tested against UK and Germany at the same policy date, China returns the largest trade volume ($438.95bn against UK's $68.08bn and Germany's $160.44bn) and the widest spread on both dimensions (chapter rates from 11.78% to 36.21%; product rates from 0.0% to 53.4%), the clearest demonstration of both the chapter breakdown and the top-products list.
curl -s -X GET https://api.globaltradealert.org/api/v1/tau/aggregate/country_brief/?un_code=156&policy_date=2026-04-15&top_n=5 \
-H "Authorization: APIKey $GTA_API_KEY"import os
import requests
API_KEY = os.environ["GTA_API_KEY"]
response = requests.get(
"https://api.globaltradealert.org/api/v1/tau/aggregate/country_brief/",
headers={"Authorization": f"APIKey {API_KEY}"},
params={"un_code": "156", "policy_date": "2026-04-15", "top_n": "5"},
)
response.raise_for_status()
result = response.json()
Executed live 2026-07-11: China's brief, 98 HS2 chapters, top 5 exposed products.
un_code (required): UN M49 numeric code of the focus country.policy_date (required): same regime-reconstruction semantics as elsewhere on this page.top_n (default 20, capped 100): number of top-exposed products returned. The chapter-level breakdown is not capped by top_n; it always returns every HS2 chapter carrying trade.scenario_id, activate_proposals (both optional): the same overrides used throughout this page.The chapter breakdown ranks by trade value: chapter 85 (electrical machinery) carries the largest volume at $123.97bn (20.95% average), chapter 84 follows at $82.00bn (31.27%), then chapter 95 ($30.03bn, 11.78%), chapter 39 ($19.29bn, 25.04%), and chapter 94 ($18.52bn, 36.21%, the highest rate of the five). The top-exposed products show the same dispersion line by line: HS 85171300 pays 0.0% (HTS + S301 only) despite being the single largest product by trade value ($41.31bn), while HS 85076000, a fraction of that trade value at $16.24bn, pays 53.4% under the full HTS + S232 + Emergency + S301 stack. A chapter average alone would hide that a country's most-traded product and its most-taxed product are not the same line.
Business question: For one country's top-traded products, does it pay more or less than its peers, and by how much?
Country brief above shows one country's exposure in isolation. Advantage puts it in relative terms: for one origin's top-N products by trade value, it reports the origin's own applied rate alongside a peer rate (the rest of the world by default, or one named peer via compare_un_code) and the resulting advantage in percentage points. Positive means the origin pays less than its peers; negative means it pays more.
This example continues China (un_code=156) against the rest of the world (no compare_un_code supplied), completing the exposure picture the country brief above started.
curl -s -X GET https://api.globaltradealert.org/api/v1/tau/aggregate/advantage/?un_code=156&policy_date=2026-04-15&top_n=5 \
-H "Authorization: APIKey $GTA_API_KEY"import os
import requests
API_KEY = os.environ["GTA_API_KEY"]
response = requests.get(
"https://api.globaltradealert.org/api/v1/tau/aggregate/advantage/",
headers={"Authorization": f"APIKey {API_KEY}"},
params={"un_code": "156", "policy_date": "2026-04-15", "top_n": "5"},
)
response.raise_for_status()
result = response.json()
Executed live 2026-07-11: China's top 5 products by trade value, each against its rest-of-world peer rate.
un_code (required): UN M49 code of the focus country.policy_date (required): same semantics as elsewhere on this page.top_n (default 20, capped 50): number of products compared, ranked by the focus country's trade value.compare_un_code (optional): names a single peer country instead of the rest-of-world default. A parameter note only in this example; supplying, for instance, a G7 peer's UN code would compare the two directly instead of against the aggregate rest-of-world rate.scenario_id, activate_proposals (both optional): the same overrides used throughout this page.Averaged across the five products, China's own rate (18.05%) sits 7.72 percentage points above the peer rate (10.33%). The gap is uneven: HS 85171300 shows none at all (both China and its peers pay 0.0%), while HS 85076000 shows the widest gap in the set, China's 53.4% against a 15.06% peer rate, a 38.34-point disadvantage on a product carrying $16.24bn in trade.
Business question: which UN M49 code does un_code expect on every calculate and aggregate endpoint above, and where does a caller resolve a country name into it?
Every worked example above supplies un_code (826 for the United Kingdom, 156 for China, and so on) as a known value. This endpoint is where those values come from: a searchable, paginated list of the 232 countries and territories the tariff engine models, each carrying its own is_ieepa/is_s232_steel group flags alongside the code.
Gotcha: GTA's UN codes do not always match the standard UN M49 table. The clearest case, and the one the API's own schema names directly, is India: it resolves to un_code=699 in GTA's data, not the standard M49 value of 356. A caller who assumes the standard table queries the wrong country, with no error to signal the mismatch.
curl -s -X GET https://api.globaltradealert.org/api/v1/tau/reference/countries/?search=India \
-H "Authorization: APIKey $GTA_API_KEY"import os
import requests
API_KEY = os.environ["GTA_API_KEY"]
response = requests.get(
"https://api.globaltradealert.org/api/v1/tau/reference/countries/",
headers={"Authorization": f"APIKey {API_KEY}"},
params={"search": "India"},
)
response.raise_for_status()
result = response.json()
Executed live 2026-07-11: 2 matches for the substring "India".
search (optional, minimum 2 characters): case-insensitive country-name substring match. Omit to page through the full list.limit (default 20, hard-capped 1000) / offset: standard DRF pagination, the same shape as /calculate/batch/ above.un_code is 699, not the standard M49 code of 356Two results match "India": British Indian Ocean Territory (un_code=86) and India itself, at un_code=699. Every other spot-checked economy used on this page (China 156, the United Kingdom 826, Germany 276, Brazil 76, Japan 392) resolves to its standard M49 value; India is the documented exception. Resolve un_code here before calling any /calculate/* or /aggregate/* endpoint above, rather than carrying a country's code over from an external table.
Business question: which HS8 tariff lines does hs_8digit accept, and how does a caller find them by chapter or heading rather than guessing a code?
Same gap as un_code above, for the other required identifier: every worked example so far supplies hs_8digit (87032300, 72142000, and the chapter-72 batch) as a known value. This endpoint answers where those values come from: a prefix search over every HS8 line present in US import trade data, from a 2-digit chapter down to the full 8-digit code.
curl -s -X GET https://api.globaltradealert.org/api/v1/tau/reference/products/?search=7214 \
-H "Authorization: APIKey $GTA_API_KEY"import os
import requests
API_KEY = os.environ["GTA_API_KEY"]
response = requests.get(
"https://api.globaltradealert.org/api/v1/tau/reference/products/",
headers={"Authorization": f"APIKey {API_KEY}"},
params={"search": "7214"},
)
response.raise_for_status()
result = response.json()
Executed live 2026-07-11: 5 HS8 lines under heading 7214, the same steel heading the Calculation Kit example above draws its 72142000 line from.
search (required, 2-8 digits): an HS code prefix. A 2-digit value scopes to a chapter (matching hs_chapter on /calculate/batch/), 4 digits to a heading, up to the full 8-digit code.limit (default 20, hard-capped 1000) / offset: standard DRF pagination.7214 returns 72141000, 72142000, 72143000, 72149100, 72149900: five 8-digit lines under the same 4-digit heading. Each record's description field currently echoes the code itself ("HS 72142000") rather than a Harmonized System product name; a caller resolving a line to a human-readable label needs an external HS reference alongside this endpoint, not this endpoint alone.
Business question: what is the master sequence of US tariff-regime activations and bilateral-deal effective dates, and can a caller use it as the backbone for a rate time series without hand-tracking dates?
The aggregate timeline example earlier on this page straddled one known transition, the Supreme Court's IEEPA ruling followed by Section 122 taking effect, by choosing dates manually. This endpoint removes that manual step: it returns every regime-activation and bilateral-deal event the engine tracks, in date order, so a caller can build a dates= list for /aggregate/timeline/ from real events instead of guessing at them.
curl -s -X GET https://api.globaltradealert.org/api/v1/tau/reference/timeline/ \
-H "Authorization: APIKey $GTA_API_KEY"import os
import requests
API_KEY = os.environ["GTA_API_KEY"]
response = requests.get(
"https://api.globaltradealert.org/api/v1/tau/reference/timeline/",
headers={"Authorization": f"APIKey {API_KEY}"},
params={},
)
response.raise_for_status()
result = response.json()
Executed live 2026-07-11: 12 events, 2025-02-04 (China opioid emergency tariff) through 2025-11-14 (Section 232 lumber derivatives).
None: the endpoint takes no query parameters and returns the full timeline as one unpaginated array.
Each event carries a date, a label, and a type of emergency, s232, ieepa, or deal. The 12 events run from the February 2025 opioid emergency tariffs through November 2025's Section 232 lumber-derivatives expansion, including the three bilateral deals used elsewhere on this page (United Kingdom, 2025-06-30; European Union, 2025-09-01; Japan, 2025-09-16). As of this execution the list stops at 2025-11-14 and does not carry the 2026-02-20 IEEPA-zeroing or 2026-02-24 Section 122 events that the aggregate timeline example earlier on this page demonstrates directly: this reference endpoint's own event catalogue has not yet been extended to the SCOTUS transition, so a caller relying on it alone as of this execution date would miss that transition entirely.
Business question: which parked, not-yet-active tariff actions can a caller price in for one request, and does doing so create any lasting state?
Bilateral deals above are already in force; toggling one off shows a counterfactual. Proposals are the opposite case: tariff actions the engine has coded but parked behind a far-future effective date, so they compute to zero at every realistic policy date until a caller explicitly un-parks one via activate_proposals on a calculate or aggregate endpoint. activate_proposals is stateless: it recomputes the rate as if the named action were active for that one request only, without writing to any scenario or the underlying data.
This endpoint itself returned 403 ("You do not have permission to perform this action") when the examples on this page were last executed, a gap distinct from the TAU access this page otherwise demonstrates: the account's TAU entitlement was confirmed live and working across every other reference, calculate, and aggregate endpoint on this page, so the listing endpoint's own APIEndpoint registration is the specific piece still missing. The two example names below come from the OpenAPI schema's own field documentation instead: bra_s301 (Brazil, un_code=76, a negative-list Section 301 archetype) and fl_s301 (a forced-labour Section 301 archetype). Both are confirmed live below via /calculate/single/, the endpoint that actually accepts activate_proposals.
curl -s -X GET https://api.globaltradealert.org/api/v1/tau/calculate/single/?hs_8digit=87032300&un_code=76&policy_date=2026-04-15 \
-H "Authorization: APIKey $GTA_API_KEY"import os
import requests
API_KEY = os.environ["GTA_API_KEY"]
response = requests.get(
"https://api.globaltradealert.org/api/v1/tau/calculate/single/",
headers={"Authorization": f"APIKey {API_KEY}"},
params={"hs_8digit": "87032300", "un_code": "76", "policy_date": "2026-04-15"},
)
response.raise_for_status()
result = response.json()
Executed live 2026-07-11: Brazil, passenger cars (HS 87032300), baseline final_rate 10.0%, s301_rate 0.0.
curl -s -X GET https://api.globaltradealert.org/api/v1/tau/calculate/single/?hs_8digit=87032300&un_code=76&policy_date=2026-04-15&activate_proposals=bra_s301 \
-H "Authorization: APIKey $GTA_API_KEY"import os
import requests
API_KEY = os.environ["GTA_API_KEY"]
response = requests.get(
"https://api.globaltradealert.org/api/v1/tau/calculate/single/",
headers={"Authorization": f"APIKey {API_KEY}"},
params={
"hs_8digit": "87032300",
"un_code": "76",
"policy_date": "2026-04-15",
"activate_proposals": "bra_s301",
},
)
response.raise_for_status()
result = response.json()
Executed live 2026-07-11: same product-country-date, activate_proposals=bra_s301 applied, final_rate rises to 35.0% (s301_rate 25.0, every other instrument unchanged).
activate_proposals (optional, comma-separated names): un-parks one or more proposed actions for this request only. Unknown names return 400. Available on every /calculate/* and /aggregate/* endpoint on this page, /calculate/single/ included.name, title, archetype (negative_list or forced_labour), description, rate_types: the fields this endpoint would return per proposal, once its own permission gap clears.Activating bra_s301 moves this Brazil passenger-car line from 10.0% to 35.0% by adding s301_rate=25.0; every other instrument (hts_rate, s232_rate, ieepa_rate, s122_rate, emergency_rate) stays fixed. A third call, repeating the baseline request with activate_proposals removed, returned a response byte-identical to the pre-activation baseline: the same 10.0% final_rate and 0.0 s301_rate, confirming the parameter mutates nothing beyond the single request that carries it.
Business question: How do I run a deal counterfactual under a scenario I control, and how do I confirm my API footprint leaves no state behind?
Every calculate and aggregate endpoint on this page accepts an optional scenario_id, defaulting to 1. That baseline scenario is read-only: writing to it (PUT, PATCH, or DELETE on /scenario/1/, or a deal toggle with scenario_id=1) returns 403, and this quickstart's own tooling refuses to even attempt it, checked before any request is issued. A caller who wants a scenario to modify creates a custom one first: it inherits every baseline rate, share, and deal toggle, and can then be changed without touching the baseline. This section runs that full lifecycle live: create a scenario, list its inherited deal toggles, disable one, recalculate against it, delete the scenario, and confirm it is gone. The scenario id below (19) was assigned by the API when this run created it and no longer exists; re-running this sequence yourself will get a different id.
curl -s -X POST https://api.globaltradealert.org/api/v1/tau/scenario/ \
-H "Authorization: APIKey $GTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "sgept-cookbook-scenario-workflow-<run-id>", "description": "SGEPT API cookbook scenario-workflow demonstration; created and deleted in one run."}'import os
import requests
API_KEY = os.environ["GTA_API_KEY"]
response = requests.post(
"https://api.globaltradealert.org/api/v1/tau/scenario/",
headers={"Authorization": f"APIKey {API_KEY}"},
json={
"name": "sgept-cookbook-scenario-workflow-<run-id>",
"description": "SGEPT API cookbook scenario-workflow demonstration; created and deleted in one run.",
},
)
response.raise_for_status()
records = response.json()
Executed live 2026-07-11: 201 Created, new scenario id=19.
curl -s -X GET https://api.globaltradealert.org/api/v1/tau/deal/?scenario_id=19 \
-H "Authorization: APIKey $GTA_API_KEY"import os
import requests
API_KEY = os.environ["GTA_API_KEY"]
response = requests.get(
"https://api.globaltradealert.org/api/v1/tau/deal/",
headers={"Authorization": f"APIKey {API_KEY}"},
params={"scenario_id": "19"},
)
response.raise_for_status()
result = response.json()
Executed live 2026-07-11: 9 deals, all inherited from the baseline as is_active: true, including uk_economic_prosperity, the same deal the Calculation Kit section above prices.
curl -s -X PUT "https://api.globaltradealert.org/api/v1/tau/deal/toggle/?name=uk_economic_prosperity&scenario_id=19" \
-H "Authorization: APIKey $GTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"is_active": false}'import os
import requests
API_KEY = os.environ["GTA_API_KEY"]
response = requests.put(
"https://api.globaltradealert.org/api/v1/tau/deal/toggle/?name=uk_economic_prosperity&scenario_id=19",
headers={"Authorization": f"APIKey {API_KEY}"},
json={"is_active": False},
)
response.raise_for_status()
result = response.json()
Executed live 2026-07-11: 200, {"deal_name": "uk_economic_prosperity", "is_active": false, "effective_date": null}. A follow-up GET /deal/?scenario_id=19 confirmed the new state persisted on the scenario, not just in the toggle response.
curl -s -X GET "https://api.globaltradealert.org/api/v1/tau/calculate/single/?hs_8digit=72142000&un_code=826&policy_date=2026-04-15&scenario_id=19" \
-H "Authorization: APIKey $GTA_API_KEY"import os
import requests
API_KEY = os.environ["GTA_API_KEY"]
response = requests.get(
"https://api.globaltradealert.org/api/v1/tau/calculate/single/",
headers={"Authorization": f"APIKey {API_KEY}"},
params={
"hs_8digit": "72142000",
"un_code": "826",
"policy_date": "2026-04-15",
"scenario_id": "19",
},
)
response.raise_for_status()
result = response.json()
Executed live 2026-07-11: final_rate=42.22, unchanged from the baseline reading the Calculation Kit section above already printed for the same product, origin, and date.
curl -s -X DELETE https://api.globaltradealert.org/api/v1/tau/scenario/19/ \
-H "Authorization: APIKey $GTA_API_KEY"import os
import requests
API_KEY = os.environ["GTA_API_KEY"]
response = requests.delete(
"https://api.globaltradealert.org/api/v1/tau/scenario/19/",
headers={"Authorization": f"APIKey {API_KEY}"},
)
response.raise_for_status()
Executed live 2026-07-11: 204 No Content. A follow-up GET /scenario/19/ returned 404 {"detail": "No Scenario matches the given query."}, confirming the scenario left no trace.
name (required on create), description (optional): the only fields a scenario itself carries; both are editable later via PUT /scenario/{id}/.name, scenario_id (both required on /deal/toggle/): the deal identifier (one of the nine named in the Calculation Kit and Batch Rates sections above) and the target scenario. The request body carries is_active (boolean).scenario_id (optional on every calculate and aggregate endpoint on this page, default 1): selects which scenario's rates and deal toggles to compute against.The lifecycle mechanics all behaved as documented: create, list, toggle, delete, and confirm-absent each returned the expected status, and the toggle's new state was independently confirmed by re-listing the scenario's deals rather than trusted from the toggle response alone. What did not happen: recalculating against the custom scenario returned the same 42.22% the baseline scenario already carries, and a follow-up calculate/single/kit/ call against the same scenario still listed uk_economic_prosperity under deals_in_force with its own counterfactual_final_rate of 49.6%, the identical figure the Calculation Kit section already printed from the baseline. As of this execution, a persisted deal toggle on a custom scenario does not propagate to /calculate/* output, even though the schema documents scenario_id on those endpoints as the mechanism for reading it. A caller who wants today's deal-off counterfactual should read counterfactual_final_rate from the kit endpoint's own baseline response (Calculation Kit section above), not toggle a deal on a custom scenario and expect the recalculation to reflect it.
Baseline scenario id 1 is read-only. Every write in this section, create, toggle, delete, targets a scenario this run created. Writing to id=1 itself returns 403; this quickstart's own tooling refuses to even attempt it, checked before any request is issued.
Proposals activation is stateless, scenarios are not. activate_proposals (Proposals section above) recomputes a single request with no lasting effect and nothing to delete afterward. A custom scenario is the opposite: it persists until you delete it, which is why this section deletes its own scenario and confirms the deletion rather than leaving it for a later caller to stumble on.
For agents and LLMs: this page as markdown, llms.txt index, OpenAPI schema.