Skip to content
StatAlphaDocumentation

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.


  • 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.


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

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

Terminal window
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
"https://api.statalpha.io/stats/gap?symbol=AAPL&time_window=12M"
Terminal window
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
"https://api.statalpha.io/stats/gap/summary?symbol=AAPL&time_window=12M"
Terminal window
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
"https://api.statalpha.io/stats/gap/top-fills?symbol=TSLA&time_window=12M&top_n=5"

{
"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"
}

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.

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,weekday

Parameters 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.

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 requires open < previous_low. Equality at the opening boundary is not an event.
  • range_gap_size is 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_close is signed; close_gap_pct = 100 * close_gap_size / previous_close.
  • events.range_reentry reaches the near previous-day boundary; events.close_gap_fill reaches the previous close; events.previous_range_traversal reaches the opposite boundary. All touches are inclusive (low <= level for gap-up fills, high >= level for gap-down).
  • Top-level range_reentry, is_filled and close_gap_fill describe D0. Nested events describe the entire available requested horizon. is_filled remains the D0 range-reentry alias. gap_size and gap_pct retain 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. invalidation means 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.

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.

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.

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.