Skip to main content
GET
/
v0
/
servers
List servers
curl --request GET \
  --url https://controller.platform.simplecloud.app/v0/servers \
  --header 'X-Network-ID: <x-network-id>' \
  --header 'X-Network-Secret: <x-network-secret>'
{
  "count": 5,
  "servers": [
    {
      "cpu_usage": 25.5,
      "created_at": "2023-01-01T12:00:00Z",
      "ip": "127.0.0.1",
      "last_activity": "2023-01-01T12:00:00Z",
      "max_memory": 2048,
      "max_players": 20,
      "memory_usage": 512,
      "min_memory": 1024,
      "network_id": "123e4567-e89b-12d3-a456-426614174000",
      "numerical_id": 1,
      "persistent_server": {
        "active": true,
        "created_at": "<string>",
        "id": "<string>",
        "max_memory": 123,
        "max_players": 123,
        "min_memory": 123,
        "name": "<string>",
        "properties": {},
        "serverhost_id": "<string>",
        "source": {
          "blueprint": "123e4567-e89b-12d3-a456-426614174000",
          "image": "ghcr.io/user/custom-image:latest",
          "type": "blueprint"
        },
        "tags": [
          "<string>"
        ],
        "type": "<string>",
        "updated_at": "<string>",
        "workflows": {
          "manual": [
            "<string>"
          ],
          "when": {
            "start": [
              "<string>"
            ],
            "stop": [
              "<string>"
            ]
          }
        }
      },
      "persistent_server_id": "123e4567-e89b-12d3-a456-426614174000",
      "player_count": 5,
      "port": 25565,
      "properties": {},
      "server_group": {
        "created_at": "<string>",
        "deployment_config": {},
        "deployment_strategy": "<string>",
        "id": "<string>",
        "name": "<string>",
        "properties": {},
        "scaling_config": {},
        "source": {
          "blueprint": {
            "configurator": "<string>",
            "created_at": "<string>",
            "id": "<string>",
            "minecraft_version": "<string>",
            "name": "<string>",
            "runtime_config": {},
            "server_software": "<string>",
            "server_url": "<string>",
            "software_version": "<string>",
            "updated_at": "<string>",
            "workflow_steps": [
              "<string>"
            ]
          },
          "image": "<string>",
          "type": "<string>"
        },
        "tags": [
          "<string>"
        ],
        "type": "<string>",
        "updated_at": "<string>",
        "workflows_config": {}
      },
      "server_group_id": "123e4567-e89b-12d3-a456-426614174000",
      "server_id": "123e4567-e89b-12d3-a456-426614174000",
      "serverhost_id": "123e4567-e89b-12d3-a456-426614174000",
      "state": "AVAILABLE",
      "updated_at": "2023-01-01T12:00:00Z"
    }
  ]
}

Headers

X-Network-ID
string
required

Network ID

X-Network-Secret
string
required

Network Secret

Query Parameters

server_group_id
string

Filter by server group ID(s), comma-separated

state
string

Filter by state(s), comma-separated (e.g., RUNNING,STARTING)

serverhost_id
string

Filter by serverhost ID

persistent_server_id
string

Filter by persistent server ID

type
string

Filter by type(s), comma-separated (matches server group type OR persistent server type)

name
string

Filter by name(s), comma-separated (matches server group name OR persistent server name)

tags
string

Filter by tag(s), comma-separated (matches if any tag matches in server group OR persistent server)

numerical_id
string

Filter by numerical ID(s), comma-separated (e.g., 1,5,10)

sort_by
string

Sort field: created_at, updated_at, numerical_id, state

sort_order
enum<string>
default:asc

Sort order: asc, desc

Available options:
asc,
desc

Response

OK

Response for listing servers

count
integer
Example:

5

servers
object[]