---
title: "Returns CFTC Commitments of Traders (COT) report rows — weekly aggregated futures + options-on-futures positioning by trader class"
method: GET
path: "/v1/cftc-cot-reports"
---

# Returns CFTC Commitments of Traders (COT) report rows — weekly aggregated futures + options-on-futures positioning by trader class

`GET /v1/cftc-cot-reports`

## Request

- Base URL: `https://api.keyvex.com`
- URL: `https://api.keyvex.com/v1/cftc-cot-reports`
- Auth: API key in header `x-api-key`

Returns CFTC Commitments of Traders (COT) report rows — weekly aggregated futures + options-on-futures positioning by trader class. The COT report is the macro positioning dataset for U.S. futures markets. Released every Friday 3:30 PM ET for the prior Tuesday close.  Trader classes (the CFTC's Legacy report, futures and options combined):   - Non-commercial (large speculators — hedge funds, CTAs)   - Commercial (hedgers — producers, swap dealers)   - Non-reportable (small speculators)  Every row carries report='legacy' and variant='combined' (futures and options together).  Killer query patterns:   - Macro positioning snapshot this week: latest_only=true (gives the     latest report row for every contract in one query)   - Large-spec extremes in S&P: commodity_name='S&P 500 STOCK INDEX'     + sort_by='noncomm_net' + sort_order='desc'   - Gold positioning history: commodity_name='GOLD' + since='2026-01-01'   - Currency COT: contract_market_name substring 'YEN' / 'EURO'  Source: publicreporting.cftc.gov/resource/jun7-fc8e.json, the CFTC's Legacy Futures-and-Options Combined report (Socrata API, free, unauthenticated); each row's source_url is that row's own query on it. Covers EVERY regulated U.S. futures + options- on-futures contract — agricultural commodities, metals, energy, financials, FX, crypto. Pure-publisher posture: raw positioning numbers, no derived sentiment scores.  Key derived fields (computed from raw): noncomm_net (large-spec net), comm_net (hedger net), nonrept_net (small-spec net). Concentration fields show top-4 / top-8 trader net long/short concentration.

## Query parameters

- `id` string
- `cftc_contract_market_code` string
- `contract_market_name` string
- `commodity_name` string
- `since` string
- `until` string
- `latest_only` boolean
- `sort_by` 'report_date' | 'open_interest' | 'noncomm_net' | 'comm_net'
- `sort_order` 'asc' | 'desc'
- `limit` integer

## Response `200`

JSON envelope: { results: [...], count, has_more }.

## Other responses

- `400`: Invalid parameter.
- `401`: Missing or invalid API key.
- `402`: This tool requires a higher plan (upgrade_required). Retrying will not help.
- `429`: Tier rate/quota limit reached (rate_limited). Retry-After points at the reset.

---

[API](https://skmtc.dev/keyvex/apis/keyvex-api.md) · [All operations](https://skmtc.dev/keyvex/apis/keyvex-api/llms.txt) · [OpenAPI document](https://skmtc.dev/keyvex/apis/keyvex-api/revisions/01c0210c19cd?raw)