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

# TFC and Setup Snapshots

> Retrieve the complete real-time state for a symbol: metadata, latest price, TFC colors across all timeframes, and all active setups in one response.

The states endpoint returns a single-symbol snapshot that aggregates everything StratAlerts tracks for a ticker: its instrument metadata, the most recent trade price, the Timeframe Continuity (TFC) color for each timeframe, and all active setup rows. This is the same data that powers the per-symbol overview page in the StratAlerts UI and is the most efficient way to get a complete picture of a symbol in one request.

**`GET https://app.stratalerts.com/api/market/v1/states/{symbol}`**

<Note>
  Requires scope: `states:read`
</Note>

## Path parameters

<ParamField path="symbol" type="string" required>
  The ticker symbol to look up (e.g., `AAPL`). Normalized to uppercase. Returns `404` if the symbol is unknown or not tracked.
</ParamField>

## Response fields

<ResponseField name="symbol" type="string" required>
  The requested ticker symbol, uppercased.
</ResponseField>

<ResponseField name="instrument" type="object" required>
  Full instrument metadata object. Contains the same fields as the [instruments endpoint](/api/rest/instruments): `symbol`, `name`, `market`, `exchange`, `type`, `sector`, and `active`.
</ResponseField>

<ResponseField name="price" type="object" required>
  Latest trade price object from the prices feed. Contains at minimum `price` and `volume`. May be an empty object (`{}`) if no recent trade is on record.
</ResponseField>

<ResponseField name="tfc" type="object" required>
  Timeframe Continuity state for the symbol. Keys are timeframe labels; values are color strings indicating directional bias.

  <Expandable title="tfc keys and values">
    <ResponseField name="D" type="string">
      Daily TFC color:
      `green`
      ,
      `red`
      , or
      `yellow`
      .
    </ResponseField>

    <ResponseField name="W" type="string">
      Weekly TFC color.
    </ResponseField>

    <ResponseField name="M" type="string">
      Monthly TFC color.
    </ResponseField>

    <ResponseField name="Q" type="string">
      Quarterly TFC color.
    </ResponseField>

    <ResponseField name="Y" type="string">
      Yearly TFC color.
    </ResponseField>
  </Expandable>

  Only timeframes with a recorded TFC state appear in this object. Intraday timeframes may appear when available.
</ResponseField>

<ResponseField name="setups" type="object[]" required>
  Array of active setup rows for the symbol. Each object includes the setup shape (e.g., `1-2U`), in-force status, P3 and PMG flags, continuation status, and sector. The exact shape mirrors the [setups endpoint](/api/rest/setups) response items.
</ResponseField>

<ResponseField name="default_timeframe" type="string" required>
  The recommended default chart timeframe for this symbol (e.g., `D`).
</ResponseField>

<ResponseField name="chart_timeframes" type="string[]" required>
  Ordered list of timeframe labels available for this symbol's chart display (e.g., `["15", "30", "60", "4H", "D", "W", "M", "Q", "Y"]`).
</ResponseField>

## Code examples

<CodeGroup>
  ```bash curl theme={null}
  curl "https://app.stratalerts.com/api/market/v1/states/AAPL" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python python theme={null}
  import requests

  resp = requests.get(
      "https://app.stratalerts.com/api/market/v1/states/AAPL",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
  )
  resp.raise_for_status()
  state = resp.json()

  # Read TFC colors
  for tf, color in state["tfc"].items():
      print(f"{tf}: {color}")

  # Count active setups
  print(f"{len(state['setups'])} active setup(s)")
  ```

  ```javascript javascript theme={null}
  const resp = await fetch(
    "https://app.stratalerts.com/api/market/v1/states/AAPL",
    { headers: { Authorization: "Bearer YOUR_API_KEY" } }
  );
  const state = await resp.json();

  // Read TFC colors
  Object.entries(state.tfc).forEach(([tf, color]) =>
    console.log(`${tf}: ${color}`)
  );

  // Count active setups
  console.log(`${state.setups.length} active setup(s)`);
  ```
</CodeGroup>

## Example response

```json theme={null}
{
  "symbol": "AAPL",
  "instrument": {
    "symbol": "AAPL",
    "name": "Apple Inc.",
    "market": "stocks",
    "exchange": "NASDAQ",
    "type": "CS",
    "sector": "Information Technology",
    "active": true
  },
  "price": {
    "price": 214.32,
    "volume": 1200
  },
  "tfc": {
    "D": "green",
    "W": "red",
    "M": "green",
    "Q": "green",
    "Y": "green"
  },
  "setups": [
    {
      "symbol": "AAPL",
      "timeframe": "D",
      "shape": "1-2U",
      "in_force": true,
      "p3": false,
      "pmg": null,
      "continuation": false,
      "sector": "Information Technology"
    }
  ],
  "default_timeframe": "D",
  "chart_timeframes": ["15", "30", "60", "4H", "D", "W", "M", "Q", "Y"]
}
```

## Error codes

| HTTP status | Error code             | Meaning                                                    |
| ----------- | ---------------------- | ---------------------------------------------------------- |
| 401         | `missing_api_key`      | No API key was provided or the key format is invalid.      |
| 403         | `inactive_entitlement` | Your account does not have an active API entitlement.      |
| 403         | `missing_scope`        | Your API key does not have the `states:read` scope.        |
| 404         | `unknown_symbol`       | The symbol was not found or is not tracked by StratAlerts. |

Error responses use the following shape:

```json theme={null}
{
  "error": {
    "code": "unknown_symbol",
    "message": "unknown symbol"
  }
}
```