futures_get_positioning

Weekly COT positioning for one market, newest first, with derived values.

The result is the shared envelope. data holds the market identity (market, cftc_contract_market_code, name, exchange) plus the echoed report_variant/category filters and the bounded weeks page. Each week has report_date (the Tuesday the CFTC observed), market-level open_interest and change_open_interest, and a categories list with per-category positions_long, positions_short, positions_spread (null where CFTC publishes no spreading category, including nonreportable and Disaggregated producer_merchant_processor_user), week-over-week change_* fields (null on the first report week), and two derived values you should read rather than compute: net_position (long − short; positive = net long) and net_position_pctile_52w (where this week's net position ranks among the trailing 52 weekly reports, 0 = most short, 100 = most long; null until a full 52-week window exists). All position values are contract counts (meta.units = "contracts"); values are exact decimals serialized as JSON strings. meta holds source ("cftc") and as_of (freshest ingestion on the page); pagination holds the cursor paging state.

To page, pass pagination.next_cursor back as cursor; when pagination.has_more is false you have reached the oldest report week we hold. CFTC COT data is US government work in the public domain.

Errors carry a machine code: unknown_entity for a market key we do not hold (with Did you mean: …? suggestions — or call futures_search_markets), and bad_parameter for a category invalid for the market's report family, a malformed cursor, or an out-of-range limit.

Example: futures_get_positioning(market="wti_crude", category="managed_money", limit=52).