# CFTC Commitments of Traders Reports (`automation-lab/cftc-commitments-of-traders-reports`) Actor

Download and normalize official current or historical CFTC COT positions into dated market and trader-category rows with weekly changes.

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

## Pricing

from $1.92 / 1,000 position extracteds

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

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

### Example input: historical financial futures

```json
{
  "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

```json
{
  "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

```js
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

```python
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

```bash
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:

```bash
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:

```json
{
  "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](https://apify.com/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.

# Actor input Schema

## `reportTypes` (type: `array`):

One or more official CFTC report families and futures-only or combined variants.

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

Fetch only the newest available report date for each selected report type. Disable this to use the historical date range.

## `fromDate` (type: `string`):

Inclusive earliest report date in YYYY-MM-DD format, used when Latest report only is disabled.

## `toDate` (type: `string`):

Inclusive latest report date in YYYY-MM-DD format, used when Latest report only is disabled.

## `marketQuery` (type: `string`):

Optional case-insensitive text filter across market, contract, and commodity names, for example GOLD, WHEAT, or CRUDE OIL.

## `contractMarketCodes` (type: `array`):

Optional exact six-digit CFTC contract market codes.

## `traderCategories` (type: `array`):

Optional normalized category keys. Available keys depend on the selected report family.

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

Maximum normalized market-and-trader-category rows saved across all selected report types.

## Actor input object example

```json
{
  "reportTypes": [
    "disaggregated_futures_only"
  ],
  "latestOnly": true,
  "marketQuery": "GOLD",
  "maxItems": 20
}
```

# Actor output Schema

## `overview` (type: `string`):

Open the normalized CFTC Commitments of Traders dataset overview.

# 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 = {
    "reportTypes": [
        "disaggregated_futures_only"
    ],
    "latestOnly": true,
    "marketQuery": "GOLD",
    "maxItems": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/cftc-commitments-of-traders-reports").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 = {
    "reportTypes": ["disaggregated_futures_only"],
    "latestOnly": True,
    "marketQuery": "GOLD",
    "maxItems": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/cftc-commitments-of-traders-reports").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 '{
  "reportTypes": [
    "disaggregated_futures_only"
  ],
  "latestOnly": true,
  "marketQuery": "GOLD",
  "maxItems": 20
}' |
apify call automation-lab/cftc-commitments-of-traders-reports --silent --output-dataset

```

## MCP server setup

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

```

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/s3Q14OzL9oY6IYU86/builds/EZRVxgFSKGx76bPHs/openapi.json