Regime Transitions

A log of the moments assets changed trend regime — for example, every stock that entered a Leading Trend last year, and when. Each entry records the label before and after, plus a snapshot of the asset’s metrics on the day it changed.

curl "https://api.bytetree.io/api/metrics/regime-transitions?window=200w-CAPR&regime=Leading+Trend&from=2024-01-01&to=2024-12-31&q=NVDA" \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch("https://api.bytetree.io/api/metrics/regime-transitions?window=200w-CAPR&regime=Leading+Trend&from=2024-01-01&to=2024-12-31&q=NVDA", {
  headers: { "Authorization": "Bearer YOUR_API_KEY" },
});
const body = await res.json();

import requests

res = requests.get(
    "https://api.bytetree.io/api/metrics/regime-transitions?window=200w-CAPR&regime=Leading+Trend&from=2024-01-01&to=2024-12-31&q=NVDA",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
body = res.json()

{
  "generatedAt": "2026-10-09T09:17:59.555Z",
  "regime": "Leading Trend",
  "window": "200w-CAPR",
  "direction": "into",
  "appliedRange": { "from": "2024-01-01", "to": "2024-12-31", "defaulted": false },
  "count": 1,
  "data": [
    {
      "symbol": "NVDA",
      "transitionDate": "2024-03-07",
      "fromRegime": "Neutral",
      "toRegime": "Leading Trend",
      "metricsAtTransition": {
        "closeUsd": 92.62,
        "byteTrendCapr200w": 5,
        "byteTrendCapr30d": 5,
        "returnUsd1M": 0.3585,
        "marketCapUsd": 2281535400000,
        "sharpe52w": 6.5771
      },
      "trendAgeAtTransition": 5,
      "confirmedTransitionDate": "2024-03-07",
      "pendingStartDate": "2024-03-01"
    }
  ]
}

curl "https://api.bytetree.io/api/metrics/regime-transitions?window=30d-CAPR&direction=any&from=2026-09-01&to=2026-09-30&type=stock&status=active&sector=Technology" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://api.bytetree.io/api/metrics/regime-transitions?window=200w-CAPR&regime=Leading+Trend&from=2026-09-01&to=2026-09-30&type=stock&sector=Technology&fields=closeUsd%2Csharpe52w%2CreturnUsd1M" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://api.bytetree.io/api/metrics/regime-transitions?window=200w-CAPR&direction=any&type=crypto" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters

Dates must be real calendar dates, fields names must be well formed, and window, direction, regime, type and status must be values the endpoint lists, or the request is a 400 — see Value validation. A well-formed field name the record doesn’t have comes back as null in metricsAtTransition.

Group filters

universe restricts the scanned population to that universe’s members — the assets whose universes[] includes the slug. Without it, the scan covers the whole registry.

dimension + group narrow the scan by the asset’s resolved value in one of the five global dimensions. The pair is independent of universe and both-or-neither: one without the other is a 400, as is an unknown dimension. type, status, sector and q compose with all of these. Both filters genuinely narrow the scan, which matters for the row cap under Bounds.

?universe=macro is a 400 — the macro dataset is at /api/macro, not a universe. Filter by nothing to scan the whole registry.

Response

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.

closeUsd is on today’s adjusted basis, so it reflects NVDA’s later share split.

Default date window

A call without from does not scan all history. When from is omitted the server applies a 90-day look-back, anchored on to if you supplied one and on the current date otherwise. An explicit from is always honoured as given — widening the range is opt-in.

Every response reports the window it actually used:

// No dates supplied — 90-day look-back, open-ended at the recent end
"appliedRange": { "from": "2026-07-11", "to": null, "defaulted": true }

// from supplied — honoured as-is
"appliedRange": { "from": "2026-09-01", "to": null, "defaulted": false }

// to supplied without from — look-back anchored on `to`
"appliedRange": { "from": "2023-10-03", "to": "2024-01-01", "defaulted": true }

Two things to read carefully:

• defaulted — true means you are looking at a 90-day slice, not the whole history. Check it before interpreting a small result set as a genuine absence of transitions.
• to: null — not an omission. The upper bound reports what you bounded; null means the query ran open-ended to the latest available data. The 90-day look-back is anchored internally on the current date, but that anchor is not reported as a to you didn’t ask for.

This default matches the equivalent ByteTree MCP tool, so both surfaces bound an unqualified query the same way.

The default stops a date-less call from scanning all history, but 90 days of the whole registry is still a lot of work: a date-less call with no asset filter is usually refused under the query-time bound below. Add an asset filter such as type, sector or universe, as in the last request example.

Bounds

• Query time. A query that can’t be computed in about 15 seconds is refused with 400 rather than left to time out:

  { "error": "regime-transitions query too broad to compute in time — narrow the date range (from/to) or add an asset filter (type/sector/universe)" }

  The work grows with date range × population. A whole-registry query over a full year — or over the 90-day default — hits this, and so can a multi-year range for a single asset type. Narrow with type, sector, universe or dimension + group, or a tighter range. This response carries Cache-Control: no-store, so a retry after narrowing is never served the error from a cache.

• 5001-row short-circuit. The query is capped at 5001 rows; if 5001 rows return the server replies 400 with a hint to narrow the date range, the asset filter, or direction. direction=any is the shape most likely to reach it.

• type=fx is rejected with 400.

Regime labels

The five labels — Leading Trend, Emerging Trend, Weakening Trend, Bear Trend and Neutral — are the same for all four windows. See Trend regime for what each one means.

Notes

• Requires an API key.
• Successful responses carry Cache-Control: private, max-age=60: a repeat of the same request within a minute may be answered from your client’s cache.
• 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.