# CFTC Commitments of Traders (COT) Report Scraper (`devilscrapes/cftc-commitments-of-traders-scraper`) Actor

Pull the CFTC's weekly Commitments of Traders reports straight from its public Socrata data portal — trader positioning across agricultural, metals, energy, currency, and financial futures markets. Filter by report type, commodity, market, and date range. No API key required.

- **URL**: https://apify.com/devilscrapes/cftc-commitments-of-traders-scraper.md
- **Developed by:** [DevilScrapes](https://apify.com/devilscrapes) (community)
- **Categories:** Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

<div align="center">
  <img src=".actor/icon.svg" width="160" alt="Devil Scrapes mark" />

## CFTC Commitments of Traders (COT) Report Scraper

**💰 $3.20 / 1 000 rows**  ·  pay only for results  ·  no credit card to try

*We do the dirty work so your dataset stays clean.* 😈

Pull the CFTC's weekly Commitments of Traders reports straight from its public Socrata data portal — trader positioning across agricultural, metals, energy, currency, and financial futures markets. Filter by report type, commodity, market, and date range. No API key required.

</div>

***

### 🎯 What this scrapes

The CFTC publishes a Commitments of Traders (COT) report every Friday, breaking down who holds what in the futures and options markets it regulates: wheat, corn, soybeans, gold, silver, copper, crude oil, natural gas, currencies, interest-rate futures, and equity indices. Traders read it every week to see how speculators are positioned against commercial hedgers. This Actor is a direct client for the CFTC's own public Socrata open-data portal (`publicreporting.cftc.gov`) — the same backend behind the CFTC's own COT visualizations — across all 6 published report-type datasets (Legacy / Disaggregated / Traders-in-Financial-Futures, each in Futures-Only and Futures-&-Options-Combined variants). Give it a report type, an optional commodity or market filter, and a date range, and it returns one clean row per market/report-date combination instead of a Socrata query string you'd otherwise have to hand-build yourself.

### 🔥 What we handle for you

- 🗂️ **All 6 COT datasets in one Actor** — Legacy, Disaggregated, and Traders in Financial Futures, each in Futures-Only or Futures-&-Options-Combined form, selectable by a single `reportType` field.
- 🔍 **Commodity and market filters** — narrow to `WHEAT`, `GOLD`, `CRUDE OIL`, or a specific exchange without hand-writing a Socrata `$where` clause.
- 📅 **Date-range control** — pull one week's report or backfill years of history; the underlying dataset goes back decades per report type.
- 🔢 **Numeric fields normalized** — open interest, long/short positions, and week-over-week changes arrive as numbers, not the raw JSON strings the source API returns.
- 🧊 **Clean, typed dataset rows** — Pydantic-validated, ISO date strings, stable Socrata row ids, JSON / CSV / Excel export straight from the Apify Console.
- 💰 **Pay-Per-Event pricing** — you only pay for results that hit your dataset. No data, no charge.

### 💡 Use cases

- Futures trading desks — track how speculators vs. commercials are positioned week over week for a watchlist of commodities.
- Quant research — backfill years of positioning history per market to build sentiment or crowding indicators.
- Commodity market newsletters — pull the latest report every Friday and auto-generate a positioning summary.
- Risk/compliance teams — monitor open interest and concentration in specific contracts over time.

### ⚙️ How to use it

1. Click **Try for free** at the top of the page.
2. Fill in the input form — most fields have sensible defaults.
3. Click **Start**. Output streams into the run's dataset.
4. Export from **Storage → Dataset** as JSON, CSV, or Excel — or fetch via the API.

### 📥 Input

| Field | Type | Required | Default | Notes |
|---|---|:--:|---|---|
| `reportType` | `string` | no | 'legacy\_futures\_only' | Which of the CFTC's 6 Commitments of Traders datasets to query (Socrata dataset id shown in parens). |
| `commodity` | `string` | no | 'WHEAT' | Optional filter on <code>commodity\_name</code> (e.g. WHEAT, GOLD, CRUDE OIL, NATURAL GAS). Omitted = all commodities. |
| `market` | `string` | no | 'CHICAGO BOARD OF TRADE' | Optional substring filter on <code>market\_and\_exchange\_names</code> (e.g. CHICAGO BOARD OF TRADE, COMMODITY EXCHANGE… |
| `dateFrom` | `string` | no | '2026-06-30' | Inclusive lower bound on <code>report\_date\_as\_yyyy\_mm\_dd</code> (YYYY-MM-DD). |
| `dateTo` | `string` | no | '2026-09-15' | Inclusive upper bound on <code>report\_date\_as\_yyyy\_mm\_dd</code> (YYYY-MM-DD). |
| `maxResults` | `integer` | no | 500 | Maximum rows returned per run (1-5000). |
| `proxyConfiguration` | `object` | no | {'useApifyProxy': False} | Apify Proxy configuration. Default is a direct connection — the CFTC's Socrata portal is a public, keyless open-data… |

#### Example input

```json
{
  "reportType": "legacy_futures_only",
  "commodity": "WHEAT",
  "market": "CHICAGO BOARD OF TRADE",
  "dateFrom": "2026-06-01",
  "dateTo": "2026-09-15",
  "maxResults": 3,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

### 📤 Output

Every row is one dataset item.

| Field | Type | Notes |
|---|---|---|
| `id` | `string` | Socrata row id for this report row. |
| `report_type` | `string` | Which of the 6 report-type datasets this row came from (mirrors the `reportType` input). |
| `market_and_exchange_names` | `string` | Full market and exchange name as published by the CFTC. |
| `report_date_as_yyyy_mm_dd` | `string` | Report date (ISO `YYYY-MM-DD`). |
| `commodity_name` | `string` | Commodity name as published by the CFTC. |
| `cftc_contract_market_code` | `string` | CFTC's internal contract market code for this market. |
| `open_interest_all` | `number` | Total open interest across all trader categories. |
| `change_in_open_interest_all` | `number` | Week-over-week change in open interest. |
| `traders_tot_all` | `number` | Total number of traders reported for this market on this date. |
| `noncomm_positions_long_all` | `number` | Non-commercial (speculator) long positions. Populated for Legacy report types only. |
| `noncomm_positions_short_all` | `number` | Non-commercial (speculator) short positions. Populated for Legacy report types only. |
| `comm_positions_long_all` | `number` | Commercial (hedger) long positions. Populated for Legacy report types only. |
| `comm_positions_short_all` | `number` | Commercial (hedger) short positions. Populated for Legacy report types only. |
| `prod_merc_positions_long` | `number` | Producer/merchant/processor/user long positions. Populated for Disaggregated report types only. |
| `prod_merc_positions_short` | `number` | Producer/merchant/processor/user short positions. Populated for Disaggregated report types only. |
| `swap_positions_long_all` | `number` | Swap dealer long positions. Populated for Disaggregated report types only. |
| `swap_positions_short_all` | `number` | Swap dealer short positions. Populated for Disaggregated report types only. |
| `m_money_positions_long_all` | `number` | Managed money long positions. Populated for Disaggregated report types only. |
| `m_money_positions_short_all` | `number` | Managed money short positions. Populated for Disaggregated report types only. |
| `dealer_positions_long_all` | `number` | Dealer/intermediary long positions. Populated for TFF report types only. |
| `dealer_positions_short_all` | `number` | Dealer/intermediary short positions. Populated for TFF report types only. |
| `asset_mgr_positions_long` | `number` | Asset manager/institutional long positions. Populated for TFF report types only. |
| `asset_mgr_positions_short` | `number` | Asset manager/institutional short positions. Populated for TFF report types only. |
| `lev_money_positions_long` | `number` | Leveraged funds long positions. Populated for TFF report types only. |
| `lev_money_positions_short` | `number` | Leveraged funds short positions. Populated for TFF report types only. |
| `other_rept_positions_long` | `number` | Other-reportables long positions. Populated for Disaggregated and TFF report types only. |
| `other_rept_positions_short` | `number` | Other-reportables short positions. Populated for Disaggregated and TFF report types only. |

#### Example output

```json
{
  "id": "row-6dca-aqww-example",
  "report_type": "legacy_futures_only",
  "market_and_exchange_names": "WHEAT-SRW - CHICAGO BOARD OF TRADE",
  "report_date_as_yyyy_mm_dd": "2026-09-15",
  "commodity_name": "WHEAT",
  "cftc_contract_market_code": "001602",
  "open_interest_all": 412873,
  "change_in_open_interest_all": -3211,
  "traders_tot_all": 487,
  "noncomm_positions_long_all": 98123,
  "noncomm_positions_short_all": 134502,
  "comm_positions_long_all": 251340,
  "comm_positions_short_all": 198211
}
```

### 💰 Pricing

Pay-Per-Event — you pay only when these events fire:

| Event | USD | What it is |
|---|---:|---|
| `actor-start` | $0.2 | One-off warm-up charge per run |
| `result` | $0.003 | Per dataset item |

Example: 1 000 rows at the rates above ≈ **$3.20**. No subscription, no minimum, no card to start — Apify gives every new account $5 of free credit.

### 🚧 Limitations

- Report coverage, publication cadence (weekly, Fridays, for the prior Tuesday), and historical depth are set entirely by the CFTC — this Actor mirrors what the source publishes, nothing more.
- `commodity` and `market` are server-side text filters against the CFTC's own field values; if a market's name doesn't match your filter text, use a broader term or leave it unset.
- This Actor returns the structured COT report rows only — it does not compute derived indicators (e.g. net-positioning z-scores); that's a downstream analysis step.

### ❓ FAQ

**Do I need a CFTC or Socrata API key?**

No. The CFTC's public reporting portal is a keyless, public open-data API — this Actor doesn't require any credentials.

**Which report type should I pick?**

`legacy_futures_only` is the classic COT report most traders reference first. Switch to `disaggregated_*` for physical-commodity markets broken into producer/merchant, swap dealer, managed money, and other-reportable categories, or `tff_*` for financial futures (rates, currencies, equity indices) broken into dealer, asset manager, leveraged funds, and other-reportable categories.

**How far back does the data go?**

Each of the 6 datasets covers a different historical range published directly by the CFTC — some back to the late 1990s/2000s. Leave `dateFrom`/`dateTo` unset to pull the widest available window (subject to `maxResults`).

**What happens if my filter combination matches nothing?**

The run succeeds with zero rows and a status message describing exactly what was searched — you're never charged for rows that don't exist.

### 💬 Your feedback

Spotted a bug, hit a weird edge case, or need a new field? Open an
issue on the Actor's **Issues** tab on Apify Console — we ship
fixes weekly and we read every report.

***

<div align="center">

Built by **[Devil Scrapes](https://apify.com/DevilScrapes)** 😈 — a small fleet of
opinionated public-data Actors. Honest pricing, real engineering, zero fine print.

</div>

# Changelog

This Actor's version history is a separate document: https://apify.com/devilscrapes/cftc-commitments-of-traders-scraper/changelog.md

# Actor input Schema

## `reportType` (type: `string`):

Which of the CFTC's 6 Commitments of Traders datasets to query (Socrata dataset id shown in parens).

## `commodity` (type: `string`):

Optional filter on <code>commodity\_name</code> (e.g. WHEAT, GOLD, CRUDE OIL, NATURAL GAS). Omitted = all commodities.

## `market` (type: `string`):

Optional substring filter on <code>market\_and\_exchange\_names</code> (e.g. CHICAGO BOARD OF TRADE, COMMODITY EXCHANGE INC.). Omitted = all markets.

## `dateFrom` (type: `string`):

Inclusive lower bound on <code>report\_date\_as\_yyyy\_mm\_dd</code> (YYYY-MM-DD).

## `dateTo` (type: `string`):

Inclusive upper bound on <code>report\_date\_as\_yyyy\_mm\_dd</code> (YYYY-MM-DD).

## `maxResults` (type: `integer`):

Maximum rows returned per run (1-5000).

## `proxyConfiguration` (type: `object`):

Apify Proxy configuration. Default is a direct connection — the CFTC's Socrata portal is a public, keyless open-data API with no TLS-level anti-bot signal.

## Actor input object example

```json
{
  "reportType": "legacy_futures_only",
  "commodity": "WHEAT",
  "market": "CHICAGO BOARD OF TRADE",
  "dateFrom": "2026-06-30",
  "dateTo": "2026-09-15",
  "maxResults": 100,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `datasetItems` (type: `string`):

All dataset items as JSON.

## `datasetItemsCsv` (type: `string`):

Same data exported to CSV.

## `datasetView` (type: `string`):

Open the run dataset in the Console.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "reportType": "legacy_futures_only",
    "commodity": "WHEAT",
    "market": "CHICAGO BOARD OF TRADE",
    "dateFrom": "2026-06-30",
    "dateTo": "2026-09-15",
    "maxResults": 100
};

// Run the Actor and wait for it to finish
const run = await client.actor("devilscrapes/cftc-commitments-of-traders-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "reportType": "legacy_futures_only",
    "commodity": "WHEAT",
    "market": "CHICAGO BOARD OF TRADE",
    "dateFrom": "2026-06-30",
    "dateTo": "2026-09-15",
    "maxResults": 100,
}

# Run the Actor and wait for it to finish
run = client.actor("devilscrapes/cftc-commitments-of-traders-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "reportType": "legacy_futures_only",
  "commodity": "WHEAT",
  "market": "CHICAGO BOARD OF TRADE",
  "dateFrom": "2026-06-30",
  "dateTo": "2026-09-15",
  "maxResults": 100
}' |
apify call devilscrapes/cftc-commitments-of-traders-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,devilscrapes/cftc-commitments-of-traders-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/BEP9iiaG753KEY10B/builds/oaq7hMLfc9JuxI10u/openapi.json