FREE · REST API REFERENCE

COT Data API

Bearer auth · 60 req/min · 500 req/day

REST API for the entire CFTC Commitments of Traders dataset. Available endpoints, authentication, rate limits, and error codes — everything you need to integrate.

The COT Data API exposes the same dataset that powers cot-reports.com: every CFTC market, every report family (Legacy, Disaggregated, TFF, Supplemental), normalized columns, weekly history. Subscribe to mint a token; bearer-auth every request; rate limits below.

This reference is in English only — the rest of the site is localized in 6 languages, but the API surface (endpoint names, parameter syntax, error codes) is shared across languages. Examples are in curl; the JavaScript snippets work in Node 18+ and any modern browser.

Authentication

Every request except /api/v1/demo/ requires a bearer token. Subscribe at cot-reports.com/api, mint a token from /account/api, and include it in the Authorization header.

curl -H "Authorization: Bearer cot_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  https://cot-reports.com/api/v1/markets/

Tokens are 36 characters total (cot_live_ prefix + 32 hex chars). The full token is shown to you exactly once at creation; we store only a SHA-256 hash. Lost tokens cannot be recovered — revoke the old one and mint a new one.

Rate limits

Tier	Per minute	Per day	Notes
Entry (9.99 $/mo)	60	500	Default tier on subscription.
Demo (no auth)	5	10	Per-IP. Static synthetic response.

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset for the tighter of the two windows, plus per-window keys (-Minute / -Day) for richer telemetry. On 429, Retry-After tells you seconds to wait.

Endpoints

GET/api/v1/markets/Bearer auth

List every CFTC market in the dataset, with metadata and report-family membership.

Parameter	In	Type	Description
category	query	string	Exact match against the metadata category.
tracked	query	boolean	Filter to the curated set of "popular" markets.
family	query	string	One of legacy, disagg, tff, supp.
search	query	string	Substring match on market_name (case-insensitive).
limit	query	integer (1..2000)	Default 500.
offset	query	integer	Pagination offset, default 0.

curl -H "Authorization: Bearer $COT_API_TOKEN" \
  "https://cot-reports.com/api/v1/markets/?family=legacy&tracked=true&limit=10"

GET/api/v1/cot/{cftc_code}/Bearer auth

Weekly history for one market. Default returns the last 520 weeks (10 years).

Parameter	In	Type	Description
cftc_code *	path	string	CFTC contract market code, e.g. 099741 for EURO FX.
family	query	string	Default legacy. One of legacy, disagg, tff, supp.
variant	query	futonly \| combined	CFTC variant: futonly (Futures Only) or combined (Futures & Options Combined). Default: the report's own (legacy: futonly; disagg, tff: combined; supp: combined only). When given, the response names it in a variant field.
from	query	YYYY-MM-DD	Inclusive lower bound on report_date.
to	query	YYYY-MM-DD	Inclusive upper bound on report_date.
limit	query	integer (1..5000)	Default 520.

curl -H "Authorization: Bearer $COT_API_TOKEN" \
  "https://cot-reports.com/api/v1/cot/099741/?from=2024-01-01"

GET/api/v1/cot/{cftc_code}/latest/Bearer auth

Most recent report for one market.

Parameter	In	Type	Description
cftc_code *	path	string	CFTC contract market code.
family	query	string	Default legacy.
variant	query	futonly \| combined	futonly or combined. Default: the report's own; when given, the response names it.

curl -H "Authorization: Bearer $COT_API_TOKEN" \
  "https://cot-reports.com/api/v1/cot/099741/latest/?variant=combined"

GET/api/v1/cot/{cftc_code}/index/Bearer auth

Briese-style COT Index (0–100 percentile) for the latest report against the lookback window.

Parameter	In	Type	Description
cftc_code *	path	string	CFTC contract market code.
lookback	query	integer (4..520)	Window in weeks. Default 52.
variant	query	futonly \| combined	The Legacy report's variant: futonly (default) or combined.

curl -H "Authorization: Bearer $COT_API_TOKEN" \
  "https://cot-reports.com/api/v1/cot/099741/index/?lookback=156"

GET/api/v1/demo/No auth

Static synthetic sample. No auth. 10 req/day per IP. Use to validate response shapes before subscribing.

curl https://cot-reports.com/api/v1/demo/

MCP server (AI assistants)

The COT data is also served to AI assistants through the Model Context Protocol at https://mcp.cot-reports.com. Your Data API key works there too, as a Bearer header — the same markets and report families, counted together with your REST API calls (one key, one plan: the same limits on the REST API and the MCP server). All the keys of one account share these limits, on the REST API and the MCP server together.

claude mcp add --transport http cot-reports https://mcp.cot-reports.com \
  --header "Authorization: Bearer cot_live_<32 hex>"

Set-up for every AI app

Error codes

code	HTTP	When
missing_header	401	Authorization header was not sent.
malformed_header	401	Authorization header is not Bearer + cot_live_<32 hex>.
unknown_token	401	Token does not match any active row. May have been revoked or never minted.
revoked	403	Token exists but was revoked (subscription canceled, manual revoke).
account_suspended	403	The account this token belongs to is suspended or closed. Its tokens work again when a suspension is lifted; a closed account's tokens are revoked with its subscription and do not come back if the account is restored.
rate_limited	429	Per-minute or per-day limit exceeded. Retry-After header indicates seconds to wait.
invalid_code	400	cftc_code in the path failed alphanumeric validation.
invalid_family	400	family parameter not one of legacy, disagg, tff, supp.
invalid_from	400	from query parameter is not a valid YYYY-MM-DD date.
invalid_to	400	to query parameter is not a valid YYYY-MM-DD date.
invalid_variant	400	variant parameter not one of futonly, combined.
variant_not_published	400	The CFTC does not publish that variant of the report (supp: Futures & Options Combined only).
variant_unavailable	404	That variant of the report is not available yet.
no_data	404	No history exists for the requested market in the requested family.
db_error	500	Internal database error. Retry once; if it persists, contact support.
internal	500	Unexpected server error. Retry once; if it persists, contact support.
demo_rate_limited	429	/api/v1/demo/ IP-hash limit (10/day) reached.

JavaScript example

const r = await fetch('https://cot-reports.com/api/v1/cot/099741/index/?lookback=52', {
  headers: { Authorization: `Bearer ${process.env.COT_API_TOKEN}` },
})
if (!r.ok) {
  const { error, message } = await r.json()
  throw new Error(`COT API ${r.status} ${error}: ${message}`)
}
const { cot_index, latest_report_date } = await r.json()
console.log(`COT Index for EURO FX as of ${latest_report_date}: ${cot_index}`)

OpenAPI 3.0 spec

Machine-readable description of every endpoint above. Drop into Postman, Insomnia, OpenAPI Generator, etc.

Download openapi.json

Acceptable use

One token per subscriber. Sharing tokens across users or systems beyond what your subscription covers is a Terms violation; we revoke tokens that show distributed-IP patterns.
The CFTC data itself is public domain (17 USC §105). You can build paid products on top, redistribute query results, or feed any model. We don't restrict the data semantics.
Mass scraping with the goal of recreating the Data Dump for free is forbidden — buy the Data Dump if that's your need; it's from 49 $ one-time and saves you the rate-limit dance.
Rate-limit circumvention (rotating IPs, parallel tokens to the same endpoint) is a Terms violation. We log per-token + per-IP-hash for exactly this reason.

Full terms: /terms.