For AI agents: markdown of this page — /docs-content-en/infra/servers/get.md documentation index — /llms.txt

Get a server

GET /v1/infra/servers/:id

Returns details of a single server by ID. If the server is in the provisioning status, the endpoint automatically polls the cloud provider for the current status and IP — suitable for a polling loop after creation. A deleted server (status: "deleted") is not accessible: a 404 is returned.

Parameters

Parameter In Type Required Description
id path string (UUID) yes Server ID from POST /v1/infra/servers or GET /v1/infra/servers

Examples

curl — personal key

Terminal 
curl -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.com/v1/infra/servers/e765edfc-ba0a-43de-b8ea-838dd872c522

curl — OAuth application

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

JavaScript — personal key

javascript 
// Poll the server until it is ready
async function waitReady(serverId) {
  while (true) {
    const res = await fetch(
      `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}`,
      { headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
    )
    const { data } = await res.json()
    if (data.status === 'running' && data.blackholeStatus === 'CONNECTED') {
      return data
    }
    if (data.status === 'error') {
      throw new Error(`Server in error: ${data.id}`)
    }
    await new Promise(r => setTimeout(r, 10000))
  }
}

JavaScript — OAuth application

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

Response fields

Field Type Description
success boolean Always true on success
data.id string (UUID) Server ID
data.status string provisioning | running | sleeping | error. A deleted server returns 404
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 — a container on a shared host). Determines the deploy contract — check it before uploading code
data.galaxyId string (UUID) | null For GALAXY_APP — the ID of the host the application runs on. 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 — the technical identifier
data.displayName string | null Human-readable name for the UI. Equals name if it was not provided at creation
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
data.ip string | null Public IP. null until the virtual machine receives an address
data.ssh object | null For an OPEN server: { user, port, hasPassword }. For BLACKHOLE it may be null or the same block without actual access. The password and private key are not returned here — they are returned only once, by POST /v1/infra/servers, at creation
data.plan string Plan. For a Galaxy application (kind: "GALAXY_APP") the host's plan is returned, not the one requested at creation — applications share the host's resources
data.region string The region the server actually landed in. For a Galaxy application the host's region is returned (the platform picks placement itself), not the one requested
data.image string OS image
data.monthlyCost string Catalog monthly cost in Vibe credits (Ꝟ) as a string (for example "24"). The amount actually billed may differ. Compare via Number(data.monthlyCost)
data.mode string BLACKHOLE or OPEN
data.createdVia string api — a call through the Vibecode API, ui — an action in the Vibecode dashboard, galaxy — a Galaxy application. Servers of agents and bots carry their own values
data.subdomain string Subdomain for the application
data.blackholeStatus string NONE | WAITING | CONNECTED | DISCONNECTED
data.accessPolicy string 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 Runtime status from the last deploy: null (fresh server), installing, ready, or error. Server creation always returns null — the runtime is installed via POST /:id/deploy.
data.appUrl string | null HTTPS address of the application
data.localPort number Local port the tunnel forwards traffic to (default 3000). Changed via PATCH /v1/infra/servers/:id/port
data.sleepAfterMinutes number | null After how many idle minutes the server is put to sleep automatically. null — never auto-sleep
data.provisionError string | null A short reason for the last provisioning/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
data.buildLog string | null Tail of the docker build log (≤8 KB) for a failed Galaxy application build. null for regular servers and on a successful build
data.nextScheduledWakeAt string (ISO 8601) | null The next scheduled wake time (lead offset included). null if the server has no enabled wake windows. Configured via Scheduled wake
data.wakeScheduleCapable boolean Whether scheduled wake windows can be configured for the server — depends on the server kind and whether the feature is enabled for the Bitrix24 account
data.buildHint string | null A localized recommendation on what to do about a failed Galaxy application build. The field is always present. It is null for regular servers, for a Galaxy application outside the error status, and when the failure could not be matched to any known category
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",
    "localPort": 3000,
    "sleepAfterMinutes": null,
    "provisionError": null,
    "provisionErrorCode": null,
    "provisionReason": null,
    "buildLog": null,
    "nextScheduledWakeAt": null,
    "wakeScheduleCapable": true,
    "buildHint": null,
    "createdAt": "2026-04-03T13:30:25.819Z"
  }
}

Error response example

404 — a server with this ID does not exist or belongs to another API key:

JSON 
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Server not found"
  }
}

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
404 NOT_FOUND Server not found or belongs to another API key
429 RATE_LIMITED The platform's overall request limit was exceeded

The full list of common API errors — Errors.

Known specifics

  • No provider request is made for running/sleeping/error. Automatic provider polling happens only when the status is provisioning. If you need to reconcile the state of other statuses — use POST /v1/infra/servers/:id/refresh.
  • The readiness criterion is two fields. To continue working with the Deploy API you need both status: "running" and blackholeStatus: "CONNECTED" at the same time. If only running is set — the virtual machine is already alive, but the tunnel agent has not connected yet. If runtime was used during deploy — additionally wait for runtimeStatus: "ready".
  • blackholeStatus: "DISCONNECTED" with running — the tunnel lost its connection on a live server. Try POST /v1/infra/servers/:id/repair.
  • monthlyCost pitfall: the field is returned as a string. Two such strings are compared character by character: "24" > "1000" returns true, and .sort() orders the values by text rather than by size. Convert to a number via Number(data.monthlyCost).
  • If you lost the SSH credentials from the creation response — they cannot be recovered. Recreate the SSH key manually via POST /v1/infra/servers/:id/exec (for BLACKHOLE) or recreate the server.

See also