GAP — Opening Gaps
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
Section titled “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 default US equity session follows New York market hours; its UTC times change with daylight saving time.
Parameters
Section titled “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 in UTC; the default follows US equity market hours |
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
Section titled “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
Section titled “Example Requests”1. Retrieve raw gap detections
Section titled “1. Retrieve raw gap detections”curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \ "https://api.statalpha.io/stats/gap?symbol=AAPL&time_window=12M"2. Summary of all detected gaps
Section titled “2. Summary of all detected gaps”curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \ "https://api.statalpha.io/stats/gap/summary?symbol=AAPL&time_window=12M"3. Top 5 fastest gap fills
Section titled “3. Top 5 fastest gap fills”curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \ "https://api.statalpha.io/stats/gap/top-fills?symbol=TSLA&time_window=12M&top_n=5"Example Response (summary excerpt)
Section titled “Example Response (summary excerpt)”{ "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
Section titled “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 |
- Gap detection automatically adjusts for weekends and non-trading hours.
- All calculations are based on aggregated intraday bar data.
- Query flexibility (custom date ranges, cutoff times, etc.) depends on the active plan.
Multi-session GAP definition v2
Section titled “Multi-session GAP definition v2”Use definition_version=2 on GET /stats/gap or GET
/stats/gap/summary. Both return the same reproducible envelope: data
contains every included raw event, summary.up and summary.down contain
separate populations, and segments contains the requested joint grouping.
The web GAP raw/summary forms select v2 by default. Existing API clients remain
on v1 unless they opt in. /top and /top-fills retain their v1 contract.
In v1, “filled” means intraday range re-entry, not previous-close fill.
GET /stats/gap/summary?symbol=AAPL&definition_version=2&time_window=12M&horizons=0,1,2,3,5,10,20&percentiles=10,25,50,75,90&benchmark_symbol=SPY&segment_by=direction,weekdayParameters shared by the raw and summary endpoints:
| Parameter | Default | Meaning |
|---|---|---|
definition_version |
1 |
Opt in with 2; legacy responses remain unchanged. |
start_date, end_date, time_window |
existing entitlement rules | Event population and observation end. Maximum v2 span: ten years. |
horizons |
0,1,2,3,5,10,20 |
Trading-session offsets, integers 0–20. |
percentiles |
10,25,50,75,90 |
Any requested percentiles strictly between 0 and 100. |
atr_targets |
1,2 |
Positive ATR target multiples, maximum 100. |
minimum_sample |
20 |
Marks small populations; never hides them. |
benchmark_symbol |
SPY |
Explicit equity benchmark; empty string disables it. |
sector_symbol |
none | Optional explicitly chosen sector ETF, never inferred. |
segment_by |
direction |
Comma-separated joint dimensions below. |
segment_filters |
{} |
JSON equality filters on those dimensions. |
corporate_action_dates |
empty | Verified ex-dates on the source-price basis, comma-separated ISO dates. |
event_session_labels |
{} |
Verified ISO session dates mapped to earnings, event or unclassified. |
V2 rejects custom UTC sessions and fill_cutoff: its units require complete
exchange sessions. V1 continues to support those options. V2 supports US equity
symbols, with the NYSE regular-session calendar. It is not a crypto/FX calendar.
Price and event references
Section titled “Price and event references”Event-definition version: gap-rth-2.0.0. The NYSE trading calendar determines holidays, early closes and UTC conversion.
- Session bars are minute-start timestamps in UTC, open inclusive, close exclusive. Exchange holidays, shortened sessions and New York DST determine the expected minute grid. No forward-fill or weekend interpolation occurs.
- The predecessor is the preceding scheduled trading session, not the previous calendar date or merely the last day with available data. Its full regular session provides high, low and last-minute close. “Previous close” here means that bar’s close; no separate official auction-price feed is assumed.
- A gap-up requires
open > previous_high; a gap-down requiresopen < previous_low. Equality at the opening boundary is not an event. range_gap_sizeis a positive distance to the relevant previous high/low;range_gap_pct = 100 * range_gap_size / previous_close(the v1 denominator).close_gap_size = open - previous_closeis signed;close_gap_pct = 100 * close_gap_size / previous_close.events.range_reentryreaches the near previous-day boundary;events.close_gap_fillreaches the previous close;events.previous_range_traversalreaches the opposite boundary. All touches are inclusive (low <= levelfor gap-up fills,high >= levelfor gap-down).- Top-level
range_reentry,is_filledandclose_gap_filldescribe D0. Nestedeventsdescribe the entire available requested horizon.is_filledremains the D0 range-reentry alias.gap_sizeandgap_pctretain aliases. Raw v2 is a versioned migration, not an exact v1 row-shape replacement. - Timestamps identify the first eligible minute, not the exact trade time.
A touch already true at the minute open precedes a later intrabar touch;
otherwise simultaneous different levels produce
ambiguous. No invented OHLC traversal order is used.invalidationmeans the opposite previous-day range boundary. Coincident semantic levels remain explicitly ambiguous.
Observation, missing data and corporate actions
Section titled “Observation, missing data and corporate actions”The lookback selects gap dates; end_date also bounds observation. D+1 is
the next scheduled trading session after D0, not 24 hours. Extending the end date
explicitly extends follow-up and the eligible event cohort. No future prices
are fetched to make a recent horizon appear complete. Up to 100 calendar days
before the start provide predecessor/ATR/trend context; no events from that
context enter the population.
Every expected minute must have one valid, finite, positive OHLC bar with
consistent high/low and non-negative finite volume. Duplicate timestamps are
invalid. A missing open or incomplete predecessor excludes event detection and
increments excluded_event_sessions. A hole, suspected halt, invalid minute,
uncompleted current minute or missing session stops the contiguous observation
path. Later bars cannot establish what happened inside that hole. Observed
touches before the hole are preserved; unknown later outcomes are null, not
losses or unfilled observations. Halts cannot currently be distinguished from
missing trades/feed gaps, so the conservative rule is identical.
Known corporate-action ex-dates exclude events on that date and censor paths
before crossing it. ATR and trend history restart after a supplied action.
The available source prices do not include a verified adjustment or corporate-action ledger. V2 does not infer splits/dividends from price jumps
or claim the series is adjusted. data_quality.price_adjustment exposes this
limitation, including when a caller supplies dates. Results without a verified
complete action list are descriptive source-price statistics, not a validated
corporate-action-neutral screening dataset.
Earnings dates without reliable announcement-to-opening-session attribution
remain unclassified. Callers can provide verified event_session_labels;
no causal event attribution or AI classification is inferred. The optional
sector ETF is user-selected. Missing optional benchmark/sector tables or bars
yield null relative returns; the primary symbol’s GAP analysis continues.
data_quality.benchmark_available / sector_available are false when that
comparison has no complete sessions; missing benchmark direction is unavailable.
Errors affecting the primary symbol are reported rather than treated as empty populations.
data_freshness exposes computation time and the latest loaded
source bar; this is not a vendor ingestion watermark.
Survival and distributions
Section titled “Survival and distributions”Discrete Kaplan–Meier is calculated separately for each direction and segment.
An event at D+h is a failure at h; an open event exits after its last complete
observed session. It is never dropped from the starting population. Curves
include at-risk and censored counts, cumulative fill and survival percentages,
and approximate Greenwood 95% survival intervals. Unsupported tails return
null; survival zero remains zero. With no observation at D0, the non-event
cannot enter the D0 risk set. Censoring assumes non-informative withdrawal;
missing-feed censoring may violate that assumption and must be considered when
interpreting results. median_sessions and percentile_sessions are from the
survival curve and remain null when not reached. The separately named
observed_time_distribution summarizes observed hits only and is not a
censor-adjusted estimate of eventual fill time.
Numerical distributions have median, population standard deviation, Q1, Q3
and linearly interpolated configurable percentiles. Each has sample_count,
eligible_event_count, missing_data_count and insufficient_data. Binomial
probabilities carry explicit numerator/denominator and Wilson 95% intervals.
Ambiguous or censored outcomes are excluded from binary denominators, with
missing counts exposed. First-touch outcome distributions include an explicit
ambiguous category. No small cell is silently pooled across direction.
Outcome definitions
Section titled “Outcome definitions”For each requested D+h, from_open starts at the gap open and from_close
starts after the gap-day close; its D0 excursion/return is zero. MFE and
MAE are non-negative in gap direction. Their high/low path includes intervening
regular sessions and overnight changes observed at the next open. Incomplete
paths have null excursion/return objects. Units: price, percent of reference,
prior ATR multiple, and range-gap multiple.
ATR is the arithmetic mean of the 14 true ranges preceding the gap, using 15
complete previous sessions (not Wilder smoothing). Forward returns are signed
price changes and percentages independent of gap direction;
directional_return_pct additionally applies the gap sign. Relative returns
subtract benchmark/sector percentage returns over identical origin/end
sessions (percentage-point difference). Comparisons are price returns, not
reinvested total returns.
Targets are 0.5, 1, 1.5 and 2 times the range gap, plus requested ATR multiples,
in gap direction from the open. Each target exposes first touch, time-to-target,
and target-before-range-reentry/previous-close-fill outcomes. First-touch labels
are target, range_reentry, previous_close, invalidation,
horizon_expiry, ambiguous or censored.
Structure includes gap-day open-to-close return, close location (0–1), wick ratios, range/ATR, signed distances from the close to previous high/low/close and current open. Relative volume uses the prior 20 complete session volumes without early-close duration normalization. Gap hold means a close strictly outside the old range in gap direction. Consecutive closes start at D0 and include a censor flag. First retest is range re-entry; retest hold requires the retest session’s complete close back outside the range. A new high/low strictly exceeds the gap-day extreme after D0; its ordering is measured against each fill event independently.
Segments and reproducibility
Section titled “Segments and reproducibility”Dimensions: direction, weekday, gap_pct_bucket (1/2/5%), gap_atr_bucket
(0.5/1/2 ATR), gap_multiple_bucket (absolute close gap divided by range gap;
1/1.5/2/3), prior 5/20/50-session close trend (up/down/flat),
volatility_regime (prior ATR as percent of previous close, boundaries 1/2/4%),
D0 benchmark open-to-close direction, and verified event class. Buckets are
lower-inclusive and upper-exclusive; unavailable history is a separate cell.
D0 benchmark direction is descriptive and not a pre-open signal. Lookback is
the request’s explicit population. Joint cells expose the same complete
metrics and sample diagnostics as direction summaries.
data is preserved in both responses: re-aggregating it with the included
configuration reproduces all summaries and cells. UI distinguishes the two
cumulative fills, still-open survival, sample size, distribution quantiles,
observation end, algorithm version and source-quality limitations. Raw JSON,
all outcomes and segment populations are expandable for inspection.