Positioning

Positioning comes from the CFTC Commitments of Traders reports and is served for every registered futures family, not its continuous series (futures).

Routes

you need	route
a family's weekly positioning reports, newest first	GET /v1/futures/{root}/positioning

Every parameter and response schema is in the API reference.

curl "https://api.tauric.ai/v1/futures/XNYM:CL/positioning?reports=12" \
  -H "Authorization: Bearer $TAURIC_API_KEY"
curl "https://api.tauric.ai/v1/futures/ES/positioning?known_at=2026-10-05T00:00:00Z" \
  -H "Authorization: Bearer $TAURIC_API_KEY"

Reports and their dates

Each report is the futures-only report of one week's positions. Its period (kind calendar_day) is the report's own as-of date, normally a Tuesday, available on the Friday; in a federal-holiday week it can be another business day.

reports sets how many; page back by sending coverage.continue_end as end (pagination).

The market and its layout

market names the market as the reports define it:

• contract_market_code, the market code to match on (never the display name);
• report, the layout, which fixes the trader categories;
• scope, which is futures_only.

report	used for	trader categories
cftc_disaggregated	commodities	producer_merchant, swap_dealer, managed_money, other_reportable, nonreportable
cftc_tff (Traders in Financial Futures)	index, rate, currency, and bitcoin futures	dealer, asset_manager, leveraged_funds, other_reportable, nonreportable

Report fields

Every field is described in the API reference. To use them:

• positions are in contracts, by category; net = long − short, present only when both legs were published.
• traders counts no traders for nonreportable, so that category is absent.
• A report carries no source timestamp: use known_from, when this version of the report was first known.

Every null has its reason in the report's field_states: not_published (suppressed or undefined, or a net with an unpublished leg; never read it as 0) or not_applicable (the layout has no such column).

A report dropped from the latest publication is still served with its last published values, with field_states.period: unconfirmed.

Coverage and freshness

• coverage.in_newest_report is false when the market is absent from its layout's newest report.
• coverage.revision_window: this year's and last year's reports can still change; older ones do not.
• freshness.stale is true when the layout's next report is overdue; freshness.refreshed_at is when its newest report was last confirmed.

Point-in-time reads

Under known_at, the answer is the reports as they were held then; a revision is dated (point in time). point_in_time.complete is true when every report year from 2006 on was available at that instant. Before point_in_time.since, the answer is empty with before_point_in_time_history.

Errors

answer	when
503 temporarily_unavailable	no report is available yet for the family's layout
404 not_published	a mapped family whose market the reports held so far do not carry

Every other code is on errors.