TFC and Setup Snapshots

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}

Requires scope: states:read

Path parameters

string

required

The ticker symbol to look up (e.g., AAPL). Normalized to uppercase. Returns 404 if the symbol is unknown or not tracked.

Response fields

string

required

The requested ticker symbol, uppercased.

object

required

Full instrument metadata object. Contains the same fields as the instruments endpoint: symbol, name, market, exchange, type, sector, and active.

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.

object

required

Timeframe Continuity state for the symbol. Keys are timeframe labels; values are color strings indicating directional bias.

Show tfc keys and values

string

Daily TFC color: green , red , or yellow .

string

Weekly TFC color.

string

Monthly TFC color.

string

Quarterly TFC color.

string

Yearly TFC color.

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

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 response items.

string

required

The recommended default chart timeframe for this symbol (e.g., D).

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"]).

Code examples

curl "https://app.stratalerts.com/api/market/v1/states/AAPL" \
  -H "Authorization: Bearer YOUR_API_KEY"

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

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)`);

Example response

{
  "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:

{
  "error": {
    "code": "unknown_symbol",
    "message": "unknown symbol"
  }
}

Overview

REST Endpoints

WebSocket

TFC and Setup Snapshots

Path parameters

Response fields

Code examples

Example response

Error codes

​Path parameters

​Response fields

​Code examples

​Example response

​Error codes

Path parameters

Response fields

Code examples

Example response

Error codes