# CFTC Commitments of Traders Reports Scraper (`parseforge/cftc-cot-reports-scraper`) Actor

Collects CFTC Commitments of Traders reports filtered by commodity name and date range. Returns each report as a flat row with long, short, and spread positions per trader category.

- **URL**: https://apify.com/parseforge/cftc-cot-reports-scraper.md
- **Developed by:** [ParseForge](https://apify.com/parseforge) (community)
- **Categories:** Developer tools, Other
- **Stats:** 1 total users, 0 monthly users, 89.7% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $19.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

[![ParseForge](https://raw.githubusercontent.com/ParseForge/apify-assets/main/banner.jpg)](https://apify.com/parseforge?fpr=vmoqkp)

### CFTC Commitments of Traders Reports Scraper

**Scrape CFTC Commitments of Traders reports by commodity and date range, up to a million per run.** Each report row includes long, short, and spread positions by trader category. Export to CSV, JSON, Excel, or XML.

The CFTC publishes weekly Commitments of Traders reports as a collection of text files, making bulk historical analysis tedious. This Actor reads the public COT data directly, filters it by commodity name and date, and returns each report in a consistent flat schema. No manual downloads or custom parsers required.

| Who uses it | What they scrape CFTC for |
|---|---|
| Commodity traders | Monitor shifts in managed money long vs short positioning for a specific futures contract. |
| Macro analysts | Aggregate positioning data across metals, energy, and grains to gauge speculative sentiment. |
| Quant researchers | Build a clean time series of legacy and disaggregated COT data for backtesting signals. |
| Risk managers | Track concentration of positions by trader category to identify potential squeeze risks. |

### What it does

This Actor collects CFTC Commitments of Traders reports filtered by commodity name and date range, and returns each one as a flat row.

- 📋 **Flat row output:** Every report is returned as one row with long, short, and spread positions per trader category, ready for analysis.
- 🔍 **Commodity filter:** Supply a substring like GOLD, CRUDE OIL, or WHEAT to collect only the contracts you care about.
- 📅 **Date range control:** Set an optional start date to pull only the most recent reports or a specific historical window.
- ⚡ **High throughput:** Collect up to a million reports in a single run, limited only by the CFTC's public archive.

Results export to CSV, JSON, Excel, or XML, or straight from the API.

### What you can do with CFTC data

**📈 Track speculative positioning.**

A commodity trader runs the Actor weekly for GOLD and CRUDE OIL to see whether managed money is adding to longs or shorts before placing a directional bet.

**📊 Build a COT sentiment index.**

A quant researcher pulls five years of disaggregated reports across a basket of currencies and grains to construct a normalized sentiment indicator for a systematic strategy.

**⚠️ Monitor concentration risk.**

A risk manager collects the latest reports for natural gas and corn to check if producer short positions are reaching extremes that historically preceded a short squeeze.

**🌍 Compare cross-asset flows.**

A macro analyst scrapes metals, energy, and equity index contracts on the same schedule to overlay positioning changes with price action and macro events.

### Why choose this scraper

|  | What you get |
|---|---|
| **No API key** | Reads the CFTC's public report archive directly, no registration or authentication needed. |
| **Consistent schema** | Every report, whether legacy or disaggregated, lands in the same flat structure for easy joins. |
| **Bulk history** | Pull years of weekly positioning data in one run instead of downloading files one by one. |
| **Flexible export** | Save results as CSV, JSON, Excel, or XML for direct use in Python, R, or a dashboard. |

### How it compares

Three other Apify actors also scrape CFTC COT data. This one focuses on a simple commodity-name filter and flat row output without requiring market codes or report-type selection.

| Feature | ParseForge | CFTC Commitments of Traders Reports Scraper | CFTC Commitments of Traders Scraper | CFTC COT Report Scraper - Futures Positioning Data |
|---|---|---|---|---|
| Commodity name substring filter | Yes | Not listed | Not listed | Yes |
| Date range filter | Yes | Not listed | Not listed | Yes |
| Legacy report format | Yes | Not listed | Not listed | Yes |
| Disaggregated report format | Yes | Not listed | Not listed | Yes |
| Financial futures report format | Yes | Not listed | Not listed | Yes |
| Market code filter | Not listed | Not listed | Not listed | Yes |

### Configure the run

Drive the Actor with a commodity name substring and an optional start date. Filters run as each report is read so only matching records reach your dataset. The Input tab lists every parameter.

A first run with the defaults:

```json
{
  "maxItems": 10,
  "commodityName": "GOLD"
}
```

A larger pull:

```json
{
  "maxItems": 200,
  "commodityName": "GOLD"
}
```

### Pricing

Pay-per-result: **$0.021 per result** collected. You pay only for the results written to your dataset.

| Results collected | Approximate cost |
|---|---|
| 100 results | $2.10 |
| 1,000 results | $21.00 |
| 10,000 results | $210.00 |

New Apify accounts start with $5 in free credit.

### Free users

Free-plan runs return up to 10 results as a preview. [Upgrade your Apify plan](https://console.apify.com/sign-up?fpr=vmoqkp) to collect up to 1,000,000 results per run.

### Run it

1. [Create a free Apify account with $5 in credit](https://console.apify.com/sign-up?fpr=vmoqkp).
2. Open the [CFTC Commitments of Traders Reports Scraper](https://apify.com/parseforge/cftc-cot-reports-scraper?fpr=vmoqkp).
3. Set your inputs and any filters, then click **Start**.
4. Export the results as CSV, Excel, JSON, or XML from the **Dataset** tab.

Run it programmatically through the [Apify API](https://docs.apify.com/api/v2) (`run-sync-get-dataset-items`) or the [ApifyClient](https://docs.apify.com/api/client/js) for JavaScript and Python.

### Use with AI agents (MCP)

Give an AI agent live access to CFTC through the Model Context Protocol. Add the Actor to Claude, Cursor, or any MCP client:

```bash
claude mcp add --transport http apify "https://mcp.apify.com/?tools=parseforge/cftc-cot-reports-scraper"
```

Then prompt it in plain language to run the scraper and read back the results.

### Troubleshooting

**Why am I getting no results?**

Check your commodityName spelling. The filter is a substring match, so GOLD will find GOLD but GLD will not. Also verify that your startDate is not set after the most recent report date.

**The run is taking a long time.**

Lower the maxItems value or set a startDate to limit the historical range. The CFTC archive is large, and pulling every report ever published will take time.

**Some fields are empty in my output.**

Not every trader category appears in every commodity report. Empty fields mean that category had no positions reported for that contract and week.

**I got an error about the date format.**

The startDate field expects YYYY-MM-DD format, for example 2024-01-15. Make sure you are using hyphens and two-digit month and day values.

**The commodity I want is not showing up.**

Try a shorter substring. For example, use CRUDE instead of CRUDE OIL, LIGHT. The CFTC contract names can be long, and a broader match may catch it.

### FAQ

| Question | Answer |
|---|---|
| What is the CFTC Commitments of Traders report? | It is a weekly publication from the U.S. Commodity Futures Trading Commission that breaks down open interest in futures and options markets by trader category, such as producers, swap dealers, managed money, and other reportables. |
| Which report types does this Actor cover? | It reads the public COT data files, which include the legacy, disaggregated, and financial futures report formats. Each is returned in a unified flat schema. |
| Can I filter by a specific commodity? | Yes. Use the commodityName input with a substring like GOLD, WHEAT, or NATURAL GAS. The filter is case-insensitive and matches any part of the contract name. |
| How far back can I get data? | The CFTC archive goes back many years. You can set a startDate to pull only recent reports or leave it empty to collect the full available history, up to the maxItems limit you set. |
| What trader categories are included? | The reports include categories such as producer/merchant, swap dealers, managed money, and other reportables, with long, short, and spread positions for each. |
| Does this include options data? | The COT reports cover futures and options combined where the CFTC publishes them. The Actor returns whatever the public file contains for the selected commodity. |
| How often is the data updated? | The CFTC releases new COT reports every Friday afternoon U.S. Eastern Time, reflecting positions as of the prior Tuesday. You can schedule the Actor to run weekly. |
| Can I get data for multiple commodities in one run? | The commodityName filter accepts one substring per run. To collect several commodities, run the Actor multiple times with different inputs or leave the filter empty to get everything. |
| What output formats are supported? | You can export the dataset as CSV, JSON, Excel, or XML from the Apify platform, or access it via the API for direct integration. |
| Do I need a CFTC account or API key? | No. The Actor reads the publicly available report files from the CFTC website, so no registration or credentials are required. |

### Related actors

Browse the full [ParseForge collection](https://apify.com/parseforge?fpr=vmoqkp) for more scrapers.

🆘 **Need help?** Email parseforge@protonmail.com with your run ID, your input, and what you expected.

⚠️ **Disclaimer.** This Actor is unofficial and is not affiliated with, endorsed by, or sponsored by U.S. Commodity Futures Trading Commission. It collects only publicly available data. You are responsible for using the collected data in compliance with the source's terms of service and applicable data-protection laws, including GDPR, CCPA, and PIPL. Do not use it to collect personal data unlawfully.

# Actor input Schema

## `maxItems` (type: `integer`):

How many COT reports to collect per run.

## `commodityName` (type: `string`):

Filter by commodity name substring (e.g. GOLD, CRUDE OIL, WHEAT).

## `startDate` (type: `string`):

Filter reports on/after this date (YYYY-MM-DD). Optional.

## Actor input object example

```json
{
  "maxItems": 10,
  "commodityName": "GOLD"
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# 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 = {
    "maxItems": 10,
    "commodityName": "GOLD"
};

// Run the Actor and wait for it to finish
const run = await client.actor("parseforge/cftc-cot-reports-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 = {
    "maxItems": 10,
    "commodityName": "GOLD",
}

# Run the Actor and wait for it to finish
run = client.actor("parseforge/cftc-cot-reports-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 '{
  "maxItems": 10,
  "commodityName": "GOLD"
}' |
apify call parseforge/cftc-cot-reports-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,parseforge/cftc-cot-reports-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/Xe9Mq37hVgqAhXfo5/builds/tDxbJX6mgF3nZVZwD/openapi.json