> ## Documentation Index
> Fetch the complete documentation index at: https://docs.financialdatapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Positioning

> Raw CFTC Commitments of Traders (COT) and Traders in Financial Futures (TFF) positioning, in the same observation model as macro.

Financial Data API carries the U.S. Commodity Futures Trading Commission's weekly positioning reports as first-class observations: the **Commitments of Traders (COT)** report and the **Traders in Financial Futures (TFF)** report. They sit under the `positioning` category, with full history and provenance, so you can read how each trader cohort is positioned across futures markets and join it against price, macro, and rates.

<Note>
  This page covers the **raw** positioning series. For positioning expressed as a historical percentile (how stretched a cohort is versus its own history), see the `cot_positioning_percentile` dataset on [Derived analytics](/apis/derived-analytics).
</Note>

## What data is available

<CardGroup cols={2}>
  <Card title="cot_positioning" icon="scale-balanced">
    CFTC Commitments of Traders — non-commercial (speculator) and commercial long/short positions and open interest, per reported futures market, weekly.
  </Card>

  <Card title="cot_tff" icon="building-columns">
    Traders in Financial Futures — leveraged-funds and asset-manager long/short positioning (with the full breakdown and open interest in metadata), weekly.
  </Card>
</CardGroup>

<Info>
  Positioning rows are keyed by the reported futures market (identified in the observation metadata and provenance), not by country. The reports are published weekly by the CFTC, typically on a Friday for the prior Tuesday.
</Info>

## Query positioning

<CodeGroup>
  ```bash cURL theme={"theme":"css-variables"}
  # Latest positioning rows
  curl "https://api.financialdatapi.com/observations/latest?indicator_id=cot_positioning" \
    -H "x-api-key: $FINANCIALDATA_API_KEY"

  # TFF history
  curl "https://api.financialdatapi.com/observations?indicator_id=cot_tff&limit=20&order=desc" \
    -H "x-api-key: $FINANCIALDATA_API_KEY"
  ```

  ```typescript TypeScript theme={"theme":"css-variables"}
  import { FinancialDataApiClient } from "@financialdatapi/client";

  const client = new FinancialDataApiClient({ apiKey: process.env.FINANCIALDATA_API_KEY });

  const { data } = await client.getLatestObservations({ indicator_id: "cot_positioning" });
  console.log(data);
  ```
</CodeGroup>

## Response shape

Each row is a standard public observation. The fields most relevant here:

<ResponseField name="indicatorId" type="string">`cot_positioning` or `cot_tff`.</ResponseField>
<ResponseField name="category" type="string">`positioning`.</ResponseField>
<ResponseField name="actual" type="number">The headline positioning value for the row (for example the cohort's net position).</ResponseField>
<ResponseField name="metadata" type="object">The per-cohort breakdown (long, short, open interest) and the futures market the row describes.</ResponseField>
<ResponseField name="provider" type="string">`U.S. Commodity Futures Trading Commission`.</ResponseField>
<ResponseField name="periodEnd" type="string">The report (as-of-Tuesday) date.</ResponseField>

<Tip>
  The cohort breakdown is in `metadata`; read it from the row, and use `GET /provenance/observations/{observationId}` for the full chain back to the CFTC release.
</Tip>

## Related

<Columns cols={3}>
  <Card title="Derived analytics" icon="calculator" href="/apis/derived-analytics">
    COT positioning expressed as a historical percentile.
  </Card>

  <Card title="Energy & commodities" icon="oil-well" href="/apis/energy-commodities">
    EIA energy market data.
  </Card>
</Columns>