Skip to main content
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

​
symbol
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

​
symbol
string
required
The requested ticker symbol, uppercased.
​
instrument
object
required
Full instrument metadata object. Contains the same fields as the instruments endpoint: symbol, name, market, exchange, type, sector, and active.
​
price
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.
​
tfc
object
required
Timeframe Continuity state for the symbol. Keys are timeframe labels; values are color strings indicating directional bias.Only timeframes with a recorded TFC state appear in this object. Intraday timeframes may appear when available.
​
setups
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.
​
default_timeframe
string
required
The recommended default chart timeframe for this symbol (e.g., D).
​
chart_timeframes
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"

​
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 statusError codeMeaning
401missing_api_keyNo API key was provided or the key format is invalid.
403inactive_entitlementYour account does not have an active API entitlement.
403missing_scopeYour API key does not have the states:read scope.
404unknown_symbolThe symbol was not found or is not tracked by StratAlerts.
Error responses use the following shape: 
{
  "error": {
    "code": "unknown_symbol",
    "message": "unknown symbol"
  }
}