---
title: "List your CoreClusters"
url: https://docs.corefinity.com/api/reference/corecluster/list-clusters
type: endpoint
last_updated: 2026-11-13
feature: clusters
related:
  - https://docs.corefinity.com/guides/corecluster/cluster-overview.md
  - https://docs.corefinity.com/mcp/tools/corecluster_list.md
---
# List your CoreClusters

Answers every CoreCluster of your company, by name, each with its package, capacity, usage and site counts,
and whether another one can be created now. The list is not paged.

```http
GET /api/corestack/clusters
```

- Scope: `read`
- Two-factor: required on your account (all)
- Rate limit: 60 a minute
- Try it in the console: on

## Request

### curl

```bash
curl https://manage.corefinity.com/api/corestack/clusters \
  -H "Authorization: Bearer $COREFINITY_TOKEN" \
  -H "Accept: application/json"
```

### PHP

```php
use Illuminate\Support\Facades\Http;

$response = Http::withToken(env('COREFINITY_TOKEN'))
    ->acceptJson()
    ->get('https://manage.corefinity.com/api/corestack/clusters');

$data = $response->json();
```

### Node

```javascript
const res = await fetch('https://manage.corefinity.com/api/corestack/clusters', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.COREFINITY_TOKEN}`,
    Accept: 'application/json',
  },
});

// An answer with no body (204) has nothing to parse.
const text = await res.text();
const data = text && JSON.parse(text);
```

### Python

```python
import os
import requests

res = requests.get(
    "https://manage.corefinity.com/api/corestack/clusters",
    headers={
        "Authorization": f"Bearer {os.environ['COREFINITY_TOKEN']}",
        "Accept": "application/json",
    },
)

data = res.json() if res.content else None
```

## Responses

### 200 The CoreClusters.

```json
{
  "can_create": {
    "available": true,
    "reason": null
  },
  "clusters": [
    {
      "actions": {
        "create_environment": {
          "available": true,
          "reason": null
        },
        "create_site": {
          "available": true,
          "reason": null
        },
        "delete": {
          "available": true,
          "reason": null
        },
        "upgrade_package": {
          "available": true,
          "downgrade": false,
          "reason": null
        }
      },
      "allowance": {
        "cpu_millicores": 4000,
        "disk_bytes": 214748364800,
        "memory_bytes": 17179869184
      },
      "capacity": {
        "basis": "p95",
        "cpu": {
          "capacity_millicores": 4000,
          "level": "ok",
          "percent": 6,
          "used_p95_millicores": 240
        },
        "evaluated_at": "2026-11-14T09:50:00Z",
        "level": "ok",
        "memory": {
          "capacity_bytes": 17179869184,
          "level": "ok",
          "percent": 6,
          "used_p95_bytes": 1073741824
        },
        "package": {
          "cores": 4,
          "key": "xsmall",
          "memory_bytes": 17179869184,
          "name": "Extra small"
        },
        "sites": {
          "count": 1,
          "environments": 0
        },
        "storage": {
          "capacity_bytes": 214748364800,
          "level": "ok",
          "percent": 5,
          "provisioned_bytes": 10737418240
        }
      },
      "created_at": "2026-11-02T08:14:00Z",
      "created_by": {
        "id": 2041,
        "name": "Eleanor Finch"
      },
      "environments": 0,
      "id": 1017,
      "kind": "customer",
      "label": "Northwind UK 1",
      "location": {
        "arch": "arm64",
        "label": "London (europe-west2)"
      },
      "logs": null,
      "name": "Northwind UK 1",
      "operation": null,
      "package": {
        "cores": 4,
        "key": "xsmall",
        "name": "Extra small"
      },
      "pending_changes": {
        "count": 0,
        "window_starts_at": null
      },
      "ready_at": "2026-11-02T08:19:00Z",
      "region": {
        "key": "uk",
        "label": "United Kingdom",
        "place": "London (europe-west2)"
      },
      "reserved": {
        "cpu_limit_millicores": 2000,
        "cpu_request_millicores": 100,
        "disk_bytes": 10737418240,
        "memory_limit_bytes": 4294967296,
        "memory_request_bytes": 536870912
      },
      "sites": {
        "applying": 0,
        "degraded": 0,
        "down": 0,
        "environments": 0,
        "healthy": 1,
        "live": 1,
        "preview": 0,
        "total": 1,
        "unknown": 0
      },
      "slug": "northwind-uk-1",
      "snapshots": {
        "frequency": "6h",
        "over_quota": false,
        "pruned_recently": false,
        "quota_bytes": 429496729600,
        "retention_days": 30,
        "usage_bytes": 1288490188
      },
      "ssh_host": "ssh-northwind.example.net",
      "state": "ready",
      "state_label": "Ready",
      "state_reason": null,
      "synced": {
        "inventory_at": "2026-11-14T09:55:00Z",
        "live_at": "2026-11-14T09:58:00Z",
        "usage_at": "2026-11-14T09:55:00Z"
      },
      "usage": {
        "cpu_millicores": 180,
        "disk_used_bytes": 2362232012,
        "memory_bytes": 912261120,
        "observed_at": "2026-11-14T09:58:00Z",
        "source": "live"
      }
    }
  ],
  "generated_at": "2026-11-14T10:00:00+00:00"
}
```

### 401 No token, or a token that is not valid.

```json
{
  "message": "Unauthenticated."
}
```

### 403 The token lacks the scope (`scope_required`, with the `scope` to use), your company requires two-factor authentication and you have not set it up, or your account has no company that can use Managed Clusters, for example because the company was closed (`company_unavailable` or `company_not_enabled`, whichever the route checks first). For Managed Clusters routes; any other route uses `ForbiddenScopeOrTwoFactor`.

```json
{
  "code": "company_unavailable",
  "message": "Your company is unavailable.",
  "reason": "company_unavailable"
}
```

### 429 Too many requests (`rate_limited`). Wait for the number of seconds in `Retry-After`, which `retry_after_seconds` repeats.

```json
{
  "code": "rate_limited",
  "message": "Too many requests. Try again in 60 seconds.",
  "reason": "rate_limited",
  "retry_after_seconds": 60
}
```

## If it is refused

| Status | Reason | What to do |
|---|---|---|
| 401 |  | Send a valid token as `Authorization: Bearer <token>`. |
| 403 | `company_unavailable` | Your company is unavailable. |
| 403 | `scope_required` | Use a token with the scope named in `scope`. |
| 403 | `two_factor_required` | Turn on two-factor on your account, then send again. |
| 429 | `rate_limited` | Wait for the seconds in `Retry-After`. |

## The same task elsewhere

- Guide: [Cluster overview](https://docs.corefinity.com/guides/corecluster/cluster-overview.md)
- MCP tool: [`corecluster_list`](https://docs.corefinity.com/mcp/tools/corecluster_list.md)
