--- title: "Cross-sectional PEAD leaderboard of recent BEAT/MISS earnings announcers" method: GET path: "/api/v1/equities/pead/leaderboard" tags: ["Equities Indices"] --- # Cross-sectional PEAD leaderboard of recent BEAT/MISS earnings announcers `GET /api/v1/equities/pead/leaderboard` Ranks RECENT S&P 500 earnings announcers (within `window_days`) by EPS surprise magnitude, split into a BEAT long side and a MISS short side. Recent announcers are seeded from the market-wide earnings calendar (rows with both an EPS actual and estimate, intersected with the S&P 500 constituent universe), bucketed by the same BEAT/MISS thresholds as the per-ticker PEAD endpoint, then CONFIRMED against each company's SEC 8-K item 2.02 filing (accepted only when a filing date matches the calendar date within +-1 day). Confirmed candidates are measured against a shared market proxy: an immediate reaction CAR over [0, +1] and a realized drift-to-date CAR over [+2, min(elapsed, +20)]. Candidates are ranked by the SURPRISE (the conditioning variable known at announcement time), NOT by realized drift, which is reported as descriptive evidence only. This is a small cross-section of one recent window - descriptive, not a backtest of the PEAD anomaly. Candidates that cannot be confirmed against SEC filings, or that lack sufficient price history, are excluded and counted in diagnostics rather than failing the request. ## Query parameters - `window_days` integer — Recent-announcer lookback in calendar days (1-21, default 7). - `limit` integer — Maximum entries per side (BEAT long / MISS short), 1-25, default 10. - `market_proxy` string — Market-proxy ticker used as the OLS regressor for every candidate. ## Response `200` Successful Response - EnvelopePeadLeaderboardPayload - `data` PeadLeaderboardPayload, required — Cross-sectional PEAD leaderboard of recent BEAT/MISS announcers. - `window_days` integer, required — Recent-announcer lookback in calendar days (the seed calendar covers [today - window_days, today]). - `as_of` string, required — Calendar to-date used as the recent-window upper bound (`YYYY-MM-DD`, today UTC). - `universe` string — Candidate universe the recent announcers were intersected with. Always `sp500_constituents`. - `market_proxy` string, required — Market-proxy ticker used as the OLS regressor for every candidate (default SPY). - `candidates_seeded` integer, required — Recent calendar announcers (with actual+estimate, in the universe) before the candidate cap. - `candidates_confirmed` integer, required — Seeded candidates whose announcement date was confirmed against an SEC 8-K item 2.02 filing within +-1 day. - `candidates_measured` integer, required — Confirmed candidates with sufficient price history to compute a reaction CAR. - `excluded_unconfirmed` integer, required — Candidates dropped because no SEC 8-K item 2.02 date matched (or the SEC fetch raised). The request still succeeds. - `excluded_no_prices` integer, required — Confirmed candidates dropped because OHLC history was insufficient for the reaction CAR. - `long_candidates` PeadLeaderboardEntry[], required — BEAT announcers sorted by |surprise_pct| descending, trimmed to `limit`. - `symbol` string, required — Ticker, normalized to upper case. - `announce_date` string, nullable — SEC-confirmed announcement date from the 8-K item 2.02 filing (`YYYY-MM-DD`). - `surprise_pct` number, nullable — (actual - estimate) / abs(estimate). The ranking key (descending by magnitude within each side). Null when the estimate is zero or non-finite. - `bucket` string, required — Surprise bucket: BEAT or MISS (MEET/UNKNOWN are dropped before ranking). - `reaction_car_0_1` number, nullable — Immediate-reaction CAR over event days [0, +1] vs the market proxy. Null when price history is insufficient. - `drift_car_to_date` number, nullable — Realized post-reaction drift CAR over [+2, min(elapsed, +20)]. DESCRIPTIVE evidence, NOT the sort key. Null when fewer than 3 post-reaction trading days have elapsed. - `drift_days_elapsed` integer, nullable — Number of trading days elapsed since day 0 used for the drift-to-date window end (capped at 20). - `short_candidates` PeadLeaderboardEntry[], required — MISS announcers sorted by |surprise_pct| descending, trimmed to `limit`. - `symbol` string, required — Ticker, normalized to upper case. - `announce_date` string, nullable — SEC-confirmed announcement date from the 8-K item 2.02 filing (`YYYY-MM-DD`). - `surprise_pct` number, nullable — (actual - estimate) / abs(estimate). The ranking key (descending by magnitude within each side). Null when the estimate is zero or non-finite. - `bucket` string, required — Surprise bucket: BEAT or MISS (MEET/UNKNOWN are dropped before ranking). - `reaction_car_0_1` number, nullable — Immediate-reaction CAR over event days [0, +1] vs the market proxy. Null when price history is insufficient. - `drift_car_to_date` number, nullable — Realized post-reaction drift CAR over [+2, min(elapsed, +20)]. DESCRIPTIVE evidence, NOT the sort key. Null when fewer than 3 post-reaction trading days have elapsed. - `drift_days_elapsed` integer, nullable — Number of trading days elapsed since day 0 used for the drift-to-date window end (capped at 20). - `methodology` string, required — Static methodology note: seed -> SEC-confirm -> measure; surprise is the sort key, realized drift is descriptive. - `descriptive_note` string, required — Static note: a small recent-window cross-section is descriptive, not a backtest of the PEAD anomaly. - `source` string — OHLC data source used. 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/revisions/4e2740743eb4/schema)