CFTC positioning

One futures contract: open interest, positions by trader class.

Routes

Base URL https://api.gloom.sh. Send a key with each call; the key's account needs a plan.

GET /v1/cftc/cot

CFTC positioning by contract. Reads stored data only and needs a key on an account with a plan; every plan reads every live dataset in full. Unknown, empty and repeated parameters are rejected. History and coverage metadata are null when the stored service cannot establish them.

Parameter: report
In: query
Type: legacy, disaggregated

Parameter: traderClass
In: query
Type: noncommercial, commercial, nonreportable, producer, swap, managed-money, other-reportable
Notes: Must belong to the selected report. Legacy: noncommercial (default), commercial, nonreportable. Disaggregated: producer, swap, managed-money (default), other-reportable, nonreportable.

Parameter	In	Type	Notes
`report`	query	`legacy`, `disaggregated`
`traderClass`	query	`noncommercial`, `commercial`, `nonreportable`, `producer`, `swap`, `managed-money`, `other-reportable`	Must belong to the selected report. Legacy: noncommercial (default), commercial, nonreportable. Disaggregated: producer, swap, managed-money (default), other-reportable, nonreportable.

Credits: 1 (lookup x1)
Plans: Basic, Desk, Enterprise

GET /v1/cftc/cot/contracts/{contractCode}

CFTC contract positioning history. Reads stored data only and needs a key on an account with a plan; every plan reads every live dataset in full. Unknown, empty and repeated parameters are rejected. History and coverage metadata are null when the stored service cannot establish them.

Parameter: contractCode
In: path, required
Type: string ^[0-9A-Za-z]{5}[0-9A-Za-z+]$
Notes: Six-character CFTC market code; normalized to uppercase.

Parameter: report
In: query
Type: legacy, disaggregated

Parameter: traderClass
In: query
Type: noncommercial, commercial, nonreportable, producer, swap, managed-money, other-reportable
Notes: Must belong to the selected report. Legacy: noncommercial (default), commercial, nonreportable. Disaggregated: producer, swap, managed-money (default), other-reportable, nonreportable.

Parameter	In	Type	Notes
`contractCode`	path, required	string `^[0-9A-Za-z]{5}[0-9A-Za-z+]$`	Six-character CFTC market code; normalized to uppercase.
`report`	query	`legacy`, `disaggregated`
`traderClass`	query	`noncommercial`, `commercial`, `nonreportable`, `producer`, `swap`, `managed-money`, `other-reportable`	Must belong to the selected report. Legacy: noncommercial (default), commercial, nonreportable. Disaggregated: producer, swap, managed-money (default), other-reportable, nonreportable.

Credits: 2 (history x1)
Plans: Basic, Desk, Enterprise

Example response

Synthetic values, marked in meta. GET /v1/datasets/cot/sample returns it with no key and no account.

json

