--- title: "Post-earnings-announcement drift (PEAD) conditioned on EPS surprise" method: GET path: "/api/v1/equities/{symbol}/earnings/pead" tags: ["Equities Indices"] --- # Post-earnings-announcement drift (PEAD) conditioned on EPS surprise `GET /api/v1/equities/{symbol}/earnings/pead` Post-earnings-announcement drift (PEAD) around the company's quarterly earnings announcements, conditioned on the EPS surprise. Announcement dates come from SEC 8-K item 2.02 filings; the surprise (BEAT/MISS/MEET) is joined by DATE from the fiscal earnings history (best-effort). Per event: OLS market-model fit on the estimation window [-250, -11] vs `market_proxy` (default SPY), daily abnormal returns over [0, +60], an immediate reaction CAR over [0, +1], and post-reaction drift CARs over [+2,+5], [+2,+20], [+2,+60] (filtered to those ending at or before `drift_window_end`). Events are bucketed by surprise (BEAT/MISS/MEET/UNKNOWN) and a BEAT-minus-MISS drift spread is reported. A drift window that runs past the next announcement's day-0 is flagged (overlaps_next_event) and excluded from the bucket aggregate, but still reported per event. Single-ticker PEAD over a handful of events is DESCRIPTIVE, not a significance test of a market-wide anomaly: per-bucket statistics are flagged exploratory and a small_sample_warning is set below 10 valid events. When the surprise source is unavailable the endpoint degrades to unconditional drift (conditioning_status=unavailable) rather than failing. Daily only (interval=1d). ## Path parameters - `symbol` string, required ## Query parameters - `lookback` integer — Number of most-recent earnings events to analyse (1-20, default 8). Bounds the OHLC history fetched and the per-request workload. - `market_proxy` string — Market-proxy ticker used as the OLS regressor. - `drift_window_end` integer — Largest drift-window end day (5..60). The drift windows [+2,+5],[+2,+20],[+2,+60] are filtered to those whose end <= this. - `include_daily_ar` boolean — Return per-event daily abnormal-return arrays over [0, +60]. Off by default to avoid response bloat. ## Response `200` Successful Response - EnvelopePeadPayload - `data` PeadPayload, required — Full PEAD response payload. - `symbol` string, required — Ticker as requested, normalized to upper case. - `market_proxy` string, required — Market-proxy ticker used as the OLS regressor (default SPY). - `interval` string, required — OHLC interval. Always `1d`. - `estimation_window` integer[], required — Estimation window in event-day offsets [start, end] (10-day leakage buffer before day 0). - `min_estimation_days` integer, required — Minimum estimation-window return rows required, else the event is skipped. - `reaction_window` integer[], required — Immediate-reaction window in event-day offsets [start, end]. - `drift_windows` array[], required — Post-reaction drift windows computed (inclusive event-day ranges), filtered to those ending at or before drift_window_end. - integer[] - `event_window` integer[], required — Full daily-AR window in event-day offsets [start, end]. - `include_daily_ar` boolean, required — Whether per-event daily_ar arrays are included. - `conditioning_status` string, required — Surprise conditioning: `available` (all events matched a surprise), `partial` (some matched), or `unavailable` (none matched, or the surprise source failed). - `coverage` object, required — Coverage counts: sec_events, valid_events, matched, unknown, unknown_by_reason, n_beat/n_miss/n_meet/n_unknown. - `events` PeadEventResult[], required — Per-event results (valid + skipped, in announcement order). - `announcement_date` string, nullable — Earnings announcement date from the SEC 8-K item 2.02 filing (`YYYY-MM-DD`). - `event_day0_date` string, nullable — Resolved event day-0 trading date (ISO 8601 UTC). Null when the event was skipped. - `period` string, nullable — SEC report/announcement (calendar) date carried by the filing (`YYYY-MM-DD`). Equals the announcement date; NOT a fiscal quarter-end. - `year` integer, nullable — Calendar year of the report/announcement date (NOT a fiscal year). - `quarter` integer, nullable — Calendar quarter (1-4) of the report/announcement date (NOT a fiscal quarter). - `filing_window` string, nullable — Announcement timing: BEFORE_OPEN / AFTER_HOURS / DURING_MARKET / null. - `event_timing_assumed` boolean, nullable — True when day-0 was assumed (DURING_MARKET or unknown filing window). - `surprise_label` string, nullable — BEAT / MISS / MEET from the joined EPS actual vs estimate. Null when no surprise was matched. - `surprise_pct` number, nullable — (actual - estimate) / abs(estimate). Null when the estimate is zero or non-finite, or no surprise was matched. - `surprise_period` string, nullable — The surprise-source FISCAL quarter-end (`YYYY-MM-DD`) matched to this announcement by date. Distinct from `period` (the calendar announcement date). - `surprise_lag_days` integer, nullable — Days between the matched fiscal quarter-end and the announcement date (announcement - surprise_period). - `surprise_match_status` string, nullable — `matched` when a fiscal surprise period was joined, else `unknown`. - `unknown_reason` string, nullable — Why no surprise was matched: no_surprise_in_window / ambiguous_surprise_period / surprise_period_already_matched / surprise_source_unavailable. Null when matched. - `bucket` string, nullable — Assigned surprise bucket: BEAT / MISS / MEET / UNKNOWN. - `market_model` MarketModelFit — OLS market-model fit over the estimation window for one event. - `alpha` number, required — OLS intercept (daily abnormal-return baseline). - `beta` number, required — OLS slope vs the market proxy. - `r_squared` number, required — Coefficient of determination (0-1). 0 when degenerate. - `n_obs` integer, required — Number of estimation-window return rows used. - `model_degenerate` boolean, required — True when the market regressor had zero variance (beta not identifiable, forced to 0). - `reaction_car` object, nullable — Immediate-reaction CAR keyed by window (e.g. `0_1`). Null/empty when the event was skipped. - `drift_car` object, nullable — Post-reaction drift CAR per window key (e.g. `2_5`, `2_20`, `2_60`). A value is null when the event is too recent for that window. - `overlaps_next_event` object, nullable — Per drift window: true when the window extends past the next (later) event's day-0. Overlapping windows are reported per-event but excluded from the bucket aggregate. - `daily_ar` number[], nullable — Per-day abnormal returns over [0, +60]. Only present when include_daily_ar=true. - `skip_reason` string, nullable — Why the event was excluded: missing_announcement_date / retrospective / announcement_outside_data / insufficient_history / event_too_recent_for_reaction. Null for valid events. - `by_bucket` object, required — Per-bucket drift aggregates keyed by bucket label (BEAT / MISS / MEET / UNKNOWN). - `pead_spread` PeadSpread[], required — BEAT-minus-MISS mean drift CAR per drift window (the PEAD headline). spread is null when conditioning is unavailable or a bucket is empty. - `drift_window` string, required — Drift window key (`_`, e.g. `2_60`). - `beat_mean_car` number, nullable — Mean drift CAR of the BEAT bucket for this window. Null when no BEAT events. - `miss_mean_car` number, nullable — Mean drift CAR of the MISS bucket for this window. Null when no MISS events. - `spread` number, nullable — beat_mean_car - miss_mean_car. Null when conditioning is unavailable or either bucket is empty for this window. - `n_beat` integer, required — BEAT events contributing to this window. - `n_miss` integer, required — MISS events contributing to this window. - `n_unknown` integer, required — UNKNOWN events contributing to this window (no surprise matched). - `small_sample_warning` boolean, required — True when fewer than 10 valid events were analysed (single-ticker PEAD is descriptive, not inferential). - `descriptive_note` string, required — Static note: single-ticker PEAD is descriptive, not a significance test of a market-wide anomaly. - `point_in_time_note` string, required — Static note: EPS actual/estimate values are not point-in-time, so the beat/miss classification can carry look-ahead bias. - `source` string — OHLC data source used. Currently always `sugra_finance`. - `meta` SugraMeta, required — Metadata attached to every /api/v1/* response envelope. - `endpoint` string, required — Requested endpoint path. - `data_time` string, required — ISO 8601 UTC timestamp of the source data, not of the request. - `response_time` string, required — ISO 8601 UTC timestamp when this response was produced. - `provider` string, required — API name and version. - `source` string, nullable — Identifier of the primary upstream source used for this response. - `attribution` string, nullable — Human-readable attribution mandated by an upstream source (e.g. a securities regulator or self-regulatory organization). Present only on responses whose source requires the owner and source to be clearly identified. Do not remove or alter it when using the response. - `fallback_used` boolean, nullable — True when the primary source failed and a fallback produced the data. - `fallback_chain` string[], nullable — Ordered list of sources attempted, in the order they were tried. - `cached` boolean, nullable — True when this response was served from the internal cache. - `stale` boolean, nullable — True when the cached response was returned after the upstream rate-limited or errored. Clients can use this to detect degraded data. ## Other responses - `401` — Missing or invalid `x-api-key` header. - `422` — Validation Error - `429` — Daily rate limit exceeded. Check `X-RateLimit-Reset` for the next window. - `503` — Upstream source is temporarily unavailable. Retry after a short delay. --- [API](https://skmtc.net/sugra/apis/sugra-api.md) · [All operations](https://skmtc.net/sugra/apis/sugra-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sugra/sugra-api/versions/dcf7427e6897/schema)