List a project's plans

Pages the project's plans, every kind together, newest first. Read kind on each row to know which of billing, pass or pass_series it carries; resources is loaded on every row. pass.upcoming_windows is not served here: the pass windows endpoints list a plan's dates.

Requires ability

project-subscription-plan:view-any

The token must hold this ability, or the call is refused with 403.

MCP tool

list_plans

Runs the same action from an agent, behind the same ability.

Authorization

bearerToken

AuthorizationBearer <token>

A personal access token minted on the dashboard under Settings, then Tokens, sent as Authorization: Bearer sbt_live_…. The token carries the abilities each endpoint lists under Requires ability and is frozen to one team.

In: header

Path Parameters

project*string

The project, resolved by the route binder.

Formatuuid

Query Parameters

page?integer

The 1-based page to return. A page past the last answers an empty data array with meta.total still filled, so a loop can stop without guessing.

Range1 <= value

Default1

per_page?integer

Rows per page, 1 to 100. A higher value clamps to the cap silently. Defaults to 25.

Range1 <= value <= 100

Default25

sort_by?string

The column to order by. Defaults to created_at; a column the endpoint does not offer falls back to the default rather than failing.

Default"created_at"

sort_direction?string

asc or desc. Defaults to desc.

Default"desc"

Value in

"asc"
"desc"

Responses

200OKapplication/json

The page, newest first.

data*array<>

The items on this page.

links*

Links to the first, last, previous and next pages.

meta*

The paging counters for this page.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

The token is valid but does not carry the ability this endpoint requires; error.context.required_ability names the one to grant. An endpoint that also checks who owns a row or which tier the account is on answers FORBIDDEN, TEAM_TIER_REQUIRED or CONNECTOR_TIER_REQUIRED with the same status, and says so in its own description.

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

An id in the path names nothing the token can see. TENANT_MISMATCH: the project sits outside the token's scope:project: allow-list, or the token carries no team scope. Both answer 404 rather than 403 so that existence outside the token's scope cannot be inferred.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X GET "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/plans"

{  "data": [    {      "id": "c4e82f16-93a7-4d5b-b81c-6e0f27a94d3b",      "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",      "kind": "subscription",      "name": "Premium Monthly",      "description": "Unlimited access to the research channel.",      "price": "29.00",      "currency": {        "id": "8f27a0d4-63be-4915-8c07-1a5d9e34b628",        "iso": "USD",        "symbol": "$"      },      "active": true,      "sales_cap": 10,      "sales_cap_sold": 3,      "position": 0,      "paused": null,      "cadence": "Per Month",      "eligibility": {        "newcomers_only": false,        "customers_only": false,        "churned_only": false,        "single_use": false,        "access_codes_only": false      },      "resources": [        {          "id": "b73c5f21-9d80-4a6e-8215-4f70ce13a9d6",          "name": "Research channel",          "kind": "telegram:supergroup",          "connector": "telegram"        }      ],      "billing": {        "billing_cycle": "month",        "billing_cycle_count": 1,        "recurring": true,        "disabled_renewal": false,        "trial_days": 7,        "trial_cardless": false,        "trial_type": "plan"      },      "pass": {        "timezone": "America/New_York",        "schedule_mode": "repeating",        "recurrence": "weekly",        "recurrence_ends_at": null,        "sales_cutoff_minutes": 60,        "sales_cutoff_anchor": "before_start",        "slots": [          {            "weekday": 0,            "day_of_month": null,            "start_time": "09:00",            "duration_minutes": 840          }        ],        "upcoming_windows": [          {            "id": "3d5a8c72-b016-4e94-8fa7-61c209d4e738",            "starts_at": "2026-09-20T13:00:00Z",            "ends_at": "2026-09-21T03:00:00Z",            "status": "scheduled"          }        ]      },      "pass_series": {        "timezone": "America/New_York",        "prevent_overlaps": true,        "sales_cutoff_minutes": 0,        "sales_cutoff_anchor": "before_start",        "seat_cap": 50,        "seats_taken": 37,        "seats_remaining": 13,        "starts_at": "2026-09-20T13:00:00Z",        "ends_at": "2026-11-29T22:00:00Z",        "window_count": 10,        "successor_plan_id": null,        "presale_hours": 48,        "windows": [          {            "id": "3d5a8c72-b016-4e94-8fa7-61c209d4e738",            "plan_id": "0b8e6a2f-4c1d-4e3a-9f52-7d6c1b2a3e45",            "plan_name": "Match Day Pass",            "starts_at": "2026-09-20T13:00:00Z",            "ends_at": "2026-09-20T16:00:00Z",            "status": "scheduled",            "added_by_rule": false          }        ],        "rules": [          {            "source_plan_id": "0b8e6a2f-4c1d-4e3a-9f52-7d6c1b2a3e45",            "kind": "date_range",            "from_at": "2026-09-01T00:00:00Z",            "to_at": "2026-12-01T00:00:00Z",            "take": null          }        ],        "blackout_window_ids": {          "property1": null,          "property2": null        }      },      "created_at": "2026-05-18T10:05:00Z",      "updated_at": "2026-05-18T10:05:00Z"    }  ],  "links": {    "first": "string",    "last": "string",    "prev": "string",    "next": "string"  },  "meta": {    "current_page": 1,    "from": 1,    "last_page": 1,    "links": [      {        "url": "string",        "label": "string",        "active": true      }    ],    "path": "string",    "per_page": 0,    "to": 1,    "total": 0  }}

