list_pass_windows
The dated access windows a pass plan generates, with their UUIDs — the ids a Pass Series is built from.
List the dated access windows on time-limited pass plans, with their UUIDs, status, local times and holder counts.
This is what makes a Pass Series authorable
create_plan with kind: pass_series takes
pass_series.window_ids. A series points at windows that already exist
rather than creating any of its own, so those UUIDs have to come from
somewhere — and this is the only tool that exposes them. Call it first, pick
the dates, then create the series.
It is also the tool for reconciling a schedule into an external calendar, and for checking what is actually still on sale before pointing a customer at a plan.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same action as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Annotations
It reads and never changes anything.
Arguments
plan_idstringoptionalUUID of one time-limited pass plan. Takes precedence over project_id.
project_idstringoptionalUUID of a project, to list windows across every pass plan on it.
statusstringoptionalFilter by lifecycle state: scheduled (not yet open), open (running now), closed (finished), canceled.
fromstringoptionalOnly windows starting at or after this ISO-8601 timestamp.
tostringoptionalOnly windows starting at or before this ISO-8601 timestamp.
limitintegeroptionalMaximum windows to return per page (1..100).
1max100pageintegeroptional1-indexed page number.
1What it returns
{ "data": [ { "id": "3d5a8c72-b016-4e94-8fa7-61c209d4e738", "plan_id": "pln_01HZ...", "plan_name": "Match Day Pass", "starts_at": "2026-09-20T13:00:00Z", "ends_at": "2026-09-20T16:00:00Z", "timezone": "America/New_York", "local_range": "Sun 20 Sep 2026, 09:00 – 12:00 EDT", "duration_minutes": 180, "status": "scheduled", "sellable": true, "holders": 12 } ], "meta": { "page": 1, "limit": 50, "total": 10, "has_more": false }}| Field | Type | Notes |
|---|---|---|
id | string UUID | The id a Pass Series points at. |
plan_id | string UUID | The pass plan the window belongs to. A series can draw from several. |
starts_at | ISO 8601 | Always UTC. |
ends_at | ISO 8601 | Always UTC. |
timezone | string | The zone the schedule was authored in. |
local_range | string | The window rendered in that zone, ready to show. See below. |
duration_minutes | integer | Length. Slots carry their own, so one plan can mix a 3-hour and a 14-hour window. |
status | string | scheduled, open, closed or canceled. |
sellable | boolean | Whether it is on sale right now, after applying the plan's sales cutoff. Not the same as status. |
holders | integer | How many purchases hold this window, series holders included. |
Both zones are returned on purpose
The UTC pair is what an integration stores. local_range is what the creator
authored and what a subscriber is shown — so an agent asked "which one is
Sunday's window" can answer without converting anything, and cannot get the
conversion wrong.
How it fails
TOKEN_MISSING_ABILITYtoken lacks pass-window:view-any (or the project-subscription-plan:view-any alias).
RESOURCE_NOT_FOUNDplan_id or project_id names something the token cannot see: unknown, another team's, or outside the token's scope:project: allow-list. Without either, the list spans only the projects the allow-list admits.
VALIDATION_FAILEDstatus is not one of scheduled, open, closed, canceled, or from / to is not a parseable timestamp (reason: not_a_timestamp).
status and sellable are different questions
A scheduled window is not necessarily buyable: the plan's sales cutoff may have closed it
already. An open window is not necessarily unbuyable either — a plan anchored to
before_end keeps selling while the window runs.
Filter on status to reason about the schedule. Read sellable to reason about what a
customer can actually buy.
Building a season ticket, end to end
list_planswithproject_id— find thekind: passplans to draw from.list_pass_windowswithplan_idand afrom/torange — collect the window UUIDs.create_planwithkind: pass_seriesand those ids inpass_series.window_ids.
Add a pass_series.rules entry in step 3 if the season should keep absorbing new windows as
they are scheduled — those are granted to existing holders automatically, at no charge.
How is this guide?
Last updated on