CFTC Commitments of Traders Reports

Download and normalize official CFTC Commitments of Traders reports into dated market and trader-category position rows.

The Actor reads CFTC Public Reporting datasets directly, supports current and historical reports, and returns analysis-ready long, short, spread, net, open-interest, percentage, trader-count, and week-over-week change fields.

What does this Actor do?

CFTC COT reports are wide market-level tables whose category names differ across report families.

This Actor turns those reports into a consistent long-form dataset:

• one item per report date;
• one market or contract;
• one normalized trader category;
• comparable position and weekly-change fields;
• an official CFTC source identifier and URL.

You can use the output directly in spreadsheets, notebooks, warehouses, dashboards, or scheduled market-monitoring workflows.

Who is it for?

• Commodity analysts refreshing weekly positioning dashboards.
• Futures traders comparing managed-money or commercial exposure.
• Macro researchers following leveraged funds and asset managers.
• Risk teams tracking large changes in net positions and open interest.
• Data engineers maintaining a dated CFTC position history.
• Journalists and researchers who need source-backed COT observations.

Why use this Actor?

The Actor uses the official anonymous CFTC Public Reporting API rather than scraping rendered pages.

That provides:

• current and historical source records;
• deterministic report-date ordering;
• six report family and futures/combined variants;
• exact contract-code filtering;
• bounded pagination and retries;
• normalized category names across changing source schemas;
• no login, browser, or proxy requirement.

It does not calculate investment signals, forecasts, percentiles, or trading recommendations.

Supported CFTC report types

Input value	Official report
legacy_futures_only	Legacy, futures only
legacy_combined	Legacy, futures and options combined
disaggregated_futures_only	Disaggregated, futures only
disaggregated_combined	Disaggregated, futures and options combined
traders_in_financial_futures_futures_only	Traders in Financial Futures, futures only
traders_in_financial_futures_combined	Traders in Financial Futures, futures and options combined

You may select more than one report type in a run.

Trader categories

Legacy reports expose:

• noncommercial
• commercial
• nonreportable

Disaggregated reports expose:

• producer_merchant
• swap_dealer
• managed_money
• other_reportable
• nonreportable

Traders in Financial Futures reports expose:

• dealer_intermediary
• asset_manager_institutional
• leveraged_funds
• other_reportable
• nonreportable

Category filters that do not occur in a selected family simply produce no rows for that category.

Data you can extract

Field group	Included fields
Report identity	report type, report date, source dataset, source record ID
Market identity	market name, contract name, commodity, group, exchange code, CFTC contract code
Positions	long, short, spread, and computed net positions
Weekly movement	change long, short, spread, net, and open interest
Relative positioning	long, short, and spread percentages of open interest
Participation	long, short, and spread trader counts when CFTC publishes them
Market scale	total open interest and contract units
Provenance	official source URL and extraction timestamp

Unavailable or inapplicable source values are returned as null.

How much does it cost to export CFTC COT position rows?

The Actor uses pay-per-event pricing:

• a $0.00005 one-time start event per run;
• one position event per useful dataset row.

The row rates are $0.00368 on FREE, $0.0032 on BRONZE, $0.002496 on SILVER, and $0.00192 on GOLD, PLATINUM, and DIAMOND.

At BRONZE rates, 10 rows cost about $0.03205, 100 rows about $0.32005, and 1,000 rows about $3.20005, including the start event.

Rejected, duplicate, or absent records are not charged as position rows. The Apify Console shows the applicable tier before each run.

Quick start

1. Open the Actor input page.
2. Select Disaggregated — futures only.
3. Keep Latest report only enabled.
4. Enter GOLD under Market or commodity contains.
5. Set Maximum position rows to 25.
6. Start the run.
7. Open the dataset to inspect or export the normalized rows.

Input parameters

reportTypes

Array of supported report variants.

Default: disaggregated_futures_only.

latestOnly

When true, the Actor first discovers the newest report date separately for every selected dataset and exports only that date.

