## List servers

`GET /v1/infra/servers`

Returns the servers managed by the current API key. Deleted servers (`status: "deleted"`) are not included by default — pass `?includeDeleted=true` to see them. Servers of other keys are not visible, even within the same Bitrix24 account. To view all servers of a Bitrix24 account, use the administrator panel in the dashboard.

## Query parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `includeDeleted` | string | No | Pass `true` to include deleted servers in the output. Any other value (or its absence) keeps the default listing |

Why this exists: sources outlive their server. Once you delete a server you can still list, untag, download or clean up its source versions — but that needs its id, and there is nowhere else to get it. The sources contract lives on the [Source storage](/docs/source-storage) page.

## Examples

### curl — personal key

```bash
curl -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.com/v1/infra/servers
```

### curl — OAuth application

```bash
curl -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  https://vibecode.bitrix24.com/v1/infra/servers
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/infra/servers', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data: servers } = await res.json()

servers.forEach(s => {
  const ready = s.status === 'running' && s.blackholeStatus === 'CONNECTED'
  console.log(`${s.name}: ${ready ? '✓ ready' : s.status} — ${s.appUrl}`)
})
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/infra/servers', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data: servers } = await res.json()
```

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | Always `true` on success |
| `data` | array | Array of servers. Each element is the same object as in [`GET /v1/infra/servers/:id`](./get.md), except: the SSH fields `ssh.password` and `ssh.privateKey` (not returned in the list) and the `localPort` / `buildLog` / `buildHint` fields (single `GET /:id` only) |
| `data[].id` | string (UUID) | Server ID |
| `data[].status` | string | Current status: `provisioning`, `running`, `sleeping`, `error`. Deleted servers are not returned by default — see `includeDeleted` |
| `data[].deletedAt` | string \| null | When the server was deleted, ISO-8601. `null` for live servers |
| `data[].provider` | string | Provider ID |
| `data[].kind` | string | Resource type: `STANDALONE` (a dedicated virtual machine), `GALAXY` (a host carrying Galaxy applications) or `GALAXY_APP` (a Galaxy application on a shared host). Determines the deploy contract |
| `data[].galaxyId` | string (UUID) \| null | For `GALAXY_APP` — the ID of the host. `null` for other types |
| `data[].appCount` | number \| null | For a `GALAXY` host — the number of non-deleted applications on it. `null` for other types |
| `data[].name` | string | System name of the server |
| `data[].displayName` | string \| null | Display name for the dashboard. Equals `name` if it was not provided |
| `data[].description` | string \| null | Application description shown on the Bitrix24 catalog card. `null` if no description was set. Changed via [`PATCH /v1/infra/servers/:id`](./update.md) |
| `data[].ip` | string \| null | Public IP (may be `null` while provisioning) |
| `data[].ssh` | object \| null | SSH data block: `{ user, port, hasPassword }`. The `password` and `privateKey` fields are not present in the list |
| `data[].plan` | string | Plan. **For a Galaxy application** (`kind: "GALAXY_APP"`) the host's plan is returned, not the one requested |
| `data[].region` | string | The actual region of the server — may differ from the requested one after a zone fallback. **For a Galaxy application** the host's region is returned |
| `data[].image` | string | OS image |
| `data[].monthlyCost` | string | Catalog monthly cost in Vibe credits (Ꝟ), as a string: `"24"` or `"24.00"`. The amount actually billed may differ. Compare with `Number(s.monthlyCost)` |
| `data[].mode` | string | `BLACKHOLE` or `OPEN` |
| `data[].createdVia` | string | `api` — a call through the Vibecode API, `ui` — an action in the dashboard, `galaxy` — a Galaxy application. Servers of agents and bots carry their own values |
| `data[].subdomain` | string | Subdomain for the application |
| `data[].blackholeStatus` | string | Tunnel state: `NONE`, `WAITING`, `CONNECTED`, `DISCONNECTED` |
| `data[].accessPolicy` | string | Access policy: `OWNER_ONLY`, `NAMED_USERS`, `DEPARTMENT`, `PORTAL`, `AUTHENTICATED`, `PUBLIC` |
| `data[].runtimeId` | string \| null | ID of the runtime installed via `POST /:id/deploy` (server creation always returns `null`). |
| `data[].runtimeStatus` | string \| null | A deprecated field, kept for compatibility. For servers created after 2026-04-25 it always returns `null`. The runtime is installed at the [`POST /:id/deploy`](/docs/infra/deploy/deploy) stage, and its readiness signal is the success of the `runtime` step in the deploy response, not this field's value |
| `data[].appUrl` | string \| null | HTTPS address of the application |
| `data[].sleepAfterMinutes` | number \| null | Number of idle minutes after which the server is automatically put to sleep. `null` — never auto-sleep |
| `data[].provisionError` | string \| null | A short reason for the last creation or build failure. `null` if there were no errors |
| `data[].provisionErrorCode` | string \| null | Machine-readable failure category: `PREEMPTIBLE_EVICTION` / `PROVISION_TIMEOUT` / `NO_CAPACITY` / `GENERIC`. `null` if there were no errors |
| `data[].provisionReason` | string \| null | Structured cause of a Galaxy application failure: `oom` — the container ran out of memory, or `crash`. `null` for regular servers and when there was no failure. `oom` is the signal to move the application to a dedicated server. The procedure is described in [Create a server](./create.md) |
| `data[].createdAt` | string (ISO 8601) | Creation timestamp |

