> 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/api-reference/fvg.md).

# FVG

Fair Value Gap statistics

## GET /stats/fvg

> Fvg Raw

```json
{"openapi":"3.1.0","info":{"title":"StatAlpha API","version":"0.4.0"},"tags":[{"name":"FVG","description":"Fair Value Gap statistics"}],"paths":{"/stats/fvg":{"get":{"tags":["FVG"],"summary":"Fvg Raw","operationId":"fvg_raw_stats_fvg_get","parameters":[{"name":"symbol","in":"query","required":true,"schema":{"type":"string","title":"Symbol"}},{"name":"timeframe","in":"query","required":false,"schema":{"type":"string","description":"Candle TF: '1m','5m','10m','15m','30m','1H','1D','1W' or custom '17m','2H','3D','2W'","default":"15m","title":"Timeframe"},"description":"Candle TF: '1m','5m','10m','15m','30m','1H','1D','1W' or custom '17m','2H','3D','2W'"},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"YYYY-MM-DD","title":"Start Date"},"description":"YYYY-MM-DD"},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"YYYY-MM-DD","title":"End Date"},"description":"YYYY-MM-DD"},{"name":"time_window","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Relative window (e.g. '6M','12M','24M','5Y')","default":"12M","title":"Time Window"},"description":"Relative window (e.g. '6M','12M','24M','5Y')"},{"name":"start_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"UTC HH:MM (intraday only)","default":"13:30","title":"Start Time"},"description":"UTC HH:MM (intraday only)"},{"name":"end_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"UTC HH:MM (intraday only)","default":"20:00","title":"End Time"},"description":"UTC HH:MM (intraday only)"},{"name":"include_extended_hours","in":"query","required":false,"schema":{"type":"boolean","description":"Include pre/post-market data","default":false,"title":"Include Extended Hours"},"description":"Include pre/post-market data"},{"name":"max_bars_to_close","in":"query","required":false,"schema":{"type":"integer","description":"0 = no limit; otherwise cap lookahead to N bars","default":50,"title":"Max Bars To Close"},"description":"0 = no limit; otherwise cap lookahead to N bars"},{"name":"use_close_prices","in":"query","required":false,"schema":{"type":"boolean","description":"Use CLOSE-based touch/fill logic instead of wicks","default":false,"title":"Use Close Prices"},"description":"Use CLOSE-based touch/fill logic instead of wicks"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## GET /stats/fvg/summary

> Fvg Summary

```json
{"openapi":"3.1.0","info":{"title":"StatAlpha API","version":"0.4.0"},"tags":[{"name":"FVG","description":"Fair Value Gap statistics"}],"paths":{"/stats/fvg/summary":{"get":{"tags":["FVG"],"summary":"Fvg Summary","operationId":"fvg_summary_stats_fvg_summary_get","parameters":[{"name":"symbol","in":"query","required":true,"schema":{"type":"string","title":"Symbol"}},{"name":"timeframe","in":"query","required":false,"schema":{"type":"string","default":"15m","title":"Timeframe"}},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"YYYY-MM-DD","title":"Start Date"},"description":"YYYY-MM-DD"},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"YYYY-MM-DD","title":"End Date"},"description":"YYYY-MM-DD"},{"name":"time_window","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":"12M","title":"Time Window"}},{"name":"start_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"UTC HH:MM (intraday only)","default":"13:30","title":"Start Time"},"description":"UTC HH:MM (intraday only)"},{"name":"end_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"UTC HH:MM (intraday only)","default":"20:00","title":"End Time"},"description":"UTC HH:MM (intraday only)"},{"name":"include_extended_hours","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Extended Hours"}},{"name":"max_bars_to_close","in":"query","required":false,"schema":{"type":"integer","description":"0 = no limit; otherwise cap lookahead to N bars","default":50,"title":"Max Bars To Close"},"description":"0 = no limit; otherwise cap lookahead to N bars"},{"name":"use_close_prices","in":"query","required":false,"schema":{"type":"boolean","description":"Use CLOSE-based touch/fill logic instead of wicks","default":false,"title":"Use Close Prices"},"description":"Use CLOSE-based touch/fill logic instead of wicks"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## GET /stats/fvg/top

> Fvg Top

```json
{"openapi":"3.1.0","info":{"title":"StatAlpha API","version":"0.4.0"},"tags":[{"name":"FVG","description":"Fair Value Gap statistics"}],"paths":{"/stats/fvg/top":{"get":{"tags":["FVG"],"summary":"Fvg Top","operationId":"fvg_top_stats_fvg_top_get","parameters":[{"name":"symbol","in":"query","required":true,"schema":{"type":"string","title":"Symbol"}},{"name":"timeframe","in":"query","required":false,"schema":{"type":"string","default":"15m","title":"Timeframe"}},{"name":"direction","in":"query","required":false,"schema":{"type":"string","description":"'bullish' or 'bearish'","default":"bullish","title":"Direction"},"description":"'bullish' or 'bearish'"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":5,"title":"Limit"}},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"YYYY-MM-DD","title":"Start Date"},"description":"YYYY-MM-DD"},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"YYYY-MM-DD","title":"End Date"},"description":"YYYY-MM-DD"},{"name":"time_window","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":"12M","title":"Time Window"}},{"name":"start_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"UTC HH:MM (intraday only)","default":"13:30","title":"Start Time"},"description":"UTC HH:MM (intraday only)"},{"name":"end_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"UTC HH:MM (intraday only)","default":"20:00","title":"End Time"},"description":"UTC HH:MM (intraday only)"},{"name":"include_extended_hours","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Extended Hours"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## Fvg Multi Top

> Return the strongest filled/advanced FVGs across multiple symbols, sorted by\
> fill\_ratio desc, then bars\_to\_full\_fill asc, then gap\_size desc.

```json
{"openapi":"3.1.0","info":{"title":"StatAlpha API","version":"0.4.0"},"tags":[{"name":"FVG","description":"Fair Value Gap statistics"}],"paths":{"/stats/fvg/multi_top":{"get":{"tags":["FVG"],"summary":"Fvg Multi Top","description":"Return the strongest filled/advanced FVGs across multiple symbols, sorted by\nfill_ratio desc, then bars_to_full_fill asc, then gap_size desc.","operationId":"fvg_multi_top_stats_fvg_multi_top_get","parameters":[{"name":"symbols","in":"query","required":true,"schema":{"type":"string","description":"Comma-separated list of symbols, e.g. AAPL,TSLA,MSFT","title":"Symbols"},"description":"Comma-separated list of symbols, e.g. AAPL,TSLA,MSFT"},{"name":"timeframe","in":"query","required":false,"schema":{"type":"string","default":"15m","title":"Timeframe"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":50,"title":"Limit"}},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"YYYY-MM-DD","title":"Start Date"},"description":"YYYY-MM-DD"},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"YYYY-MM-DD","title":"End Date"},"description":"YYYY-MM-DD"},{"name":"time_window","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":"12M","title":"Time Window"}},{"name":"start_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"UTC HH:MM (intraday only)","default":"13:30","title":"Start Time"},"description":"UTC HH:MM (intraday only)"},{"name":"end_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"UTC HH:MM (intraday only)","default":"20:00","title":"End Time"},"description":"UTC HH:MM (intraday only)"},{"name":"include_extended_hours","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Extended Hours"}},{"name":"max_bars_to_close","in":"query","required":false,"schema":{"type":"integer","description":"0 = no limit; otherwise cap lookahead to N bars","default":50,"title":"Max Bars To Close"},"description":"0 = no limit; otherwise cap lookahead to N bars"},{"name":"use_close_prices","in":"query","required":false,"schema":{"type":"boolean","description":"Use CLOSE-based touch/fill logic instead of wicks","default":false,"title":"Use Close Prices"},"description":"Use CLOSE-based touch/fill logic instead of wicks"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```

## GET /stats/fvg/doc

> Fvg Doc

```json
{"openapi":"3.1.0","info":{"title":"StatAlpha API","version":"0.4.0"},"tags":[{"name":"FVG","description":"Fair Value Gap statistics"}],"paths":{"/stats/fvg/doc":{"get":{"tags":["FVG"],"summary":"Fvg Doc","operationId":"fvg_doc_stats_fvg_doc_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}}}
```

## GET /stats/fvg/\_debug

> Fvg Debug

```json
{"openapi":"3.1.0","info":{"title":"StatAlpha API","version":"0.4.0"},"tags":[{"name":"FVG","description":"Fair Value Gap statistics"}],"paths":{"/stats/fvg/_debug":{"get":{"tags":["FVG"],"summary":"Fvg Debug","operationId":"fvg_debug_stats_fvg__debug_get","parameters":[{"name":"symbol","in":"query","required":true,"schema":{"type":"string","title":"Symbol"}},{"name":"timeframe","in":"query","required":false,"schema":{"type":"string","default":"15m","title":"Timeframe"}},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Start Date"}},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"End Date"}},{"name":"time_window","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":"12M","title":"Time Window"}},{"name":"include_extended_hours","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Extended Hours"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}
```


---

# 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/api-reference/fvg.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.