When false, the Actor applies the optional historical date range.

Default: true.

fromDate

Optional inclusive lower date in YYYY-MM-DD format.

Used only when latestOnly is disabled.

toDate

Optional inclusive upper date in YYYY-MM-DD format.

Used only when latestOnly is disabled.

marketQuery

Optional case-insensitive substring filter across the CFTC market name, contract name, and commodity name.

Useful examples include GOLD, WHEAT, CRUDE OIL, and UST BOND.

contractMarketCodes

Optional exact six-digit CFTC contract market codes.

Use this when a stable source identifier is safer than a text match.

traderCategories

Optional list of normalized category keys.

Use it to return only managed money, commercials, leveraged funds, or another supported classification.

maxItems

Maximum normalized position rows across every selected report.

Allowed range: 1 to 50,000.

Default: 250.

Example input: latest gold positioning

{
  "reportTypes": ["disaggregated_futures_only"],
  "latestOnly": true,
  "marketQuery": "GOLD",
  "maxItems": 25
}

Example input: historical financial futures

{
  "reportTypes": ["traders_in_financial_futures_futures_only"],
  "latestOnly": false,
  "fromDate": "2026-07-01",
  "toDate": "2026-08-31",
  "traderCategories": [
    "dealer_intermediary",
    "asset_manager_institutional",
    "leveraged_funds"
  ],
  "maxItems": 100
}

Example output

{
  "reportType": "disaggregated_futures_only",
  "reportDate": "2026-09-01",
  "marketName": "GOLD - COMMODITY EXCHANGE INC.",
  "contractMarketName": "GOLD",
  "commodityName": "GOLD",
  "commodityGroup": "NATURAL RESOURCES",
  "exchangeCode": "CMX",
  "cftcContractMarketCode": "088691",
  "traderCategory": "managed_money",
  "traderCategoryLabel": "Managed money",
  "longPositions": 144816,
  "shortPositions": 47018,
  "spreadPositions": 33709,
  "netPositions": 97798,
  "changeLong": 5421,
  "changeShort": 1037,
  "changeNet": 4384,
  "percentOpenInterestLong": 34.9,
  "percentOpenInterestShort": 11.3,
  "openInterest": 415196,
  "changeOpenInterest": -12761,
  "sourceDatasetId": "72hh-3qpy",
  "sourceRecordId": "260901088691F",
  "sourceUrl": "https://publicreporting.cftc.gov/resource/72hh-3qpy.json?id=260901088691F"
}

Values above illustrate the current output shape. CFTC values change with each weekly report.

Understanding net and weekly changes

netPositions is computed as long positions minus short positions for the same report row and category.

changeNet is computed as the CFTC-reported weekly long change minus the CFTC-reported weekly short change.

A positive number means the category became more net long, or less net short, during the reporting week. It is not a prediction.

Current versus historical runs

Use latestOnly: true for scheduled weekly refreshes and small current snapshots.

Use latestOnly: false with dates to build a historical panel.

Historical output is ordered from newest dates to oldest dates. The maxItems limit applies after market and category filters, so it bounds saved rows rather than raw upstream records.

Export and integration workflows

Common patterns include:

• schedule a weekly gold, oil, or grain refresh;
• append dated rows to BigQuery, Snowflake, or S3;
• export CSV or Excel for a positioning workbook;
• trigger a webhook when a run completes;
• compare changeNet across categories in a notebook;
• join contract codes to an internal futures reference table.

The default Apify dataset supports JSON, CSV, Excel, XML, RSS, and API access.

JavaScript API example

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/cftc-commitments-of-traders-reports').call({
  reportTypes: ['disaggregated_futures_only'],
  latestOnly: true,
  marketQuery: 'WHEAT',
  traderCategories: ['managed_money'],
  maxItems: 20,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);

Python API example

from apify_client import ApifyClient

