Skip to content
/
List servers
Last updated

List servers

Lists the Forge cloud servers you created in the acting organization (your current one, or the one named in organization_id), newest first, each as the server object. Deleted servers stay in the list for seven days after they were deleted. With scope=org it lists every member's servers, so an organization admin can see — and stop — everything the organization pays for. To list your servers in every organization at once, use List your servers in every organization.

Callers holding manage_forge also receive orphans: resources Forge labelled in the organization's own (bring-your-own) provider accounts that no server Forge manages owns any more, such as a server left behind by an interrupted delete or one forgotten when its account was disconnected with forget_hosts=true, with what each costs at the provider. Remove one with Delete a leftover resource. Resources in Aitronos' own accounts are never listed; Aitronos cleans those up itself.

Requires a bearer token (or API key) whose principal holds the use_forge capability in the acting organization; scope=org requires manage_forge. It works while Forge cloud compute is switched off. An organization API key has no user of its own, so scope=mine lists no servers for it.

GEThttps://api.aitronos.com/v1/forge/compute/hosts

Query Parameters

scope string optional

mine (default) lists the servers you created; org lists every member's servers and requires manage_forge.

organization_id string optional

The organization to act in. Defaults to your current organization. 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

hosts array — the servers, newest first, each a server object. A server whose record cannot be read is left out rather than failing the whole list.

orphans array — leftover resources in the organization's own provider accounts. Always empty for callers without manage_forge. Each entry:

  • offering_id string — the bring-your-own offering whose account holds the resource.
  • provider_resource_id string — the resource's id at the provider. Some providers' ids contain a /.
  • resource_type string — server, snapshot, ssh_key or firewall.
  • name string or null — the resource's name at the provider.
  • hourly string or null — what the resource costs per hour at the provider, in currency; null when unknown or not charged by the hour.
  • currency string or null — the currency of hourly.
  • first_seen_at string or null — when Forge first found the resource (UTC).
  • last_seen_at string — when Forge last found it (UTC).
{
  "hosts": [
    {
      "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
    },
    {
      "id": "fchost_0b7e4d21c9a84f6b8d3e5a1c7f902e64",
      "offering_id": "aitronos",
      "kind": "managed",
      "name": "nightly-tests",
      "organization": {"id": "org_3c1e9a7b5d2f4e8a9b0c6d1e2f3a4b5c", "name": "Acme Engineering"},
      "user_id": "usr_2c6b8e1f4a9d4c7e8b0f3a5d6e1c9b27",
      "project_group": null,
      "location_id": "eu-central",
      "location_label": "Germany",
      "size_id": "std-8",
      "size_label": "8 vCPU · 32 GB",
      "state": "parked",
      "state_label": "Parked. The server is saved and not running",
      "transient": false,
      "step": null,
      "step_started_at": null,
      "state_changed_at": "2026-09-28T18:03:40.905112Z",
      "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.42",
        "monthly_cap": "261.55",
        "currency": "CHF",
        "source": "aitronos",
        "includes_vat": false,
        "catalog_version": "fc-3b8e1f0a9c42",
        "quoted_at": "2026-09-27T14:12:09.551208Z",
        "parked_per_gb_month": "0.0269",
        "price_verified": true
      },
      "month_to_date": "11.76",
      "notice": null,
      "idle_reminder": null,
      "reconcile_flags": null,
      "actions": ["resume", "delete"],
      "created_at": "2026-09-27T14:12:09.551208Z",
      "ready_at": "2026-09-27T14:15:02.300417Z",
      "parked_at": "2026-09-28T18:03:40.905112Z",
      "parked_expires_at": "2026-10-28T18:03:40.905112Z",
      "deleted_at": null,
      "revoked_at": null,
      "revoke_reason": null,
      "last_activity_at": "2026-09-28T06:40:00Z"
    }
  ],
  "orphans": [
    {
      "offering_id": "digitalocean",
      "provider_resource_id": "512399871",
      "resource_type": "server",
      "name": "forge-build-box",
      "hourly": "0.2500",
      "currency": "USD",
      "first_seen_at": "2026-09-27T21:40:02.551730Z",
      "last_seen_at": "2026-09-28T08:55:02.118904Z"
    }
  ]
}

Errors

StatusCodeWhen
401AUTHENTICATION_REQUIREDNo valid credential.
403ORGANIZATION_ACCESS_DENIEDorganization_id or X-Organization-Id names an organization you are not an active member of.
403INSUFFICIENT_PERMISSIONSThe caller does not hold use_forge, or asked for scope=org without manage_forge.
422VALIDATION_ERRORscope is neither mine nor org.
cURL
curl "https://api.aitronos.com/v1/forge/compute/hosts?scope=org" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response:

{
  "hosts": [
    {
      "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
    },
    {
      "id": "fchost_0b7e4d21c9a84f6b8d3e5a1c7f902e64",
      "offering_id": "aitronos",
      "kind": "managed",
      "name": "nightly-tests",
      "organization": {"id": "org_3c1e9a7b5d2f4e8a9b0c6d1e2f3a4b5c", "name": "Acme Engineering"},
      "user_id": "usr_2c6b8e1f4a9d4c7e8b0f3a5d6e1c9b27",
      "project_group": null,
      "location_id": "eu-central",
      "location_label": "Germany",
      "size_id": "std-8",
      "size_label": "8 vCPU · 32 GB",
      "state": "parked",
      "state_label": "Parked. The server is saved and not running",
      "transient": false,
      "step": null,
      "step_started_at": null,
      "state_changed_at": "2026-09-28T18:03:40.905112Z",
      "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.42",
        "monthly_cap": "261.55",
        "currency": "CHF",
        "source": "aitronos",
        "includes_vat": false,
        "catalog_version": "fc-3b8e1f0a9c42",
        "quoted_at": "2026-09-27T14:12:09.551208Z",
        "parked_per_gb_month": "0.0269",
        "price_verified": true
      },
      "month_to_date": "11.76",
      "notice": null,
      "idle_reminder": null,
      "reconcile_flags": null,
      "actions": ["resume", "delete"],
      "created_at": "2026-09-27T14:12:09.551208Z",
      "ready_at": "2026-09-27T14:15:02.300417Z",
      "parked_at": "2026-09-28T18:03:40.905112Z",
      "parked_expires_at": "2026-10-28T18:03:40.905112Z",
      "deleted_at": null,
      "revoked_at": null,
      "revoke_reason": null,
      "last_activity_at": "2026-09-28T06:40:00Z"
    }
  ],
  "orphans": [
    {
      "offering_id": "digitalocean",
      "provider_resource_id": "512399871",
      "resource_type": "server",
      "name": "forge-build-box",
      "hourly": "0.2500",
      "currency": "USD",
      "first_seen_at": "2026-09-27T21:40:02.551730Z",
      "last_seen_at": "2026-09-28T08:55:02.118904Z"
    }
  ]
}
Previous page
Next page