{
  "data": {
    "source": "CFTC",
    "scope": "futures-only",
    "reportFamily": "legacy",
    "generatedAt": "2026-09-30T12:00:00.000Z",
    "asOf": "2026-09-29",
    "fetchedAt": "2026-09-30T12:00:00.000Z",
    "publishedAt": null,
    "status": "partial",
    "gaps": [
      "ILLUSTRATIVE sample only"
    ],
    "classes": [
      {
        "id": "noncommercial",
        "label": "Noncommercial"
      }
    ],
    "traderClass": "noncommercial",
    "rows": [
      {
        "contractCode": "000001",
        "marketName": "ILLUSTRATIVE contract 1",
        "exchangeCode": "ILLUSTRATIVE",
        "commodityCode": "ILLUSTRATIVE",
        "reportDate": "2026-09-29",
        "openInterest": 1000,
        "position": {
          "id": "noncommercial",
          "label": "Noncommercial",
          "long": 300,
          "short": 200,
          "spreading": 0,
          "net": 100,
          "netPercentOfOpenInterest": 10,
          "weeklyChange": null,
          "previousReportDate": null,
          "percentile1Y": {
            "value": null,
            "rank": null,
            "sampleCount": 0,
            "windowStart": "2025-09-29",
            "windowEnd": "2026-09-29",
            "historyStart": null,
            "historyEnd": null,
            "completeWindow": false,
            "min": null,
            "max": null,
            "mean": null
          },
          "percentile3Y": {
            "value": null,
            "rank": null,
            "sampleCount": 0,
            "windowStart": "2025-09-29",
            "windowEnd": "2026-09-29",
            "historyStart": null,
            "historyEnd": null,
            "completeWindow": false,
            "min": null,
            "max": null,
            "mean": null
          }
        },
        "status": "available"
      },
      {
        "contractCode": "000002",
        "marketName": "ILLUSTRATIVE contract 2",
        "exchangeCode": "ILLUSTRATIVE",
        "commodityCode": "ILLUSTRATIVE",
        "reportDate": "2026-09-29",
        "openInterest": 1000,
        "position": {
          "id": "noncommercial",
          "label": "Noncommercial",
          "long": 300,
          "short": 200,
          "spreading": 0,
          "net": 100,
          "netPercentOfOpenInterest": 10,
          "weeklyChange": null,
          "previousReportDate": null,
          "percentile1Y": {
            "value": null,
            "rank": null,
            "sampleCount": 0,
            "windowStart": "2025-09-29",
            "windowEnd": "2026-09-29",
            "historyStart": null,
            "historyEnd": null,
            "completeWindow": false,
            "min": null,
            "max": null,
            "mean": null
          },
          "percentile3Y": {
            "value": null,
            "rank": null,
            "sampleCount": 0,
            "windowStart": "2025-09-29",
            "windowEnd": "2026-09-29",
            "historyStart": null,
            "historyEnd": null,
            "completeWindow": false,
            "min": null,
            "max": null,
            "mean": null
          }
        },
        "status": "available"
      },
      {
        "contractCode": "000003",
        "marketName": "ILLUSTRATIVE contract 3",
        "exchangeCode": "ILLUSTRATIVE",
        "commodityCode": "ILLUSTRATIVE",
        "reportDate": "2026-09-29",
        "openInterest": 1000,
        "position": {
          "id": "noncommercial",
          "label": "Noncommercial",
          "long": 300,
          "short": 200,
          "spreading": 0,
          "net": 100,
          "netPercentOfOpenInterest": 10,
          "weeklyChange": null,
          "previousReportDate": null,
          "percentile1Y": {
            "value": null,
            "rank": null,
            "sampleCount": 0,
            "windowStart": "2025-09-29",
            "windowEnd": "2026-09-29",
            "historyStart": null,
            "historyEnd": null,
            "completeWindow": false,
            "min": null,
            "max": null,
            "mean": null
          },
          "percentile3Y": {
            "value": null,
            "rank": null,
            "sampleCount": 0,
            "windowStart": "2025-09-29",
            "windowEnd": "2026-09-29",
            "historyStart": null,
            "historyEnd": null,
            "completeWindow": false,
            "min": null,
            "max": null,
            "mean": null
          }
        },
        "status": "available"
      }
    ]
  },
  "meta": {
    "dataset": "cot",
    "asOf": null,
    "source": [
      {
        "id": "cftc-cot",
        "attribution": "Commodity Futures Trading Commission",
        "licence": "Public government files"
      }
    ],
    "historyStarts": null,
    "coverage": null,
    "lastUpdated": null,
    "sample": true,
    "note": "ILLUSTRATIVE: synthetic examples showing the response fields; not real company disclosures or published observations."
  }
}

Meta fields

Field: dataset
Here: The dataset id
In the example: "cot"

Field: asOf
Here: The position observation date
In the example: null

Field: source
Here: Attribution and licence of each source
In the example: 1 source

Field: historyStarts
Here: Earliest stored history when established by the service; otherwise null.
In the example: null, not stated yet

Field: coverage
Here: Service-established coverage; null when unavailable.
In the example: null

Field: lastUpdated
Here: When the CFTC file was downloaded
In the example: null

Field	Here	In the example
`dataset`	The dataset id	`"cot"`
`asOf`	The position observation date	null
`source`	Attribution and licence of each source	1 source
`historyStarts`	Earliest stored history when established by the service; otherwise null.	null, not stated yet
`coverage`	Service-established coverage; null when unavailable.	null
`lastUpdated`	When the CFTC file was downloaded	null

Sources

Source: Commodity Futures Trading Commission
Licence: Public government files

Source	Licence
Commodity Futures Trading Commission	Public government files

Errors

These routes can answer 400, 401, 402, 403, 404, 429, 503. See Errors for the codes.

Gloom Datasets reads stored data only: a call never starts a collection.