# CFTC COT Futures Positioning Scraper (Commitments of Traders) (`scrapers_lat/cftc-cot-futures-positioning-scraper`) Actor

Weekly CFTC Commitments of Traders positioning by trader category: legacy, disaggregated and financial futures. Long, short, net, weekly change and % of open interest per market. Export to JSON, CSV or Excel.

- **URL**: https://apify.com/scrapers\_lat/cftc-cot-futures-positioning-scraper.md
- **Developed by:** [Scrapers Lat](https://apify.com/scrapers_lat) (community)
- **Categories:** Developer tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $11.34 / 1,000 positioning records

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

[![CFTC COT Futures Positioning Scraper](https://scrapers.lat/banners/cftc-cot-futures-positioning-scraper.png)](https://console.apify.com/actors/zTMwi6inkt8JOaTYl/input)

## CFTC COT Futures Positioning Scraper (Commitments of Traders)

Here is one real result, with every field the actor returns:

```json
{
  "reportType": "legacy",
  "reportTypeLabel": "Legacy Futures-Only",
  "marketName": "GOLD - COMMODITY EXCHANGE INC.",
  "contractMarketName": "GOLD",
  "exchange": "COMMODITY EXCHANGE INC.",
  "commodity": "GOLD",
  "commodityGroup": "NATURAL RESOURCES",
  "commoditySubgroup": "PRECIOUS METALS",
  "contractCode": "088691",
  "reportDate": "2026-08-11",
  "reportWeek": "2026 Report Week 32",
  "contractUnits": "(CONTRACTS OF 100 TROY OUNCES)",
  "futuresOnlyOrCombined": "FutOnly",
  "openInterest": 400309,
  "changeInOpenInterest": 28758,
  "totalTraders": 297,
  "primaryCategory": "Non-Commercial",
  "primaryLong": 250936,
  "primaryShort": 32996,
  "primaryNet": 217940,
  "primaryChangeLong": 23923,
  "primaryChangeShort": 3617,
  "primaryChangeNet": 20306,
  "primaryPctOfOiLong": 62.7,
  "primaryPctOfOiShort": 8.2,
  "pctLongOfOI": 62.69,
  "nonCommercialLong": 250936,
  "nonCommercialShort": 32996,
  "nonCommercialSpread": 28937,
  "netNonCommercial": 217940,
  "changeNonCommercialLong": 23923,
  "changeNonCommercialShort": 3617,
  "changeNetNonCommercial": 20306,
  "pctOiNonCommercialLong": 62.7,
  "pctOiNonCommercialShort": 8.2,
  "commercialLong": 69385,
  "commercialShort": 322025,
  "netCommercial": -252640,
  "changeCommercialLong": -2447,
  "changeCommercialShort": 23702,
  "pctOiCommercialLong": 17.3,
  "pctOiCommercialShort": 80.4,
  "totalReportableLong": 349258,
  "totalReportableShort": 383958,
  "nonReportableLong": 51051,
  "nonReportableShort": 16351,
  "netNonReportable": 34700,
  "aiBias": null,
  "aiExtremeness": null,
  "aiInterpretation": null,
  "source": "CFTC Commitments of Traders (COT)",
  "observedAt": "2026-08-21T02:25:16.778Z",
  "error": null
}
```

The most complete CFTC Commitments of Traders scraper available. It returns every trader-category position the weekly COT reports expose (long, short, spreading, weekly change and percent of open interest), plus derived fields such as net positions per category, net weekly change and long-as-percent-of-open-interest, and gives you filters for report type, market name, contract code, date range and latest week only so you get exactly the market-weeks you need across the Legacy, Disaggregated and Traders in Financial Futures reports.

**[Input](https://apify.com/scrapers_lat/cftc-cot-futures-positioning-scraper/input-schema) · [Output](https://apify.com/scrapers_lat/cftc-cot-futures-positioning-scraper/output-schema) · [Pricing](https://apify.com/scrapers_lat/cftc-cot-futures-positioning-scraper/pricing) · [Examples](https://apify.com/scrapers_lat/cftc-cot-futures-positioning-scraper/examples)**

![Platform](https://img.shields.io/badge/platform-Apify-blue) ![Coverage](https://img.shields.io/badge/coverage-US%20futures%20%26%20options-green) ![Output](https://img.shields.io/badge/output-JSON%20%7C%20CSV%20%7C%20Excel-orange) ![Billing](https://img.shields.io/badge/billing-pay%20per%20result-brightgreen)

### Table of contents

- [What it does](#what-it-does)
- [Quickstart](#quickstart)
- [Input reference](#input-reference)
- [Output reference](#output-reference)
- [Example output record](#example-output-record)
- [Run via API and CLI](#run-via-api-and-cli)
- [Fetch results](#fetch-results)
- [Billing and limits](#billing-and-limits)
- [FAQ and troubleshooting](#faq-and-troubleshooting)
- [More scrapers at scrapers.lat](#more-scrapers-at-scraperslat)

### What it does

This actor returns weekly CFTC Commitments of Traders (COT) positioning data, one clean record per market and report week. It covers three report families and lets the input pick which one:

- **Legacy Futures-Only** splits every market into Non-Commercial (large speculators), Commercial (hedgers) and Non-Reportable (small traders).
- **Disaggregated Futures-Only** breaks physical-commodity markets into Producer/Merchant/Processor/User, Swap Dealers, Managed Money and Other Reportables.
- **Traders in Financial Futures (TFF)** breaks financial markets into Dealer/Intermediary, Asset Manager/Institutional, Leveraged Funds and Other Reportables.

For each market-week you get open interest and its weekly change, the number of reporting traders, and for every trader category the long, short, net, weekly change and percent of open interest. Derived fields include net positions per category, net weekly change and long as a percent of open interest, so you can spot crowded or stretched positioning without post-processing.

### Quickstart

Latest week for a single market in the Legacy report:

```json
{
  "reportType": "legacy",
  "market": "GOLD",
  "latestOnly": true,
  "maxResults": 3
}
```

Managed Money positioning in crude oil from the Disaggregated report:

```json
{
  "reportType": "disaggregated",
  "market": "CRUDE OIL",
  "latestOnly": true,
  "maxResults": 5
}
```

A history of weekly reports for one market using a date range:

```json
{
  "reportType": "tff",
  "market": "EURO FX",
  "reportDateFrom": "2025-01-01",
  "reportDateTo": "2026-08-31",
  "latestOnly": false,
  "maxResults": 100
}
```

### Input reference

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `reportType` | string (enum) | no | Which COT report to read: `legacy`, `disaggregated` or `tff`. Default `legacy`. | `legacy` |
| `market` | string | no | Case-insensitive substring match on the market and exchange name. Leave empty for every market. | `GOLD` |
| `contractCode` | string | no | Exact CFTC contract market code for a precise single-market pull. | `088691` |
| `reportDateFrom` | string | no | Earliest report week to include (YYYY-MM-DD). | `2025-01-01` |
| `reportDateTo` | string | no | Latest report week to include (YYYY-MM-DD). | `2026-08-31` |
| `latestOnly` | boolean | no | Return only the most recent report week for the matching markets. Default true. | `true` |
| `includeAiSignal` | boolean | no | Opt-in add-on. Adds an AI read of each market's speculative net position. Paid plans only. | `false` |
| `maxResults` | integer | no | Maximum records to return. Free plans are capped at 10. | `10` |

### Output reference

| Name | Type | Description |
| --- | --- | --- |
| `reportType` | string | Report family: legacy, disaggregated or tff |
| `reportTypeLabel` | string | Human label for the report family |
| `marketName` | string | CFTC market and exchange name |
| `contractMarketName` | string | Short contract market name |
| `exchange` | string | Exchange the contract trades on |
| `commodity` | string | Commodity name |
| `commodityGroup` | string | Commodity group |
| `commoditySubgroup` | string | Commodity subgroup |
| `contractCode` | string | CFTC contract market code |
| `reportDate` | string | Report week date (YYYY-MM-DD) |
| `reportWeek` | string | Report week label |
| `contractUnits` | string | Units of the underlying contract |
| `futuresOnlyOrCombined` | string | Futures-only or futures plus options combined |
| `openInterest` | number | Total open interest |
| `changeInOpenInterest` | number | Weekly change in open interest |
| `totalTraders` | number | Number of reporting traders |
| `primaryCategory` | string | Main speculative category for the report type |
| `primaryLong` / `primaryShort` / `primaryNet` | number | Primary category long, short and net |
| `primaryChangeLong` / `primaryChangeShort` / `primaryChangeNet` | number | Weekly change in primary long, short and net |
| `primaryPctOfOiLong` / `primaryPctOfOiShort` | number | Primary long and short as reported percent of open interest |
| `pctLongOfOI` | number | Derived: primary long divided by open interest, percent |
| `nonCommercialLong` / `nonCommercialShort` / `nonCommercialSpread` / `netNonCommercial` | number | Legacy: non-commercial positions |
| `changeNonCommercialLong` / `changeNonCommercialShort` / `changeNetNonCommercial` | number | Legacy: weekly change in non-commercial |
| `pctOiNonCommercialLong` / `pctOiNonCommercialShort` | number | Legacy: non-commercial percent of open interest |
| `commercialLong` / `commercialShort` / `netCommercial` | number | Legacy: commercial positions |
| `changeCommercialLong` / `changeCommercialShort` | number | Legacy: weekly change in commercial |
| `pctOiCommercialLong` / `pctOiCommercialShort` | number | Legacy: commercial percent of open interest |
| `totalReportableLong` / `totalReportableShort` | number | Legacy: total reportable positions |
| `producerMerchantLong` / `producerMerchantShort` / `netProducerMerchant` | number | Disaggregated: producer/merchant/processor/user |
| `swapDealerLong` / `swapDealerShort` / `netSwapDealer` | number | Disaggregated: swap dealers |
| `managedMoneyLong` / `managedMoneyShort` / `netManagedMoney` | number | Disaggregated: managed money |
| `changeManagedMoneyLong` / `changeManagedMoneyShort` / `changeNetManagedMoney` | number | Disaggregated: weekly change in managed money |
| `pctOiManagedMoneyLong` / `pctOiManagedMoneyShort` | number | Disaggregated: managed money percent of open interest |
| `dealerLong` / `dealerShort` / `netDealer` | number | TFF: dealer/intermediary |
| `assetManagerLong` / `assetManagerShort` / `netAssetManager` | number | TFF: asset manager/institutional |
| `leveragedFundsLong` / `leveragedFundsShort` / `netLeveragedFunds` | number | TFF: leveraged funds |
| `changeLeveragedFundsLong` / `changeLeveragedFundsShort` / `changeNetLeveragedFunds` | number | TFF: weekly change in leveraged funds |
| `pctOiLeveragedFundsLong` / `pctOiLeveragedFundsShort` | number | TFF: leveraged funds percent of open interest |
| `otherReportableLong` / `otherReportableShort` / `netOtherReportable` | number | Other reportables (disaggregated and tff) |
| `nonReportableLong` / `nonReportableShort` / `netNonReportable` | number | Non-reportable (small traders) |
| `aiBias` / `aiExtremeness` / `aiInterpretation` | string | AI positioning signal (add-on only) |
| `source` | string | Data source |
| `observedAt` | string | When the record was scraped |
| `error` | string | Error message, if any |

Fields that do not apply to the chosen report type are returned as null so the column layout stays consistent.

### Example output record

A real Managed Money record from the Disaggregated report:

```json
{
  "reportType": "disaggregated",
  "marketName": "CRUDE OIL, LIGHT SWEET-WTI - ICE FUTURES EUROPE",
  "reportDate": "2026-08-11",
  "openInterest": 797158,
  "primaryCategory": "Managed Money",
  "managedMoneyLong": 15527,
  "managedMoneyShort": 23963,
  "netManagedMoney": -8436,
  "changeNetManagedMoney": -1346,
  "netSwapDealer": -77668,
  "netProducerMerchant": 81931,
  "pctLongOfOI": 1.95
}
```

### Run via API and CLI

Start a run with the Apify API:

```bash
curl -X POST "https://api.apify.com/v2/acts/scrapers_lat~cftc-cot-futures-positioning-scraper/runs?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reportType":"legacy","market":"E-MINI S&P","latestOnly":true,"maxResults":5}'
```

Or with the Apify CLI:

```bash
apify call scrapers_lat/cftc-cot-futures-positioning-scraper \
  --input '{"reportType":"disaggregated","market":"CRUDE OIL","latestOnly":true,"maxResults":5}'
```

### Fetch results

Read the dataset items from a finished run:

```bash
curl "https://api.apify.com/v2/actor-runs/RUN_ID/dataset/items?token=YOUR_TOKEN&format=json"
```

Swap `format=json` for `format=csv` or `format=xlsx` to export to CSV or Excel.

### Billing and limits

- Pay per result. You are charged for each positioning record returned, never for empty or failed runs.
- Events: a one-time actor start, a `result` event per market-week record, and an opt-in `ai_positioning_signal` add-on billed only when a usable AI signal is produced.
- The AI add-on is disabled for free Apify plans and never charges when the model returns nothing usable.
- Free Apify plans are capped at 10 records per run. Paid plans can raise `maxResults`.
- A configured spend limit is respected: once reached, the run stops emitting billable records.
- If no market matches your filters, the actor returns a single non-billable row describing the mismatch.

### FAQ and troubleshooting

**Which report should I use?** Use `legacy` for a broad speculator-versus-hedger split on any market, `disaggregated` for detailed physical-commodity categories (managed money, swaps, producers), and `tff` for financial futures (leveraged funds, asset managers, dealers).

**How do I target one exact market?** Pass `contractCode` (for example `088691` for gold). A `market` substring like `GOLD` can match several related contracts.

**How do I get history instead of the latest week?** Set `latestOnly` to false and provide `reportDateFrom` and `reportDateTo`, or just a date range.

**How fresh is the data?** COT reports are published weekly by the CFTC. Each record carries its `reportDate` and `reportWeek` so you always know the exact week.

**No records came back.** Check the `market` spelling or try a broader substring, confirm the `reportType` covers that market, and widen or remove the date range.

### More scrapers at scrapers.lat

Explore the full catalog of finance, market and compliance scrapers at [scrapers.lat](https://scrapers.lat).

This actor is not affiliated with, endorsed by, or sponsored by the CFTC. It returns public data for research and analysis.

# Actor input Schema

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

Which CFTC Commitments of Traders report to read. legacy = Non-Commercial vs Commercial (all markets). disaggregated = Producer/Merchant, Swap Dealers, Managed Money, Other Reportables (physical commodities). tff = Traders in Financial Futures: Dealer, Asset Manager, Leveraged Funds, Other (financial markets).

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

Case-insensitive substring match on the CFTC market and exchange name, for example "GOLD", "CRUDE OIL", "E-MINI S\&P", "EURO FX", "WHEAT". Leave empty to include every market in the report.

## `contractCode` (type: `string`):

Exact CFTC contract market code to match, for example 088691 (gold) or 13874A (E-mini S\&P 500). Use this for a precise single-market pull instead of a name substring.

## `reportDateFrom` (type: `string`):

Earliest report week to include (YYYY-MM-DD). Setting a date range turns off Latest Only unless you keep it checked. Leave empty for no lower bound.

## `reportDateTo` (type: `string`):

Latest report week to include (YYYY-MM-DD). Leave empty for the most recent available report.

## `latestOnly` (type: `boolean`):

Return only the single most recent report week for the matching markets. On by default. Turn off (or set a date range) to pull historical weeks.

## `includeAiSignal` (type: `boolean`):

Add an AI read of each market's speculative net position: bias (bullish/bearish/neutral), extremeness, and a one-sentence interpretation from the net position and its weekly change. Opt-in add-on, billed per record only when a usable signal is produced. Available to paid Apify plans.

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

Maximum number of market-week positioning records to return in one run. Free Apify plans are capped at 10.

## Actor input object example

```json
{
  "reportType": "legacy",
  "market": "GOLD",
  "contractCode": "088691",
  "reportDateFrom": "2025-01-01",
  "reportDateTo": "2026-08-31",
  "latestOnly": true,
  "includeAiSignal": false,
  "maxResults": 10
}
```

# 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 = {
    "maxResults": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("scrapers_lat/cftc-cot-futures-positioning-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 = { "maxResults": 10 }

# Run the Actor and wait for it to finish
run = client.actor("scrapers_lat/cftc-cot-futures-positioning-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 '{
  "maxResults": 10
}' |
apify call scrapers_lat/cftc-cot-futures-positioning-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,scrapers_lat/cftc-cot-futures-positioning-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/zTMwi6inkt8JOaTYl/builds/XYoC7dsGY2KH0daSH/openapi.json