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

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.

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

Query parameters

idstring

Direct doc lookup ({contract_code}-{YYYY-MM-DD}). Fastest path.

cftc_contract_market_codestring

Exact CFTC contract code (e.g., '13874A' = E-mini S&P 500, '088691' = Gold, '067651' = Crude Oil WTI).

contract_market_namestring

Case-insensitive substring on contract_market_name (e.g., 'S&P 500', 'GOLD', 'CRUDE OIL', 'JAPANESE YEN'); a needle of 3 characters or fewer matches WHOLE WORDS ('GAS' finds 'NAT GAS', not 'GASOLINE'). Applied client-side, within a bounded window.

commodity_namestring

Exact commodity name from CFTC's catalog (e.g., 'S&P 500 STOCK INDEX', 'GOLD', 'CRUDE OIL', 'EURO FX').

sincestring

Inclusive lower bound on report_date (YYYY-MM-DD).

untilstring

Inclusive upper bound on report_date (YYYY-MM-DD).

latest_onlyboolean

When true, returns only the most recent report row per contract (one row per contract instead of weekly history).

sort_by'report_date' | 'open_interest' | 'noncomm_net' | 'comm_net'

Sort key. Default: report_date. report_date, open_interest, noncomm_net, comm_net.

sort_order'asc' | 'desc'

Default: desc.

limitinteger

Max records. Default 50, max 500.

Response

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

Changes

No recorded changes to this operation across all 1 revision of this API.