client = ApifyClient('APIFY_TOKEN')
run = client.actor('automation-lab/cftc-commitments-of-traders-reports').call(run_input={
    'reportTypes': ['legacy_futures_only'],
    'latestOnly': True,
    'marketQuery': 'CRUDE OIL',
    'maxItems': 30,
})
items = client.dataset(run['defaultDatasetId']).list_items().items
print(items)

cURL API example

curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~cftc-commitments-of-traders-reports/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reportTypes":["disaggregated_futures_only"],"latestOnly":true,"marketQuery":"GOLD","maxItems":25}'

Never commit an Apify token to source control. Use environment variables or your secret manager.

MCP integration

Add this Actor to Claude Code through the Apify MCP server:

claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/cftc-commitments-of-traders-reports"

Claude Desktop setup

Claude Desktop can use:

{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/cftc-commitments-of-traders-reports"
    }
  }
}

Cursor setup

Add the same HTTP MCP URL in Cursor under Settings → Tools & MCP.

VS Code setup

Add the same HTTP MCP URL through your VS Code MCP extension or workspace MCP configuration.

Example prompts:

• “Export the latest managed-money CFTC positions for wheat.”
• “Get July and August financial-futures leveraged-fund rows.”
• “Compare weekly net changes across the latest gold trader categories.”

Reliability and failure behavior

The Actor retries transient API failures up to three times with bounded backoff.

It fails the run when:

• a report type is unsupported;
• a date is malformed;
• the start date is after the end date;
• a contract code is not six digits;
• the official API repeatedly fails or returns an invalid response.

It does not silently substitute a third-party source.

A successful run may contain zero rows when valid filters match no official records.

Limits and data notes

• CFTC generally publishes COT reports weekly.
• The report date describes the official observation, not the extraction time.
• Category definitions differ by report family.
• Some CFTC fields are blank or inapplicable and become null.
• Source dataset IDs and field names can change upstream.
• Combined reports include futures and options on a futures-equivalent basis.
• This Actor does not provide real-time market prices.
• This Actor does not send alerts by itself; use Apify schedules and webhooks.

Responsible use and legality

The Actor accesses public United States government data from CFTC Public Reporting endpoints without authentication.

Review CFTC notices, Apify terms, and your organization’s data-governance requirements before operational use.

COT data is informational and does not constitute investment advice. Validate material trading or compliance decisions against the official CFTC publication.

Troubleshooting

Why did I get zero items?

Remove marketQuery and traderCategories, confirm the date range, and retry with one report type. A category from another report family will not match.

Why is changeNet null?

The selected category or historical source row may not include both weekly long and short changes. The Actor returns null rather than inventing a value.

Why are counts different across report types?

Each family covers different markets and participant classifications. Futures-only and combined datasets are also distinct official products.

How do I avoid duplicate weekly data?

Use sourceRecordId, traderCategory, and reportType as a composite downstream key. Scheduled runs can then upsert rather than append duplicates.

FAQ

Does this require a CFTC API key?

No. The supported official Public Reporting endpoints are anonymous.

Can it fetch historical COT data?

Yes. Disable latestOnly and set an inclusive date range.

Can I filter by a precise contract?

Yes. Supply one or more six-digit CFTC contract market codes.

Does it calculate percentiles or trading signals?

No. It normalizes official positions, percentages, trader counts, and weekly changes. Derived strategy analytics belong downstream.

Does it support every CFTC report?

It supports Legacy, Disaggregated, and Traders in Financial Futures, each in futures-only and combined form. Supplemental, concentration-only, and bank participation reports are outside this version.

Related Automation Lab Actors

Explore other public-market, commodity, and financial-data Actors from Automation Lab.

Use this Actor when the buyer job is official CFTC futures positioning, not cash grain bids, settlement prices, or general market news.

Support

When reporting a problem, include:

• the Apify run ID;
• the exact input;
• selected report type;
• expected market or contract code;
• expected report date;
• a link to the official CFTC record when available.

This makes upstream schema changes and filter mismatches easier to reproduce.