Screen sessions
screen_sessionsFilter the finished SPX sessions in the FirmTape archive by their closing measurements and count them: regime at the close and at the open, zero-gamma flip crossings, whether the expected-hold band held, direction and size of the move, net-gamma percentile, 0DTE ATM IV at the open, the calendar event, weekday and year. Returns how many sessions match, three shares over them (closed above the flip, band held, mean absolute move) printed next to the same shares over the whole archive, and the matched days. A matched share close to the archive's share is a base rate, not a pattern. Use when: 'how often did FOMC days close in negative gamma', 'the days the band broke with the percentile under 20', 'largest moves on CPI days since 2024'. Not for: one day's numbers (get_session), gamma by strike (get_gex_profile), or testing a rule with out-of-sample statistics (the Lab). Limits: counts over finished sessions' closing measurements only, no per-strike data; at most 50 sessions listed per call. Counts, not investment advice.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| iv | No | 0DTE ATM implied vol at the open: under 10%, 10-15%, 15-20%, 20% and above | |
| dir | No | Direction of the open-to-close move | |
| dow | No | Day of the week | |
| band | No | Whether the expected-hold band held all session | |
| gpct | No | Net-gamma percentile at the close: under 20, 20 to 50, 50 to 80, 80 and above | |
| move | No | Size of the open-to-close move: under 0.5%, 0.5% or more, 1% or more, 2% or more | |
| open | No | Regime at the open: pos = opened above the flip, neg = below | |
| sort | No | Order of the sessions list: newest (default), oldest, move (largest absolute move first), gpct (highest percentile first) | |
| year | No | Calendar year, e.g. 2025; a year outside the archive is dropped | |
| cross | No | Flip crossings in the session: 0 = none, 1 = exactly one, 2 = two or more | |
| event | No | Event the day carried: fomc (decision days), cpi, nfp (payrolls), pce, ppi, gdp, retail (retail sales), jolts, ism, claims, auctions (Treasury), fed (speeches, Beige Book), opex (expiration), vix (VIX settlement), umich, confidence, eia, halts (halt in a top name), housing (housing and durables), refunding, rebalances (index), none (no event of these kinds) | |
| limit | No | How many matched sessions to list (default 20, max 50); the counts always cover every match | |
| regime | No | Regime at the close: pos = closed above the zero-gamma flip, neg = below |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The /screener page that shows the same result to a person | |
| label | Yes | The filters in words | |
| shares | Yes | The same three shares over the matched sessions and over the whole archive; a matched share close to the archive's is a base rate, not a pattern | |
| source | No | ||
| filters | No | The filters the screener accepted; a value outside the vocabulary is dropped, not an error | |
| matched | Yes | Sessions matching every filter | |
| summary | Yes | One sentence carrying this answer's numbers, its trading day and its source, written to be quoted verbatim to a reader rather than paraphrased. | |
| archived | Yes | Finished sessions in the archive | |
| screened | Yes | Sessions whose closing measurements were available to screen | |
| sessions | Yes | Matched sessions in the requested order (default newest first), at most `limit` | |
| truncated | Yes | True when more sessions matched than `sessions` carries | |
| question_url | No | When the filters are one of the screener's common questions, that question's own page (e.g. /screener/negative-gamma-closes), the address to cite |