> For the complete documentation index, see [llms.txt](https://statalpha.gitbook.io/statalpha-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://statalpha.gitbook.io/statalpha-docs/stats/bos.md).

# BOS

The **Break of Structure (BOS)** identifies moments when the market shifts its structural trend —\
for example, when a new *Higher High* breaks a prior swing high, or a *Lower Low* breaks below the previous swing low.\
It is used to evaluate **trend continuation**, **reversals**, and the **strength of structural breakouts**.

***

## Concept

BOS events mark the moment price action breaks an existing structure level, indicating a possible change or continuation of market regime.

* **Bullish BOS:** Price breaks above a previous swing high following a higher low (HL → HH).
* **Bearish BOS:** Price breaks below a previous swing low following a lower high (LH → LL).
* Each BOS is tracked for up to **5 days** to evaluate follow-through and retracement behavior.

These statistics help quantify structure-based opportunities instead of relying purely on visual chart analysis.

***

## Parameters

| Parameter                 | Type    | Description                                                                                              |
| ------------------------- | ------- | -------------------------------------------------------------------------------------------------------- |
| `symbol`                  | string  | Symbol for the analyzed asset (e.g. `AAPL`, `BTCUSD`)                                                    |
| `start_date` / `end_date` | string  | Defines the custom date range for analysis (format `YYYY-MM-DD`)                                         |
| `time_window`             | string  | Predefined relative range (e.g. `1M`, `3M`, `12M`, `24M`, `5Y`). Ignored if explicit dates are provided. |
| `bos_minutes`             | integer | Bar resolution for structure detection (default `5`)                                                     |
| `pivot_bars`              | integer | Number of bars left/right used to detect pivot highs/lows (default `2`)                                  |
| `use_close`               | boolean | Use close prices (`true`) instead of highs/lows for BOS detection                                        |
| `start_time` / `end_time` | string  | Optional: Restrict analysis to intraday hours (e.g. `13:30` → `20:00`)                                   |
| `include_raw_data`        | boolean | When `true`, includes raw BOS event records in response                                                  |

***

## Example

```bash
curl -s \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://api.statalpha.market/stats/bos?symbol=AAPL&time_window=12M&bos_minutes=15&pivot_bars=2&use_close=true"
```

### Example Response (summary)

```json
{
  "symbol": "AAPL",
  "timeframe": "15min",
  "summary": {
    "total_bos_count": 384,
    "bullish_count": 192,
    "bearish_count": 192,
    "success_rate": 63.4,
    "avg_bos_range": 1.82,
    "avg_relative_follow_through_pct": 42.7,
    "avg_bos_duration_seconds": 58200
  },
  "parameters": {
    "pivot_bars": 2,
    "use_close": true,
    "time_window": "12M"
  }
}
```

***

## Interpretation

| Metric                                              | Meaning                                                                                          |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **success\_rate**                                   | Percentage of BOS patterns that achieved a meaningful follow-through without retracement failure |
| **avg\_bos\_range**                                 | Average price distance between BOS level and swing extreme                                       |
| **avg\_relative\_follow\_through\_pct**             | Average follow-through as % of BOS range                                                         |
| **avg\_bos\_duration\_seconds**                     | Average time a BOS pattern remained active                                                       |
| **retrace\_50\_pct\_share**                         | Share of BOS events where retracement exceeded 50% of the BOS range                              |
| **bullish\_success\_rate / bearish\_success\_rate** | Directional performance comparison                                                               |

***

## Endpoints

* `/stats/bos` — Returns aggregated BOS statistics summary
* `/stats/bos/raw` — Returns all detected BOS events including metadata
* `/stats/bos/doc` — Returns field documentation for both endpoints


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://statalpha.gitbook.io/statalpha-docs/stats/bos.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.