> 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/gap.md). # Gap The **Opening Gap (GAP)** analysis identifies situations where the market opens significantly above or below the previous day’s range.\ These events often represent strong sentiment shifts, news reactions, or temporary price inefficiencies.\ StatAlpha quantifies how often these gaps are filled, how long it takes, and under what conditions fills occur. *** ## Concept * **Gap Up:** Current day’s open is above the previous day’s high. * **Gap Down:** Current day’s open is below the previous day’s low. * A gap is considered **filled** once the price trades back into the previous day’s range. * Partial fills and full fills are tracked separately, including timing, percentage, and volume at the moment of fill. The algorithm automatically skips weekends and adjusts for session times (default `13:30`–`20:00` UTC). *** ## Parameters | Parameter | Type | Description | | ------------------------- | ------- | ------------------------------------------------------------------------------ | | `symbol` | string | Target symbol (e.g., `AAPL`, `BTCUSD`) | | `start_date` / `end_date` | string | Optional custom range (`YYYY-MM-DD`) | | `time_window` | string | Predefined relative range such as `1M`, `3M`, `6M`, `12M`, `24M`, `5Y` | | `start_time` / `end_time` | string | Defines intraday session boundaries (default `13:30`–`20:00` UTC) | | `fill_cutoff` | string | Optional UTC time (e.g. `16:30`) limiting the observation window for gap fills | | `top_n` | integer | Used by `/top` and `/top-fills` endpoints to limit results | *** ## Endpoints | Endpoint | Description | | -------------------------- | ------------------------------------------------------------------------------------------------------------------ | | `GET /stats/gap` | Returns raw daily gap detections for the given symbol and range | | `GET /stats/gap/summary` | Aggregated statistics for all detected gaps, including direction, weekday breakdown, and partial fill distribution | | `GET /stats/gap/top` | Lists the largest gaps (by size or % change) in the selected period | | `GET /stats/gap/top-fills` | Lists the fastest full gap fills sorted by fill duration | | `GET /stats/gap/doc` | Returns field documentation for all gap endpoints | *** ## Example Requests ### 1. Retrieve raw gap detections ```bash curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \ "https://api.statalpha.market/stats/gap?symbol=AAPL&time_window=12M" ``` ### 2. Summary of all detected gaps ```bash curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \ "https://api.statalpha.market/stats/gap/summary?symbol=AAPL&time_window=12M" ``` ### 3. Top 5 fastest gap fills ```bash curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \ "https://api.statalpha.market/stats/gap/top-fills?symbol=TSLA&time_window=12M&top_n=5" ``` *** ## Example Response (summary excerpt) ```json { "symbol": "AAPL", "total_gaps": 182, "filled_gaps": 116, "fill_rate": 63.7, "avg_gap_size": 1.12, "avg_gap_pct": 0.84, "avg_fill_time_seconds": 14200, "avg_partial_fill_pct": 71.3, "gap_direction_stats": { "up": {"count": 92, "fill_rate": 67.4, "avg_gap_pct": 0.93}, "down": {"count": 90, "fill_rate": 59.8, "avg_gap_pct": 0.76} }, "weekday_breakdown": { "Monday": {"count": 36, "fill_rate": 61.1}, "Tuesday": {"count": 32, "fill_rate": 68.8} }, "partial_fill_distribution": { "0%": 14, "1-25%": 27, "26-50%": 33, "51-75%": 41, "76-99%": 23, "100%": 44 }, "time_window": "12M" } ``` *** ## Interpretation | Metric | Meaning | | ---------------------------------- | --------------------------------------------------------------------------- | | **fill\_rate** | Percentage of all gaps that were fully filled within the observation period | | **avg\_gap\_size / avg\_gap\_pct** | Average absolute and relative size of all detected gaps | | **avg\_fill\_time\_seconds** | Average number of seconds until full fill (only for filled gaps) | | **avg\_partial\_fill\_pct** | Average degree of partial fills (unfilled + filled combined) | | **gap\_direction\_stats** | Split statistics by direction (`up`/`down`) | | **weekday\_breakdown** | Fill-rate tendencies by day of week | | **partial\_fill\_distribution** | Histogram of how completely each gap was filled | *** ## Notes * Gap detection automatically adjusts for weekends and non-trading hours. * All calculations are based on aggregated intraday bar data. * Cached responses ensure consistent performance for repeated queries. * Query flexibility (custom date ranges, cutoff times, etc.) depends on the active plan. --- # 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/gap.md?ask=&goal= ``` `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.