Type definitions

The shapes above as types, ready to paste into your client.

export interface Response {  data: PlanResource[];  links: Links;  meta: Meta;}export interface PlanResource {  id: string;  project_id: string;  kind: string;  name: string;  description: string | unknown[] | null;  price: string;  currency: Currency;  active: boolean;  sales_cap: number | null;  sales_cap_sold: number;  position: number | null;  paused: Paused | null;  cadence: string;  eligibility: Eligibility;  resources?: Resource[];  billing?: Billing;  pass?: Pass;  pass_series?: PassSeries | PassSeries2;  created_at: string | null;  updated_at: string | null;}export interface Currency {  id: string;  iso: string;  symbol: string;}export interface Paused {  reason: string;  at: string | null;}export interface Eligibility {  newcomers_only: boolean;  customers_only: boolean;  churned_only: boolean;  single_use: boolean;  access_codes_only: boolean;}export interface Resource {  id: string;  name: string;  kind: string;  connector: string | null;}export interface Billing {  billing_cycle: string | "day" | "week" | "month" | "year" | "lifetime";  billing_cycle_count: number;  recurring: boolean;  disabled_renewal: boolean;  trial_days: number;  trial_cardless: boolean;  trial_type: string | "project" | "plan";}export interface Pass {  timezone: string | null;  schedule_mode: string | null;  recurrence: string | null;  recurrence_ends_at: string | null;  sales_cutoff_minutes: number | null;  sales_cutoff_anchor: string;  slots?: Slot[];  upcoming_windows?: UpcomingWindow[];}export interface Slot {  weekday: number | null;  day_of_month: number | null;  start_time: string;  duration_minutes: number;}export interface UpcomingWindow {  id: string;  starts_at: string;  ends_at: string;  status: string;}export interface PassSeries {  timezone: string;  prevent_overlaps: boolean;  sales_cutoff_minutes: number;  sales_cutoff_anchor: string;  seat_cap: number | null;  seats_taken: number;  seats_remaining: number | null;  starts_at: string | null;  ends_at: string | null;  window_count: number;  successor_plan_id: string | null;  presale_hours: number | null;  windows: Window[];  rules: Rule[];  blackout_window_ids: Record<string, unknown>;}export interface Window {  id: string;  plan_id: string;  plan_name: string;  starts_at: string;  ends_at: string;  status: string;  added_by_rule: boolean;}export interface Rule {  source_plan_id: string;  kind: string;  from_at: string | null;  to_at: string | null;  take: number | null;}export interface PassSeries2 {  timezone: unknown | null;  prevent_overlaps: boolean;  sales_cutoff_minutes: number;  sales_cutoff_anchor: string;  seat_cap: unknown | null;  seats_taken: number;  seats_remaining: unknown | null;  starts_at: unknown | null;  ends_at: unknown | null;  window_count: number;  successor_plan_id: unknown | null;  presale_hours: unknown | null;  windows: string[];  rules: string[];  blackout_window_ids: string[];}export interface Links {  first: string | null;  last: string | null;  prev: string | null;  next: string | null;}export interface Meta {  current_page: number;  from: number | null;  last_page: number;  links: Link[];  path: string | null;  per_page: number;  to: number | null;  total: number;}export interface Link {  url: string | null;  label: string;  active: boolean;}

List a project's plans

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Query ParametersCopy Anchor Link

ResponsesCopy Anchor Link

Authorization

Path Parameters

Query Parameters

Responses