## Response example

```json
{
  "success": true,
  "data": [
    {
      "id": "e765edfc-ba0a-43de-b8ea-838dd872c522",
      "status": "running",
      "provider": "bitrix-cloud",
      "kind": "STANDALONE",
      "galaxyId": null,
      "appCount": null,
      "name": "vibe-server-pd9l",
      "displayName": "vibe-server-pd9l",
      "description": null,
      "ip": "111.88.251.211",
      "ssh": {
        "user": "ubuntu",
        "port": 22,
        "hasPassword": true
      },
      "plan": "bc-small",
      "region": "bc-eu-central",
      "image": "ubuntu-2404-lts",
      "monthlyCost": "24",
      "mode": "OPEN",
      "createdVia": "ui",
      "subdomain": "app-05b67cf7",
      "blackholeStatus": "CONNECTED",
      "accessPolicy": "OWNER_ONLY",
      "runtimeId": null,
      "runtimeStatus": null,
      "appUrl": "https://app-05b67cf7.vibecode.bitrix24.com",
      "sleepAfterMinutes": null,
      "provisionError": null,
      "provisionErrorCode": null,
      "provisionReason": null,
      "createdAt": "2026-04-03T13:30:25.819Z"
    }
  ]
}
```

## Error response example

401 — no API key passed:

```json
{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key required. Pass via X-Api-Key header."
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not passed |
| 401 | `INVALID_API_KEY` | Invalid or expired API key |
| 429 | `RATE_LIMITED` | The platform's overall request limit was exceeded |

The full list of common API errors — [Errors](/docs/errors).

## Known specifics

- **An empty array while servers are running means the current key does not manage them.** The output is limited to the servers of the current key. After the previous key expires or is revoked, the server stays bound to it. If the previous key is deleted, the server is left without a managing key. In both cases a new key returns an empty `data` while the servers keep running and remain visible in the dashboard. How to restore access — [Server access recovery](/docs/infra/server-access-recovery).
- **Even a Bitrix24 account administrator sees only their own servers.** For an account-wide picture, use the administrator panel in the dashboard — the API-key restriction cannot be changed.
- **Servers of Bitrix24 accounts marked as deleted are hidden automatically.** The platform checks account availability daily: if an account responds with 410/403 three days in a row, it is marked as deleted and its servers stop being displayed.
- **The response is not paginated** — all of the key's servers are returned in a single array.
- **`includeDeleted=true` does not surface servers of deleted Bitrix24 accounts.** The account-level hiding above applies whatever the parameter says: the account is gone, so a call against those servers is meaningless.

## See also

- [Create a server](./create.md)
- [Get a server](./get.md)
- [Update name and description](./update.md)
- [Delete a server](./delete.md)
- [Lifecycle](/docs/infra/lifecycle)
- [Server access recovery](/docs/infra/server-access-recovery)