Regime Transitions

Returns an event log of trend-regime transitions across the asset population — for each (symbol, transitionDate) pair where a regime change occurred, returns the from and to regime labels plus a snapshot of metric values at the transition. Designed for “which assets entered or left this regime, when, and what did the rest of the metric set look like at the moment they did?”.

Request

# Assets that entered Leading Trend on the 200w-CAPR window in 2024
curl "https://api.bytetree.io/api/metrics/regime-transitions?window=200w-CAPR&regime=Leading%20Trend&from=2024-01-01&to=2024-12-31"

# Any 30d-CAPR transition in the last 90 days for active stocks
curl "https://api.bytetree.io/api/metrics/regime-transitions?window=30d-CAPR&direction=any&from=2026-02-01&type=stock&status=active"

# Custom metric snapshot at transition
curl "https://api.bytetree.io/api/metrics/regime-transitions?window=200w-CAPR&regime=Leading%20Trend&from=2025-01-01&fields=closeUsd,sharpe52w,returnUsd1M"

Query Parameters

Name	Type	Required	Description
`window`	`string`	Yes	Score window. One of `200w-CAPR`, `200w-Local`, `30d-CAPR`, `30d-Local`
`regime`	`string`	Yes when `direction !== 'any'`	Target regime label (e.g. `Leading Trend`, `Emerging Trend`, `Late Stage`, `Crash`). May be omitted when `direction=any`
`direction`	`string`	No	One of `into`, `outOf`, `any` (case-insensitive). Default `into`. `any` returns every transition regardless of `regime`
`from`	`string`	No	Inclusive ISO `YYYY-MM-DD` lower bound on `transitionDate`
`to`	`string`	No	Inclusive ISO `YYYY-MM-DD` upper bound on `transitionDate`
`type`	`string`	No	Asset-type filter — `stock`, `crypto`, `etf`, `index`, `commodity`. `fx` is rejected
`status`	`string`	No	Asset status — `active`, `pending`, `inactive`
`sector`	`string`	No	Sector filter (case-insensitive)
`q`	`string`	No	Free-text symbol/name search
`universe`	`string`	No	Universe slug (e.g. `macro`, `global-trends-200`). Use with `dimension` and `group`. Out-of-scope slugs return `403`
`dimension`	`string`	No	Dimension within the universe: `region`, `sector`, `industry`, `type`, or `country`
`group`	`string`	No	Group label within the dimension, exact match (paired with `universe` + `dimension`)
`fields`	`string`	No	Comma-separated metric keys included in `metricsAtTransition`. Default: `closeUsd, byteTrendCapr200w, byteTrendCapr30d, returnUsd1M, marketCapUsd, sharpe52w`
`format`	`string`	No	Response format: `json` (default), `csv`, or `toon`

Response

Field	Type	Description
`generatedAt`	`string`	ISO timestamp captured when the server ran the aggregation
`regime`	`string` or `null`	Echo of the resolved target regime. `null` when `direction=any`
`window`	`string`	Echo of the resolved window
`direction`	`string`	Echo of the resolved direction
`count`	`number`	Number of transition rows in `data`
`data`	`object[]`	One row per transition event
`data[].symbol`	`string`	Asset ticker symbol
`data[].transitionDate`	`string`	ISO `YYYY-MM-DD`. For raw windows, this IS the confirmation date; see below
`data[].fromRegime`	`string`	Regime label immediately before the transition
`data[].toRegime`	`string`	Regime label after the transition
`data[].metricsAtTransition`	`object`	Snapshot of `fields` evaluated at `transitionDate`
`data[].trendAgeAtTransition`	`number`	Confirmed window only. Days the prior regime had been in force at the transition
`data[].confirmedTransitionDate`	`string`	Confirmed window only. Same value as `transitionDate` — kept for explicitness
`data[].pendingStartDate`	`string`	Confirmed window only. Date the pending transition first appeared. Confirmation lag is the trading-day delta to `confirmedTransitionDate`

Two output shapes

window=200w-CAPR (confirmed window) — every row carries trendAgeAtTransition, confirmedTransitionDate, and pendingStartDate. The 4-trading-day delta between pendingStartDate and confirmedTransitionDate is the confirmation lag built into the long-window CAPR score.
window=200w-Local, 30d-CAPR, 30d-Local (raw windows — no confirmation lag) — those three fields are omitted entirely from each row. transitionDate IS the confirmation date.

{
  "generatedAt": "2026-05-07T19:42:00.613Z",
  "regime": "Leading Trend",
  "window": "200w-CAPR",
  "direction": "into",
  "count": 160,
  "data": [
    {
      "symbol": "NVDA",
      "transitionDate": "2024-03-12",
      "fromRegime": "Emerging Trend",
      "toRegime": "Leading Trend",
      "trendAgeAtTransition": 5,
      "confirmedTransitionDate": "2024-03-12",
      "pendingStartDate": "2024-03-07",
      "metricsAtTransition": {
        "closeUsd": 880.21,
        "byteTrendCapr200w": 5,
        "byteTrendCapr30d": 5,
        "returnUsd1M": 0.084,
        "marketCapUsd": 2200000000000,
        "sharpe52w": 1.42
      }
    }
  ]
}

Bounds

5001-row short-circuit. The query is capped at $limit: 5001; if 5001 rows return the server replies 400 with a hint to narrow the date range, the asset filter, or direction. The cap protects both sides — direction=any over the entire population without filters will reliably trip it.
type=fx is rejected with 400.

Regime labels

Regime labels are the values of confirmedRegime* / pendingRegime* produced by the scoring engine. See the Latest Metrics field reference for the full label set per window. The MCP bytetree://glossary resource holds authoritative wording sourced from engine doc-strings.

Notes

Requires an API key.
Backs the public ByteTree MCP’s get_regime_transitions tool.
The metricsAtTransition block is a point-in-time snapshot — values are read from the symbol’s metric record on transitionDate, not recomputed.