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/marketsBearer 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.
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}/latestBearer auth

Most recent report for one market.

Parameter	In	Type	Description
cftc_code *	path	string	CFTC contract market code.
family	query	string	Default legacy.

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

GET/api/v1/cot/{cftc_code}/indexBearer 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.

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

GET/api/v1/demoNo 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

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).
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.
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 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.