+++
title = "Plans API Introduction"
weight = 97
updated = 2026-10-13
aliases = ["/docs/plans-api-introduction.html", "/docs/bonsai-api/endpoints/plans-api/", "/docs/api/endpoints/plans-api/"]

[extra]
nav_title = "Plans API Introduction"
weight = 20
+++

The Plans API gives users the ability to explore the different cluster subscription plans available to their account.

{{ legacy_api_notice() }}

The Plans API gives users the ability to explore the different cluster subscription plans available to their account. This API supports the following actions:

- View all plans available for your account.
- View a single plan available for your account.

All calls to the Plans API must be [authenticated](@/docs/api/legacy/authentication/overview/index.md) with an active [API token](@/docs/account/api-tokens/index.md) that has the `account:read` [scope](@/docs/account/api-tokens/index.md#scopes).

## The Bonsai Plan Object

The Bonsai API provides a standard format for Plan objects. A Plan object includes:

<table>
<thead>
<tr>
<th>Attribute</th><th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>slug</td><td>A String representing a machine-readable name for the plan. </td>
</tr>
<tr>
<td>name</td><td>A String representing the human-readable name of the plan.</td>
</tr>
<tr>
<td>price_in_cents</td><td>An Integer representing the plan price in cents.</td>
</tr>
<tr>
<td>billing_interval_in_months</td><td>An Integer representing the plan billing interval in months.</td>
</tr>
<tr>
<td>single_tenant</td><td>A Boolean indicating whether the plan is single-tenant or not. A value of <strong>false</strong> indicates the Cluster will share hardware with other Clusters. Single tenant environments can be reached via the public Internet. Additional documentation <a href="@/docs/platform/bonsai-architecture/index.md">here</a>.</td>
</tr>
<tr>
<td>private_network</td><td>A Boolean indicating whether the plan is on a publicly addressable network. Private plans provide environments that cannot be reached by the public Internet. A <a href="@/docs/heroku/private-spaces-and-vpc-peering/index.md">VPC connection</a> will be needed to communicate with a private cluster.</td>
</tr>
<tr>
<td>available_releases</td><td>An Array with the slugs of the search releases available for the plan. Additional information about a release can be retrieved from the <a href="@/docs/api/legacy/endpoints/releases-api/index.md">Releases API</a>.</td>
</tr>
<tr>
<td>available_spaces</td><td>An Array with the paths of every active shared Space. It is the same list for every plan, and it does not include your account's private spaces. Use the <a href="@/docs/api/legacy/endpoints/spaces-api/index.md">Spaces API</a> for the spaces your account can provision clusters in.</td>
</tr>
</tbody>
</table>

## View all plans

The Bonsai API provides a method to get a list of all plans available to your account. An HTTP GET call is made to the `/plans` endpoint, and Bonsai will return a JSON list of Plan objects.

#### Supported Parameters

No parameters are supported for this action.

#### HTTP Request

An HTTP GET call is made to `/plans`.

#### HTTP Response

Upon success, Bonsai responds with an `HTTP 200: OK` code, along with a JSON list representing the Plans available to your account:

```javascript
{
  "plans": [
     {
        "slug": "sandbox",
        "name": "Sandbox",
        "price_in_cents": 0,
        "billing_interval_in_months": 1,
        "single_tenant": false,
        "private_network": false,
        "available_releases": [
            "elasticsearch-7.10.2",
            "opensearch-2.19.4"
        ],
        "available_spaces": [
            "omc/bonsai-gcp/us-east4/common",
            "omc/bonsai-gcp/us-west1/common",
            "omc/bonsai/ap-northeast-1/common",
            "omc/bonsai/ap-southeast-2/common",
            "omc/bonsai/eu-central-1/common",
            "omc/bonsai/eu-west-1/common",
            "omc/bonsai/us-east-1/common",
            "omc/bonsai/us-west-2/common"
        ]
     },
     {
        "slug": "standard-fir",
        "name": "Standard Fir",
        "price_in_cents": 2000,
        "billing_interval_in_months": 1,
        "single_tenant": false,
        "private_network": false,
        "available_releases": [
            "elasticsearch-7.10.2",
            "opensearch-2.19.4"
        ],
        "available_spaces": [
            "omc/bonsai-gcp/us-east4/common",
            "omc/bonsai-gcp/us-west1/common",
            "omc/bonsai/ap-northeast-1/common",
            "omc/bonsai/ap-southeast-2/common",
            "omc/bonsai/eu-central-1/common",
            "omc/bonsai/eu-west-1/common",
            "omc/bonsai/us-east-1/common",
            "omc/bonsai/us-west-2/common"
        ]
     }
  ]
}
```

## View a single plan

The Bonsai API provides a method to retrieve information about a single Plan available to your account.

#### Supported Parameters

No parameters are supported for this action.

#### HTTP Request

An HTTP GET call is made to `/plans/[:plan-slug]`.

#### HTTP Response

Upon success, Bonsai will respond with an `HTTP 200: OK` code, along with a JSON body representing the Plan object:

```javascript
{
   "slug": "sandbox",
   "name": "Sandbox",
   "price_in_cents": 0,
   "billing_interval_in_months": 1,
   "single_tenant": false,
   "private_network": false,
   "available_releases": [
      "elasticsearch-7.10.2",
      "opensearch-2.19.4"
   ],
   "available_spaces": [
      "omc/bonsai-gcp/us-east4/common",
      "omc/bonsai-gcp/us-west1/common",
      "omc/bonsai/ap-northeast-1/common",
      "omc/bonsai/ap-southeast-2/common",
      "omc/bonsai/eu-central-1/common",
      "omc/bonsai/eu-west-1/common",
      "omc/bonsai/us-east-1/common",
      "omc/bonsai/us-west-2/common"
   ]
}
```

A slug that does not name a plan available to your account gets an [HTTP 404: Not Found](@/docs/api/legacy/errors/404-not-found/index.md) error:

```json
{
  "errors": [
    "Plan 'sandboxing' not found. Please use the /plans endpoint for a list of available plans."
  ],
  "status": 404
}
```