# CFTC Commitments of Traders: Weekly Net Positions by Market (`accountable_eel/cftc-commitments-of-traders-lookup`) Actor

CFTC Commitments of Traders (COT) Disaggregated data for futures markets: weekly net positions for managed money, producers, swap dealers, and open interest. Export to Sheets or n8n.

- **URL**: https://apify.com/accountable_eel/cftc-commitments-of-traders-lookup.md
- **Developed by:** [Adriana Voss](https://apify.com/accountable_eel) (community)
- **Categories:** Developer tools, Automation
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 weekly cot report row returneds

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?

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

## CFTC Commitments of Traders: Weekly Net Positions by Market

**Get official CFTC Commitments of Traders (COT) weekly positioning data by market, commodity, or contract code.**
One call fetches disaggregated futures positioning straight from the Commodity Futures Trading Commission (publicreporting.cftc.gov) and returns structured weekly rows: total open interest, commercial hedger positions (producer/merchant and swap dealers), speculative managed money (hedge funds, CTAs), other reportables, and non-reportables (retail). Turn on monitoring and run on a weekly schedule (Friday afternoon) to receive only new weekly reports as soon as they are published, billed per row and free on quiet runs.

**Who uses it:**

- **Commodity and macro traders** tracking institutional money flow and commercial hedging in gold, crude oil, natural gas, silver, and grains.
- **Quantitative analysts and quants** building sentiment, positioning velocity, or crowding indicators.
- **Newsletter authors and financial researchers** generating automated weekly COT positioning tables and charts.
- **Automation workflows (Make, n8n, Google Sheets)** alerting on extreme hedge fund net longs or net shorts.

### What is covered

Sourced directly from the official CFTC Disaggregated Futures Commitments of Traders dataset:

- **Managed Money:** long, short, spread, net positioning, and weekly net change (the key speculative positioning metric).
- **Producer / Merchant / Processor / User:** commercial physical hedgers.
- **Swap Dealers:** institutional swap and derivative dealers.
- **Total Commercial Net:** combined producer/merchant and swap dealer net positioning.
- **Other Reportables & Non-Reportables:** active large non-commercial traders and small retail traders.
- **Open Interest:** total market open interest and weekly contract changes.
- **Trader Concentration:** percentage of open interest held by top 4 and top 8 largest traders.

### How to use

1. **In the Apify Console.** Open the actor page and click **Start** — the `markets` field is already pre-filled with a working example. Results land in the run's dataset as soon as each item is found.
2. **Via the API.** Call it directly with a POST request — no Console needed once you have an API token:
   ```bash
   curl "https://api.apify.com/v2/acts/accountable_eel~cftc-commitments-of-traders-lookup/run-sync-get-dataset-items?token=<YOUR_TOKEN>" \
     -X POST \
     -H "Content-Type: application/json" \
     -d '{"markets":["GOLD","CRUDE OIL"]}'
   ```
3. **On a schedule.** Save this actor as an Apify **Task** with the input you want, then add a **Schedule** (hourly, daily, weekly) so it runs on its own — no server of your own required.

### Input

```json
{
  "markets": [
    "GOLD",
    "CRUDE OIL"
  ]
}
```

One market name, commodity, or CFTC contract code per line. For example: GOLD, CRUDE OIL, SILVER, SOYBEANS, or 088691. Sourced from the CFTC Disaggregated Futures Commitments of Traders dataset. Accepted formats: GOLD, CRUDE OIL, SILVER, SOYBEANS, 088691.

```json
{
  "markets": ["GOLD", "CRUDE OIL"],
  "weeks": 4,
  "maxItems": 20
}
```

- `markets`: list of commodities, contract names, or CFTC codes (e.g. `GOLD`, `CRUDE OIL`, `SOYBEANS`, `SILVER`, or code `088691`).
- `weeks`: how many weekly historical reports to fetch per market (default: 4, up to 52).
- `maxItems`: maximum weekly report rows per market (default: 20, up to 100).
- `onlyNewSinceLastRun`: optional boolean (default: false). When true, only reports published since your previous run are returned.
- `deltaName`: optional string to name your watchlist memory.

### Output

One row per weekly report for each matching futures contract:

| query | found | status | market | reportCount | monitorStatus | reports | reportId | reportDate | reportWeek | contractMarketName | marketAndExchange | cftcMarketCode | cftcContractCode | commodityName | commodityGroup | commoditySubgroup | contractUnits | openInterest | openInterestChange | openInterestPct | managedMoneyLong | managedMoneyShort | managedMoneySpread | managedMoneyNet | managedMoneyNetChange | managedMoneyLongPct | managedMoneyShortPct | managedMoneySpreadPct | prodMercLong | prodMercShort | prodMercNet | prodMercLongPct | prodMercShortPct | swapDealersLong | swapDealersShort | swapDealersSpread | swapDealersNet | swapDealersLongPct | swapDealersShortPct | commercialNet | otherReportablesLong | otherReportablesShort | otherReportablesSpread | otherReportablesNet | nonReportablesLong | nonReportablesShort | nonReportablesNet | totalReportableLong | totalReportableShort | totalTraders | concentrationNet4LongPct | concentrationNet4ShortPct | concentrationNet8LongPct | concentrationNet8ShortPct | isNew | sourceUrl | scrapedAt |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| GOLD | true | OK | <market query> | <reports returned> | <monitoring status> | \<all reports (full list)> | <cftc report id> | <report date> | <report week> | <contract market name> | <market and exchange> | <cftc exchange code> | <cftc contract code> | <commodity name> | <commodity group> | <commodity subgroup> | <contract units> | <open interest> | <open interest change> | <open interest percent> | <managed money long> | <managed money short> | <managed money spreading> | <managed money net position> | <managed money net change> | \<managed money long %> | \<managed money short %> | \<managed money spread %> | \<producer/merchant long> | \<producer/merchant short> | \<producer/merchant net position> | \<producer/merchant long %> | \<producer/merchant short %> | <swap dealers long> | <swap dealers short> | <swap dealers spreading> | <swap dealers net position> | \<swap dealers long %> | \<swap dealers short %> | <total commercial net position> | <other reportables long> | <other reportables short> | <other reportables spreading> | <other reportables net position> | <non-reportables long> | <non-reportables short> | <non-reportables net position> | <total reportable long> | <total reportable short> | <total traders> | \<top 4 traders net long %> | \<top 4 traders net short %> | \<top 8 traders net long %> | \<top 8 traders net short %> | \<is this report new?> | <cftc data source url> | 1970-01-01T00:00:00.000Z |

Every row includes:

- `market`: queried market name.
- `reportDate`: Tuesday as-of date (`YYYY-MM-DD`).
- `contractMarketName`: contract name (e.g. `GOLD`, `WTI FINANCIAL CRUDE OIL`).
- `commodityName` & `commodityGroup`: category classifications.
- `openInterest` & `openInterestChange`: total open interest and weekly change.
- `managedMoneyNet` & `managedMoneyNetChange`: net managed money contracts and weekly change.
- `commercialNet`: combined net commercial positions.
- `sourceUrl`: direct link to the CFTC record.
- `scrapedAt`: ISO timestamp.

Missing values return `null` (never 0 or empty string). A query matching no markets returns a single `found: false` row and is never charged.

### Monitoring & Alerts

Turn on `onlyNewSinceLastRun` to run this actor as an automated weekly alert (e.g. scheduled for Friday 4:00 PM US Eastern, right after CFTC releases new data):

- The first run establishes the baseline and returns all matching reports.
- Subsequent runs return only newly published weekly reports.
- Quiet runs (no new release) return a status row with `reportCount: 0`, `monitorStatus: "NO_NEW_REPORTS"`, and cost $0 (never charged).

### Limits

- CFTC updates Commitments of Traders data once a week, normally on Friday at 3:30 PM Eastern Time, reflecting positioning as of the previous Tuesday.
- Disaggregated reports cover physical commodities (precious metals, energies, agriculture, livestock) and select financial contracts.
- Rate limits: requests honor CFTC's crawl-delay policy.

### Pricing

- **Weekly COT report row returned**: $4 per 1,000 reports

Plus a $0.00005 start fee per run. Each event above is billed independently, only when it actually returns data — misses (`found:false`) are never charged.

### Use it from Clay, n8n, Make, or an AI agent

This actor runs synchronously over plain HTTP — call it directly from a script, a workflow tool, or an AI agent, no Apify Console needed once you have an API token.

```bash
curl "https://api.apify.com/v2/acts/accountable_eel~cftc-commitments-of-traders-lookup/run-sync-get-dataset-items?token=<YOUR_TOKEN>" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"markets":["GOLD","CRUDE OIL"]}'
```

**n8n.** Add an HTTP Request node: Method `POST`, URL `https://api.apify.com/v2/acts/accountable_eel~cftc-commitments-of-traders-lookup/run-sync-get-dataset-items?token=<YOUR_TOKEN>`, Body Content Type `JSON`, JSON Body `{"markets":["GOLD","CRUDE OIL"]}` (swap in an expression from an earlier node for a real value).

**Clay.** Add an "HTTP API" column: Method `POST`, URL `https://api.apify.com/v2/acts/accountable_eel~cftc-commitments-of-traders-lookup/run-sync-get-dataset-items?token=<YOUR_TOKEN>`, Body `{"markets":["{{market}}"]}`, mapping the row's market into the `markets` array.

**MCP.** In Claude, Cursor, or any MCP client with the Apify MCP server, ask for "cftc commitments of traders data" — the agent will find and run this actor.

### Example runs

Paste any of these into the Input tab and press Start. All three run keyless with no tokens, keys, or external setup required.

**1. Gold and Crude Oil positioning (last 4 weeks)**

```json
{
  "markets": ["GOLD", "CRUDE OIL"],
  "weeks": 4,
  "maxItems": 20
}
```

**2. Precious metals watch (Gold, Silver, Platinum)**

```json
{
  "markets": ["GOLD", "SILVER", "PLATINUM"],
  "weeks": 8,
  "maxItems": 30
}
```

**3. Weekly Friday COT monitor (alerts only on newly released reports)**

```json
{
  "markets": ["GOLD", "CRUDE OIL", "NATURAL GAS", "SOYBEANS"],
  "weeks": 1,
  "onlyNewSinceLastRun": true,
  "deltaName": "weekly-commodities-alert"
}
```

# Actor input Schema

## `markets` (type: `array`):

One market name, commodity, or CFTC contract code per line. For example: GOLD, CRUDE OIL, SILVER, SOYBEANS, or 088691. Sourced from the CFTC Disaggregated Futures Commitments of Traders dataset. Accepted formats: GOLD, CRUDE OIL, SILVER, SOYBEANS, 088691. You're only charged for the ones we actually find — a miss costs nothing.

## `weeks` (type: `integer`):

How many historical weekly Tuesday reports to include for each market (default 4, up to 52).

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

Caps how many weekly report rows are returned and billed for each market (default 20, up to 100).

## `onlyNewSinceLastRun` (type: `boolean`):

On: only new weekly COT reports published since your last run are returned and charged for. Run on a weekly schedule (e.g. Friday evening) as a COT alert. Off: returns the last N weeks every time.

## `deltaName` (type: `string`):

Optional. Name this search's monitoring memory so you can run multiple independent schedules. Leave empty to auto-derive from your market list.

## `testRun` (type: `boolean`):

Turn this on to test your input on a small sample before running the full list. Turn it off to process everything.

## `onlyFound` (type: `boolean`):

Only keep rows where something was actually found. Misses are always free, whether or not you show them here.

## `includeKeywords` (type: `array`):

Optional. Only keep results that mention at least one of these words (e.g. a job title, a city, a product name). Leave empty to keep everything.

## `excludeKeywords` (type: `array`):

Optional. Drop any result that mentions one of these words. Leave empty to skip nothing.

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

Optional. Stop the run once this many results have been found — useful for a quick, cheap sample. Leave blank for no limit.

## `columns` (type: `array`):

Choose which pieces of information to include in each result row. All are included by default.

## `expandRows` (type: `boolean`):

When on, each report found gets its own row instead of being grouped under its market. You're still only charged once per market, no matter how many rows it produces.

## `maxConcurrency` (type: `integer`):

Parallel requests. Keep conservative — this target has no browser fallback, so getting blocked costs more than slow-and-steady.

## Actor input object example

```json
{
  "markets": [
    "GOLD",
    "CRUDE OIL"
  ],
  "weeks": 4,
  "maxItems": 20,
  "onlyNewSinceLastRun": false,
  "deltaName": "",
  "testRun": false,
  "onlyFound": false,
  "includeKeywords": [],
  "excludeKeywords": [],
  "columns": [
    "market",
    "reportCount",
    "monitorStatus",
    "reports",
    "reportId",
    "reportDate",
    "reportWeek",
    "contractMarketName",
    "marketAndExchange",
    "cftcMarketCode",
    "cftcContractCode",
    "commodityName",
    "commodityGroup",
    "commoditySubgroup",
    "contractUnits",
    "openInterest",
    "openInterestChange",
    "openInterestPct",
    "managedMoneyLong",
    "managedMoneyShort",
    "managedMoneySpread",
    "managedMoneyNet",
    "managedMoneyNetChange",
    "managedMoneyLongPct",
    "managedMoneyShortPct",
    "managedMoneySpreadPct",
    "prodMercLong",
    "prodMercShort",
    "prodMercNet",
    "prodMercLongPct",
    "prodMercShortPct",
    "swapDealersLong",
    "swapDealersShort",
    "swapDealersSpread",
    "swapDealersNet",
    "swapDealersLongPct",
    "swapDealersShortPct",
    "commercialNet",
    "otherReportablesLong",
    "otherReportablesShort",
    "otherReportablesSpread",
    "otherReportablesNet",
    "nonReportablesLong",
    "nonReportablesShort",
    "nonReportablesNet",
    "totalReportableLong",
    "totalReportableShort",
    "totalTraders",
    "concentrationNet4LongPct",
    "concentrationNet4ShortPct",
    "concentrationNet8LongPct",
    "concentrationNet8ShortPct",
    "isNew",
    "sourceUrl"
  ],
  "expandRows": true,
  "maxConcurrency": 1
}
```

# 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 = {
    "markets": [
        "GOLD",
        "CRUDE OIL"
    ],
    "includeKeywords": [],
    "excludeKeywords": []
};

// Run the Actor and wait for it to finish
const run = await client.actor("accountable_eel/cftc-commitments-of-traders-lookup").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 = {
    "markets": [
        "GOLD",
        "CRUDE OIL",
    ],
    "includeKeywords": [],
    "excludeKeywords": [],
}

# Run the Actor and wait for it to finish
run = client.actor("accountable_eel/cftc-commitments-of-traders-lookup").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 '{
  "markets": [
    "GOLD",
    "CRUDE OIL"
  ],
  "includeKeywords": [],
  "excludeKeywords": []
}' |
apify call accountable_eel/cftc-commitments-of-traders-lookup --silent --output-dataset

```

## MCP server setup

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

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/xbwox6pnQPYCDm6Mv/builds/Tc4RjMMky6N9THLaf/openapi.json
