---
title: "BTC Cycle signal timeline (band per indicator and week/day)"
method: GET
path: "/api/v1/btc-cycle/timeline"
tags: ["History"]
---

# BTC Cycle signal timeline (band per indicator and week/day)

`GET /api/v1/btc-cycle/timeline`

## Request

- Base URL: `https://tradingstrategies.work`
- URL: `https://tradingstrategies.work/api/v1/btc-cycle/timeline`
- Auth: HTTP bearer

Band per cycle indicator (composite first, then the nine components in weight order) over time, from STORED point-in-time scores — nothing is recomputed. Weekly cells carry the LAST available day of the ISO week (never an average). flips[] lists day-to-day band changes per row (newest first); `flicker` marks a flip reverted within flip_hold_days. consensus counts components above neutral (score ≥ 45) and rising over 30 days, and reports independence.effective_rows — the participation ratio of first-difference correlations of the nine component scores over the trailing window (nine rows are fewer independent signals). days_missing declares calendar days without a snapshot. Free tier, no window cap (the source has ~2,850 daily rows).

## Query parameters

- `from` string, date
- `to` string, date
- `resolution` 'week' | 'day'

## Response `200`

Timeline container: rows[] (band per cell), flips[], consensus, coverage (days_total/days_missing).

- BtcCycleTimelineResponse
  - `as_of` string, date
  - `resolution` 'week' | 'day'
  - `from` string, date
  - `to` string, date
  - `data_start_date` string, date
  - `data_end_date` string, date
  - `days_total` integer: Calendar days from data_start_date to data_end_date, inclusive.
  - `days_missing` integer: Calendar days in that span without a snapshot row (measured, not assumed).
  - `flip_hold_days` integer: A flip reverted within this many days is marked flicker.
  - `bands` object: Score band [lo, hi) per label — the same signalFromScore() as the pulse tile.
  - `rows` object[]
    - `key` string: 'composite' or a component key (pi_top, pi_bot, mayer, rsi_w, ma200w, halving, fg, btc_dom, mining).
    - `label_de` string
    - `label_en` string
    - `short` string
    - `weight` number, nullable: Component weight in the composite (null for the composite row).
    - `cells` object[]
      - `date` string, date: Weekly resolution: the LAST available day of the ISO week.
      - `score` integer, nullable: Stored score 0–100, rounded; null = no snapshot / component not scored.
      - `band` 'accumulation' | 'recovery' | 'expansion' | 'distribution' | 'overheated' | 'null', nullable
  - `flips` object[]: Day-to-day band changes per row, newest first.
    - `date` string, date
    - `key` string
    - `from` string
    - `to` string
    - `score_from` number
    - `score_to` number
    - `flicker` boolean
  - `consensus` object
    - `as_of` string, date
    - `above_neutral` object
      - `n` integer
      - `of` integer
      - `keys` string[]
    - `rising_30d` object
      - `n` integer
      - `of` integer
      - `keys` string[]
    - `independence` object
      - `effective_rows` number, nullable: Participation ratio (Σλ)²/Σλ² of the eigenvalues of the correlation matrix of first differences of the component scores over window_days; null when fewer than 30 observations.
      - `nominal_rows` integer
      - `evaluated_rows` integer: Components with non-zero variance in the window.
      - `window_days` integer
      - `n_obs` integer
      - `basis` 'score_change'
  - `note` string

## Other responses

- `400`: Invalid input — fehlt Pflichtfeld oder Wert außerhalb des erlaubten Bereichs.
- `401`: Unauthenticated — kein gültiger Bearer-Token im Authorization-Header.
- `403`: Tier-Insufficient — Endpoint braucht höheren API-Tier. Response enthält upgrade_url.
- `404`: Not-Found — Resource existiert nicht oder gehört nicht dem aktuellen User.
- `429`: Rate-Limit überschritten — Tier-Quota (hourly/daily) oder Per-Endpoint-Quota erreicht. Retry-After-Header gesetzt.
- `500`: Internal Error.
- `503`: Upstream-Failure — Datenquelle nicht erreichbar (Binance, EODHD, etc.).

---

[API](https://skmtc.dev/tradingstrategies/apis/backtesting-arena-public-api.md) · [All operations](https://skmtc.dev/tradingstrategies/apis/backtesting-arena-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tradingstrategies/apis/backtesting-arena-public-api/revisions/f82e8d6eecd7?raw)