# Get a server Returns one Forge cloud server: its state, network addresses, SSH host keys, price, this month's cost (Aitronos servers) and what can be done with it now. Poll it about every two seconds while the server is in a backend-driven state (`creating`, `booting`, `parking`, `resuming`, `deleting`, `revoking`); the setup itself is described in the [lifecycle](/docs/api-reference/forge-compute/introduction#creating-and-setting-up-a-server). A server is visible to the person who created it and to members with `manage_forge`; anyone else is told it does not exist. Requires a bearer token (or API key) whose principal holds the `use_forge` capability in the acting organization. It works while Forge cloud compute is switched off, so a server can always be found and stopped. #### Path Parameters **`host_id`** string required The server's id: the `fchost_` id returned in `id`, or the UUID sent when the server was created (any letter case, with or without hyphens). #### Query Parameters **`organization_id`** string optional The organization the server belongs to: send its `organization.id` (from [List your servers in every organization](/docs/api-reference/forge-compute/list-my-hosts)). Defaults to your current organization, where a server of another organization is not found. You must be an active member of it, or the request is refused with `403 ORGANIZATION_ACCESS_DENIED`. #### Headers **`X-Organization-Id`** string optional The same as `organization_id`, as a header. When both are sent, the query parameter wins. ## Returns The server object. Every host endpoint returns it. **Identity** - **`id`** string — `fchost_` followed by 32 hex characters. - **`offering_id`** string — the offering it runs on, e.g. `aitronos`. - **`kind`** string — `managed` (Aitronos servers, billed to your organization) or `byo` (your organization's own provider account, billed by the provider). - **`name`** string — the name given at creation. - **`organization`** object — the organization the server is billed to and acted on in: **`id`** string, and **`name`** string or `null` (`null` when it cannot be read right now). Send `organization.id` as `organization_id` or `X-Organization-Id` with every request about this server. - **`user_id`** string or `null` — the user who created it. - **`project_group`** object or `null` — the Forge [project group](/docs/api-reference/forge-compute/list-project-groups) the server was rented in, fixed when it was created: **`id`** string (`fpgrp_` id), **`client_id`** string or `null` (Forge's own id for the group) and **`name`** string or `null` (both `null` when they cannot be read right now; the `id` never is). A group deleted since is still named. `null` when the server was rented outside any group. The group never moves the server's billing: the server stays billed to `organization`, the organization it was rented in, even when the group's organization changes later; the group only places the server's usage under it on the organization's [usage report](/assets/get-usage-detail-report.45870ea5b94806d0570403fa53ae031e4b48417dddf0f27bd3aa2fc29b7ba55c.49b960d1.md). - **`location_id`**, **`location_label`** string — where it runs. For Aitronos servers the label is a country, e.g. `Germany`; for your own account both are the provider's location id. - **`size_id`**, **`size_label`** string — its size, e.g. `16 vCPU · 64 GB`; for your own account both are the provider's size id. **State** - **`state`** string — the lifecycle state; see [the lifecycle](/docs/api-reference/forge-compute/introduction#server-lifecycle). - **`state_label`** string — the state as a sentence to show the person. - **`transient`** boolean — `true` while the server is between states. Backend-driven states (`creating`, `booting`, `parking`, `resuming`, `deleting`, `revoking`) end on their own; client-driven ones (`awaiting_client` to `pairing`) end when the client reports its next step. - **`step`** string or `null` — the setup step reached (`securing`, `installing`, `pairing` or `ready`); `null` outside setup. - **`step_started_at`**, **`state_changed_at`** string or `null` — when the step started and when the server entered its current state (UTC). - **`failure`** object or `null` — why the last lifecycle step failed: `code` (a `FORGE_COMPUTE_*` error code, e.g. `FORGE_COMPUTE_CAPACITY_UNAVAILABLE` or `FORGE_COMPUTE_PROVIDER_LIMIT`), `message` (a sentence safe to show) and `details` (e.g. `alternatives`). A failed create ends in `failed_clean`; a failed resume goes back to `parked`; a failed park goes back to `ready`; a step that may have left a running server ends in `failed_billing`. - **`actions`** array of strings — what the caller may request now, in display order: `park`, `resume`, `delete`, `revoke`. Already filtered by what the offering supports: `park` is never listed for an offering whose `capabilities.park` is `false` in [List compute offerings](/docs/api-reference/forge-compute/list-offerings). **Connection** - **`ipv4`**, **`ipv6`** string or `null` — the server's public addresses while it exists. A resumed server usually has new ones. - **`ssh_port`** integer — the SSH port, `22`. - **`ssh_user`** string — the user to log in as, always `forge`. - **`bootstrap_host_key_pub`** string or `null` — the bootstrap host key (K0) to trust on the first connection. `null` in the create response, set once the backend has generated it (by `awaiting_client` at the latest), and `null` again once the host key was reported. - **`host_key_pub`** string or `null` — the server's own host key (K1), once [reported](/docs/api-reference/forge-compute/report-host-key). From then on it is the only key to trust. **Money** - **`price`** object — the price the server was created (or last resumed) at; it is billed at exactly this price. `hourly`, `monthly_cap` and `parked_per_gb_month` are decimal strings in `currency`; `source` is `aitronos` (billed to your organization) or the bring-your-own offering id (billed by that provider); `includes_vat` is `false`; `catalog_version` and `quoted_at` say where and when it was quoted; `price_verified` is `true` when the price was confirmed at the source. - **`month_to_date`** string or `null` — Aitronos servers: what this server has cost your organization this calendar month, in CHF. `null` for bring-your-own servers, and when the reading is unavailable right now (never `"0.00"` in its place). - **`notice`** object or `null` — Aitronos servers near or at a spending limit; `null` when there is none. `code` string: `spend_cap_90`, `spend_cap_100` or `spend_cap_parked` for the organization's spending limit, or `member_limit_90`, `member_limit_100` or `member_limit_parked` for the [per-person limit](/docs/api-reference/forge-compute/get-limits) of the server's owner (at 90%; at 100% while the server keeps running or until it can be parked; parked at 100%). The organization's notice wins when both apply. Show `message` for any other code. `message` string (a sentence to show, for example "You have used 92% of your monthly limit of CHF 12.50 for Aitronos servers. At 100%, your running Aitronos servers are parked: their work is saved and compute charges stop."), `percent` integer or `null` (how much of the limit is used, at most 100; `null` when not known) and `set_at` string or `null` (when the notice was set, UTC). - **`idle_reminder`** object or `null` — set while the server is `ready` and no activity was reported for the organization's `idle_reminder_hours`: `since` (when it was last in use) and `message`. - **`reconcile_flags`** object or `null` — bring-your-own servers only: resources of this server that still exist in your provider account although they should not (for example after a delete). `leftover_resources` lists each with `resource_type` (`server`, `snapshot`, `ssh_key` or `firewall`), `provider_resource_id`, `name` (or `null`), `first_seen_at` and `last_seen_at` (UTC); `message` (a sentence to show, or `null`) and `checked_at` (UTC, or `null`) go with it. `null` when nothing is left; always `null` for Aitronos servers. **Times and reasons** - **`created_at`**, **`ready_at`** (the last time it became ready), **`parked_at`**, **`deleted_at`**, **`revoked_at`**, **`last_activity_at`** string or `null` (UTC). - **`parked_expires_at`** string or `null` — parked Aitronos servers only: when the saved server is deleted unless it is [resumed](/docs/api-reference/forge-compute/resume-host) first (UTC). An Aitronos server parked for 30 days is deleted; its owner is notified 3 days before, and a server is never deleted with less than 3 days' notice. `null` for bring-your-own servers (they never expire) and for any server that is not parked. - **`revoke_reason`** string or `null` — the reason given when it was revoked. - **`provider_server_id`** string — bring-your-own servers only, while a server exists: its id in your own provider account. The key is left out entirely for Aitronos servers and when no server exists. Every timestamp in the object, the ones inside `price`, `notice`, `idle_reminder` and `reconcile_flags` included, is ISO 8601 in UTC with a `Z` suffix, e.g. `2026-09-28T09:03:41.502318Z`. ```json { "id": "fchost_5d0c2b9e7a414f3c9e8b1a6d2f4c7e90", "offering_id": "aitronos", "kind": "managed", "name": "build-box", "organization": {"id": "org_3c1e9a7b5d2f4e8a9b0c6d1e2f3a4b5c", "name": "Acme Engineering"}, "user_id": "usr_7f3a9c2e1b8d4e6fa0c5b3d9e2f1a4c7", "project_group": {"id": "fpgrp_4b9e2c7a1d3f4e8a9c0b6d2e1f3a5b7c", "client_id": "grp-clients", "name": "Clients"}, "location_id": "eu-central", "location_label": "Germany", "size_id": "std-16", "size_label": "16 vCPU · 64 GB", "state": "ready", "state_label": "Ready", "transient": false, "step": "ready", "step_started_at": "2026-09-28T09:03:41.502318Z", "state_changed_at": "2026-09-28T09:03:41.502318Z", "failure": null, "ipv4": "203.0.113.24", "ipv6": "2001:db8:4f2a::1", "ssh_port": 22, "ssh_user": "forge", "bootstrap_host_key_pub": null, "host_key_pub": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExampleServerHostKeyForDocumentationOnly0000", "price": { "hourly": "0.83", "monthly_cap": "520.30", "currency": "CHF", "source": "aitronos", "includes_vat": false, "catalog_version": "fc-3b8e1f0a9c42", "quoted_at": "2026-09-28T09:00:00.184066Z", "parked_per_gb_month": "0.0269", "price_verified": true }, "month_to_date": "0.83", "notice": null, "idle_reminder": null, "reconcile_flags": null, "actions": ["park", "delete", "revoke"], "created_at": "2026-09-28T09:00:00.184066Z", "ready_at": "2026-09-28T09:03:41.502318Z", "parked_at": null, "parked_expires_at": null, "deleted_at": null, "revoked_at": null, "revoke_reason": null, "last_activity_at": null } ``` ## Errors | Status | Code | When | | --- | --- | --- | | 401 | `AUTHENTICATION_REQUIRED` | No valid credential. | | 403 | `ORGANIZATION_ACCESS_DENIED` | `organization_id` or `X-Organization-Id` names an organization you are not an active member of. | | 403 | `INSUFFICIENT_PERMISSIONS` | The caller does not hold `use_forge` in the acting organization. | | 404 | `FORGE_COMPUTE_HOST_NOT_FOUND` | No server with this id in the acting organization, or it was created by someone else and the caller does not hold `manage_forge`. | | 422 | `INVALID_ID_FORMAT` | `host_id` is neither a UUID nor `fchost_<32 hex>`. | ```bash cURL curl "https://api.aitronos.com/v1/forge/compute/hosts/fchost_5d0c2b9e7a414f3c9e8b1a6d2f4c7e90" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ```python Python SDK # pip install aitronos-sdk # # The Python SDK does not expose a typed `forge_compute` namespace yet, so call # the endpoint directly with the same credential you would pass to `Aitronos(...)` # — an API key or a bearer token, both sent as `Authorization: Bearer `. import time import httpx API_KEY = "your-api-key" url = "https://api.aitronos.com/v1/forge/compute/hosts/fchost_5d0c2b9e7a414f3c9e8b1a6d2f4c7e90" headers = {"Authorization": f"Bearer {API_KEY}"} server = httpx.get(url, headers=headers).json() while server["transient"] and server["state"] in ("creating", "booting", "parking", "resuming", "deleting", "revoking"): time.sleep(2) server = httpx.get(url, headers=headers).json() print(server["state_label"], server["actions"]) ``` ```python Python import os import requests token = os.environ["AITRONOS_TOKEN"] server = requests.get( "https://api.aitronos.com/v1/forge/compute/hosts/fchost_5d0c2b9e7a414f3c9e8b1a6d2f4c7e90", headers={"Authorization": f"Bearer {token}"}, ).json() if server["failure"]: print(server["failure"]["code"], server["failure"]["message"]) print(server["state"], server["month_to_date"], server["price"]["currency"]) ``` ```javascript JavaScript const response = await fetch( "https://api.aitronos.com/v1/forge/compute/hosts/fchost_5d0c2b9e7a414f3c9e8b1a6d2f4c7e90", { headers: { Authorization: `Bearer ${process.env.AITRONOS_TOKEN}` } }, ); const server = await response.json(); if (server.notice) console.warn(server.notice.message); console.log(server.state_label, server.actions); ``` **Response:** 200 OK ```json { "id": "fchost_5d0c2b9e7a414f3c9e8b1a6d2f4c7e90", "offering_id": "aitronos", "kind": "managed", "name": "build-box", "organization": {"id": "org_3c1e9a7b5d2f4e8a9b0c6d1e2f3a4b5c", "name": "Acme Engineering"}, "user_id": "usr_7f3a9c2e1b8d4e6fa0c5b3d9e2f1a4c7", "project_group": {"id": "fpgrp_4b9e2c7a1d3f4e8a9c0b6d2e1f3a5b7c", "client_id": "grp-clients", "name": "Clients"}, "location_id": "eu-central", "location_label": "Germany", "size_id": "std-16", "size_label": "16 vCPU · 64 GB", "state": "ready", "state_label": "Ready", "transient": false, "step": "ready", "step_started_at": "2026-09-28T09:03:41.502318Z", "state_changed_at": "2026-09-28T09:03:41.502318Z", "failure": null, "ipv4": "203.0.113.24", "ipv6": "2001:db8:4f2a::1", "ssh_port": 22, "ssh_user": "forge", "bootstrap_host_key_pub": null, "host_key_pub": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExampleServerHostKeyForDocumentationOnly0000", "price": { "hourly": "0.83", "monthly_cap": "520.30", "currency": "CHF", "source": "aitronos", "includes_vat": false, "catalog_version": "fc-3b8e1f0a9c42", "quoted_at": "2026-09-28T09:00:00.184066Z", "parked_per_gb_month": "0.0269", "price_verified": true }, "month_to_date": "0.83", "notice": null, "idle_reminder": null, "reconcile_flags": null, "actions": ["park", "delete", "revoke"], "created_at": "2026-09-28T09:00:00.184066Z", "ready_at": "2026-09-28T09:03:41.502318Z", "parked_at": null, "parked_expires_at": null, "deleted_at": null, "revoked_at": null, "revoke_reason": null, "last_activity_at": null } ``` 200 Idle, near the limit ```json { "id": "fchost_5d0c2b9e7a414f3c9e8b1a6d2f4c7e90", "offering_id": "aitronos", "kind": "managed", "name": "build-box", "organization": {"id": "org_3c1e9a7b5d2f4e8a9b0c6d1e2f3a4b5c", "name": "Acme Engineering"}, "user_id": "usr_7f3a9c2e1b8d4e6fa0c5b3d9e2f1a4c7", "project_group": {"id": "fpgrp_4b9e2c7a1d3f4e8a9c0b6d2e1f3a5b7c", "client_id": "grp-clients", "name": "Clients"}, "location_id": "eu-central", "location_label": "Germany", "size_id": "std-16", "size_label": "16 vCPU · 64 GB", "state": "ready", "state_label": "Ready", "transient": false, "step": "ready", "step_started_at": "2026-09-28T09:03:41.502318Z", "state_changed_at": "2026-09-28T09:03:41.502318Z", "failure": null, "ipv4": "203.0.113.24", "ipv6": "2001:db8:4f2a::1", "ssh_port": 22, "ssh_user": "forge", "bootstrap_host_key_pub": null, "host_key_pub": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExampleServerHostKeyForDocumentationOnly0000", "price": { "hourly": "0.83", "monthly_cap": "520.30", "currency": "CHF", "source": "aitronos", "includes_vat": false, "catalog_version": "fc-3b8e1f0a9c42", "quoted_at": "2026-09-28T09:00:00.184066Z", "parked_per_gb_month": "0.0269", "price_verified": true }, "month_to_date": "7.47", "notice": { "code": "spend_cap_90", "message": "Your organization has used 92% of its monthly spending limit. At 100%, running cloud servers are parked: their work is saved and compute charges stop.", "percent": 92, "set_at": "2026-09-28T17:00:04.118203Z" }, "idle_reminder": { "since": "2026-09-28T09:25:00Z", "message": "No activity on this server for 8 hours or more. Park it or delete it if you no longer need it. It is billed by the hour while it runs." }, "reconcile_flags": null, "actions": ["park", "delete", "revoke"], "created_at": "2026-09-28T09:00:00.184066Z", "ready_at": "2026-09-28T09:03:41.502318Z", "parked_at": null, "parked_expires_at": null, "deleted_at": null, "revoked_at": null, "revoke_reason": null, "last_activity_at": "2026-09-28T09:25:00Z" } ``` 200 Own account ```json { "id": "fchost_c41f7a2e9b6d4e0a8f3c5b1d7e2a9c60", "offering_id": "digitalocean", "kind": "byo", "name": "gpu-free-runner", "organization": {"id": "org_3c1e9a7b5d2f4e8a9b0c6d1e2f3a4b5c", "name": "Acme Engineering"}, "user_id": "usr_7f3a9c2e1b8d4e6fa0c5b3d9e2f1a4c7", "project_group": null, "location_id": "fra1", "location_label": "fra1", "size_id": "c-8", "size_label": "c-8", "state": "deleted", "state_label": "Deleted", "transient": false, "step": null, "step_started_at": null, "state_changed_at": "2026-09-29T17:30:08.771045Z", "failure": null, "ipv4": null, "ipv6": null, "ssh_port": 22, "ssh_user": "forge", "bootstrap_host_key_pub": null, "host_key_pub": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExampleServerHostKeyForDocumentationOnly0000", "price": { "hourly": "0.2500", "monthly_cap": "168.00", "currency": "USD", "source": "digitalocean", "includes_vat": false, "catalog_version": "fc-3b8e1f0a9c42", "quoted_at": "2026-09-28T09:00:00.184066Z", "parked_per_gb_month": "0.0600", "price_verified": true }, "month_to_date": null, "notice": null, "idle_reminder": null, "reconcile_flags": { "leftover_resources": [ { "resource_type": "snapshot", "provider_resource_id": "178233410", "name": "forge-gpu-free-runner-park", "first_seen_at": "2026-09-29T17:45:02.310775Z", "last_seen_at": "2026-09-29T18:00:02.442019Z" } ], "message": "Some resources of this server still exist in your provider account and may still be charged there.", "checked_at": "2026-09-29T18:00:02.442019Z" }, "actions": [], "created_at": "2026-09-28T09:00:00.184066Z", "ready_at": "2026-09-28T09:02:48.071553Z", "parked_at": null, "parked_expires_at": null, "deleted_at": "2026-09-29T17:31:15.908612Z", "revoked_at": null, "revoke_reason": null, "last_activity_at": "2026-09-28T09:25:00Z" } ``` 404 Not Found ```json { "success": false, "error": { "code": "FORGE_COMPUTE_HOST_NOT_FOUND", "message": "This server could not be found. It may have been deleted.", "system_message": "Forge compute host not found", "type": "client_error", "status": 404, "details": {"resource": "forge_compute_host"}, "trace_id": "3f1c9a52-7d4e-4b8a-9c21-6e0d5f7a8b34", "timestamp": "2026-09-28T09:00:00Z" } } ``` ## Related Resources - [Forge cloud compute overview](/docs/api-reference/forge-compute/introduction) - [List billing organizations](/docs/api-reference/forge-compute/list-billing-organizations) - [Choose the default billing organization](/docs/api-reference/forge-compute/choose-billing-organization) - [List project groups](/docs/api-reference/forge-compute/list-project-groups) - [Register or update a project group](/docs/api-reference/forge-compute/put-project-group) - [Delete a project group](/docs/api-reference/forge-compute/delete-project-group) - [List compute offerings](/docs/api-reference/forge-compute/list-offerings) - [Get offering options](/docs/api-reference/forge-compute/get-offering-options) - [Resolve a free size](/docs/api-reference/forge-compute/resolve-offering-size) - [List connected accounts](/docs/api-reference/forge-compute/list-credentials) - [Connect a cloud account](/docs/api-reference/forge-compute/put-credential) - [Disconnect a cloud account](/docs/api-reference/forge-compute/delete-credential) - [Create a server](/docs/api-reference/forge-compute/create-host) - [List servers](/docs/api-reference/forge-compute/list-hosts) - [List your servers in every organization](/docs/api-reference/forge-compute/list-my-hosts) - [Get a server](/docs/api-reference/forge-compute/get-host) - [Get a server's daily cost and uptime](/docs/api-reference/forge-compute/get-host-usage) - [List a server's running intervals](/docs/api-reference/forge-compute/list-host-intervals) - [List a server's event history](/docs/api-reference/forge-compute/list-host-events) - [Report a setup step](/docs/api-reference/forge-compute/report-progress) - [Report the server's host key](/docs/api-reference/forge-compute/report-host-key) - [Mark a server ready](/docs/api-reference/forge-compute/report-ready) - [Report activity](/docs/api-reference/forge-compute/report-activity) - [Park a server](/docs/api-reference/forge-compute/park-host) - [Resume a server](/docs/api-reference/forge-compute/resume-host) - [Delete a server](/docs/api-reference/forge-compute/delete-host) - [Revoke a server](/docs/api-reference/forge-compute/revoke-host) - [Get compute settings](/docs/api-reference/forge-compute/get-settings) - [Update compute settings](/docs/api-reference/forge-compute/update-settings) - [Get spend limits](/docs/api-reference/forge-compute/get-limits) - [Change the organization's limits](/docs/api-reference/forge-compute/update-organization-limits) - [Set your own limit](/docs/api-reference/forge-compute/update-my-limit) - [List member limits](/docs/api-reference/forge-compute/list-member-limits) - [Set a member's limit](/docs/api-reference/forge-compute/update-member-limit) - [Delete a leftover resource](/docs/api-reference/forge-compute/delete-orphan)