list_pass_windows

The dated access windows a pass plan generates, with their UUIDs — the ids a Pass Series is built from.

Purpose

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.

Required ability

pass-window:view-any — a token holding project-subscription-plan:view-any also satisfies it, because this list gated on the plan ability before the pass-window family had a surface of its own.

Input schema

{
  "type": "object",
  "properties": {
    "plan_id": {
      "type": "string",
      "description": "UUID of one time-limited pass plan. Takes precedence over project_id."
    },
    "project_id": {
      "type": "string",
      "description": "UUID of a project, to list windows across every pass plan on it."
    },
    "status": {
      "type": "string",
      "description": "Filter by lifecycle state: scheduled, open, closed, canceled."
    },
    "from": {
      "type": "string",
      "description": "Only windows starting at or after this ISO-8601 timestamp."
    },
    "to": {
      "type": "string",
      "description": "Only windows starting at or before this ISO-8601 timestamp."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Maximum windows to return per page (1..100)."
    },
    "page": {
      "type": "integer",
      "minimum": 1,
      "description": "1-indexed page number."
    }
  }
}

Output shape

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

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

Example prompts

"List the upcoming windows on plan pln_01HZ... so I can build a season ticket from them."

"Which pass windows on project 7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13 are still on sale this month?"

"How many people hold the window on 20 September?"

Building a season ticket, end to end

list_plans with project_id — find the kind: pass plans to draw from.
list_pass_windows with plan_id and a from/to range — collect the window UUIDs.
create_plan with kind: pass_series and those ids in pass_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.

Failure modes

TOKEN_MISSING_ABILITY — token lacks pass-window:view-any (or the project-subscription-plan:view-any alias).
RESOURCE_NOT_FOUND — plan_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_FAILED — status is not one of scheduled, open, closed, canceled, or from / to is not a parseable timestamp (reason: not_a_timestamp).

create_plan — where these ids are used.
list_plans
Plans API
Pass Series guide

list_pass_windows

On this page