---
title: List Servers
description: "Returns a paginated list of all servers in your team. Supports filtering by search term and status. Requires the read:servers scope."
url: "https://betterdocs.shahrear.msf.bd/index.php/docs/hell0-boys-docs/hell0-boys/servers/list-servers/"
updated: "2026-08-20"
category: hell0 boys / Servers
---

# List Servers

GET`/servers`

## Code Samples

```curl

                curl --request GET \
  --url 'https://app.xcloud.host/api/v1/servers' \
  --header 'Authorization: Bearer YOUR_TOKEN'

                const response = await fetch('https://app.xcloud.host/api/v1/servers', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
});

const data = await response.json();
console.log(data);

                import requests

headers = {
    "Authorization": "Bearer YOUR_TOKEN"
}

response = requests.get("https://app.xcloud.host/api/v1/servers", headers=headers)

print(response.json())

                <?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://app.xcloud.host/api/v1/servers',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => [
  'Authorization: Bearer YOUR_TOKEN'
  ],
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

                using System.Net.Http;

var client = new HttpClient();
var request = new HttpRequestMessage(new HttpMethod("GET"), "https://app.xcloud.host/api/v1/servers");
request.Headers.Add("Authorization", "Bearer YOUR_TOKEN");
var response = await client.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);

                import java.net.URI;
import java.net.http.*;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://app.xcloud.host/api/v1/servers"))
    .header("Authorization", "Bearer YOUR_TOKEN")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
```

## Response

```json

                {
    "success": true,
    "message": "Servers retrieved successfully.",
    "data": {
        "data": [
            {
                "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                "name": "xcloud",
                "status": "active",
                "ip_address": "203.0.113.42",
                "provider": "digitalocean",
                "stack": "lemp",
                "php_version": "8.2",
                "region": "nyc1",
                "created_at": "2024-06-01T09:00:00Z"
            }
        ],
        "meta": {
            "current_page": 1,
            "last_page": 3,
            "per_page": 15,
            "total": 42
        }
    }
}

                {
    "success": false,
    "message": "Unauthenticated.",
    "data": null
}

                {
    "success": false,
    "message": "This action is unauthorized. Your token is missing the required scope.",
    "data": null
}
```

Returns a paginated list of all servers in your [Team](https://betterdocs.shahrear.msf.bd/encyclopedia/team/). Supports filtering by search term and status. Requires the `read:servers` scope.

## [Query](https://betterdocs.shahrear.msf.bd/encyclopedia/query/) Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `search` | string | Optional | Filter by [Server](https://betterdocs.shahrear.msf.bd/encyclopedia/server/) name or IP [Address](https://betterdocs.shahrear.msf.bd/encyclopedia/address/) |
| `status` | string | Optional | Filter by [Server](https://betterdocs.shahrear.msf.bd/encyclopedia/server/) status |
| `page` | integer | Optional | Page number (default [1](https://betterdocs.shahrear.msf.bd/encyclopedia/1/)) |
| `per_page` | integer | Optional | Items per page (default 15, max 100) |

## Responses

### 200 — Paginated list of servers

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `success` | boolean | Optional |  |
| `message` | string | Optional |  |
| `data` | object | Optional |  |
| `data` | object | Optional |  |
| `data.data` | array of object | Optional |  |
| `data.meta` | object | Optional |  |

```json

                {
    "success": true,
    "message": "Servers retrieved successfully.",
    "data": {
        "data": [
            {
                "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                "name": "xcloud",
                "status": "active",
                "ip_address": "203.0.113.42",
                "provider": "digitalocean",
                "stack": "lemp",
                "php_version": "8.2",
                "region": "nyc1",
                "created_at": "2024-06-01T09:00:00Z"
            }
        ],
        "meta": {
            "current_page": 1,
            "last_page": 3,
            "per_page": 15,
            "total": 42
        }
    }
}
```

### 401 — Missing or invalid authentication token

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `success` | boolean | Optional |  |
| `message` | string | Optional |  |
| `data` | object | Optional |  |

```json

                {
    "success": false,
    "message": "Unauthenticated.",
    "data": null
}
```

### 403 — Token lacks the required scope

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `success` | boolean | Optional |  |
| `message` | string | Optional |  |
| `data` | object | Optional |  |

```json

                {
    "success": false,
    "message": "This action is unauthorized. Your token is missing the required scope.",
    "data": null
}
```