# How to Get a Fleet Overview of All Servers and Sites with the xCloud Public API and MCP

> Read every xCloud server and site in one call with GET /api/v1/overview or the overview_show MCP tool: status counts, usage warnings and truncation.

The fleet overview returns every server and site you can access in your xCloud team in one request, with each server's stored status, its usage warnings and status counts for the whole team. Call it as `GET /api/v1/overview` from a script, or ask an AI agent to run the `overview_show` MCP tool. It is the fastest way to build a fleet home page, a morning health check or a "which servers need attention" report without calling each server's detail endpoint.

The overview is new in xCloud v2.9.6.1.

## What the overview returns

The response has four parts. All values come from data xCloud has already stored; the request does not contact your servers.

| Field | What it holds |
|---|---|
| `servers` | Up to 500 servers: `uuid`, `name`, `provider`, `type` (the server stack), `status`, `state`, `is_connected` and `usage` |
| `sites` | Up to 500 sites: `uuid`, `name`, `server_uuid`, `type`, `status` and `php_version` |
| `counts` | The number of servers and of sites per stored status, for **every** resource you can access, before the 500 cap |
| `truncation` | For `servers` and for `sites`: whether the list was cut (`truncated`), the `limit` (500) and the `next_action` to read the rest |

Each server's `usage` object carries the same warnings the xCloud dashboard shows:

| Usage field | Meaning |
|---|---|
| `cpu_percent`, `ram_percent`, `disk_percent` | The last stored readings, or `null` when xCloud has no disk snapshot for the server |
| `cpu_high` | CPU use is above 80% |
| `ram_low` | Less than 10% of RAM is available |
| `disk_low` | A watched filesystem (`/var/www`, `/var/lib/mysql` or `/`) has less than 5 GB free |
| `disk_critical` | A watched filesystem has less than 1 GB free |

`state` is the server's summary state as the dashboard shows it: `Initial`, `Processing`, `Success`, `Warning`, `Disconnected` or `Error`, or `null` when none applies.

## Prerequisites

- An xCloud API token with **both** `read:servers` and `read:sites`. See [How to Access the xCloud API](/docs/how-to-access-the-xcloud-api/) to create one.
- For MCP, the token or connection must also allow MCP (`mcp:invoke`). An OAuth connection from an MCP client works too. See [How to Connect xCloud MCP to Your AI Agent](/docs/how-to-connect-xcloud-mcp-to-ai-agent/).
- The **Team Admin** or **Server Admin** role in the team. A **Site Admin** cannot read the overview, because it includes server summaries.

The overview is read-only. A token with no write permissions is enough, and is the safer choice for dashboards and reports.

## Step 1: Call the overview endpoint

Send a `GET` request with your token. Store the token in an environment variable instead of pasting it into the command.

```bash
export XCLOUD_TOKEN='xc_live_xxxxxxxxxxxx'

curl 'https://app.xcloud.host/api/v1/overview' \
  --header "Authorization: Bearer $XCLOUD_TOKEN" \
  --header 'Accept: application/json'
```

**Expected result:** a `200` response with the servers, sites, counts and truncation for the token's default team. A shortened example:

```json
{
  "success": true,
  "message": "Success",
  "data": {
    "servers": [
      {
        "uuid": "9a1f0c2e-4b7d-4e8a-9c3f-1d2e3f4a5b6c",
        "name": "docs-demo",
        "provider": "hetzner",
        "type": "nginx",
        "status": "provisioned",
        "state": "Success",
        "is_connected": true,
        "usage": {
          "cpu_percent": 12.5,
          "ram_percent": 44.1,
          "disk_percent": 93,
          "cpu_high": false,
          "ram_low": false,
          "disk_low": false,
          "disk_critical": false
        }
      }
    ],
    "sites": [
      {
        "uuid": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
        "name": "example.com",
        "server_uuid": "9a1f0c2e-4b7d-4e8a-9c3f-1d2e3f4a5b6c",
        "type": "wordpress",
        "status": "provisioned",
        "php_version": "8.3"
      }
    ],
    "counts": {
      "servers": { "provisioned": 1, "provisioning": 0, "error": 0 },
      "sites": { "provisioned": 1, "provisioning": 0, "provisioning_failed": 0 }
    },
    "truncation": {
      "servers": { "truncated": false, "limit": 500, "next_action": null },
      "sites": { "truncated": false, "limit": 500, "next_action": null }
    }
  }
}
```

`counts` lists **every** stored status for servers and for sites, including the ones at `0`, so a client can show a fixed set of tiles. The example above is shortened.

To read another granted team, add the `X-Team-Id` header with that team's UUID from `GET /api/v1/teams`. See [Multi-Team API Tokens and MCP Access](/docs/multi-team-api-tokens-and-mcp-access/).

## Step 2: Find the servers that need attention

Filter the response for servers with a warning flag or a disconnected agent. This example uses `jq`:

```bash
curl -s 'https://app.xcloud.host/api/v1/overview' \
  --header "Authorization: Bearer $XCLOUD_TOKEN" \
  --header 'Accept: application/json' \
  | jq '.data.servers[]
        | select(.is_connected == false or .usage.cpu_high or .usage.ram_low or .usage.disk_low)
        | {name, state, usage}'
```

**Expected result:** one JSON object per server that needs a look, or no output when every server is healthy. A server with `disk_critical: true` is about to fail writes; free disk space on it first.

The usage figures are the last stored readings, not a live measurement. To see the current values and history for one server, open it in the dashboard as described in [How To Monitor Server Resource Usage with xCloud](/docs/how-to-monitor-server-resource-usage-with-xcloud/). For the same fleet view in the dashboard, see [xCloud Monitoring](/docs/monitor-all-your-servers-with-xcloud-monitoring/).

## Step 3: Read the rest when a list is truncated

Each list holds at most 500 entries, in the order the servers or sites were created. When a team has more, the counts stay complete and `truncation` tells you where the rest is:

```json
"truncation": {
  "servers": { "truncated": false, "limit": 500, "next_action": null },
  "sites": { "truncated": true, "limit": 500, "next_action": "sites.index" }
}
```

`next_action` names the paginated list operation: `servers.index` is `GET /api/v1/servers`, and `sites.index` is `GET /api/v1/sites`. Both take `page` and `per_page` (up to 100):

```bash
curl 'https://app.xcloud.host/api/v1/sites?page=1&per_page=100' \
  --header "Authorization: Bearer $XCLOUD_TOKEN" \
  --header 'Accept: application/json'
```

**Expected result:** the first 100 sites. Increase `page` until you have read every site. Use the totals in `counts` to check that your client has them all.

## Step 4: Ask an AI agent for the overview over MCP

In an MCP client connected to xCloud, ask in plain language:

```text
Give me an overview of all my xCloud servers and sites. List any server that is
disconnected or has a CPU, RAM or disk warning, and tell me how many sites are
not provisioned.
```

The agent runs the `overview_show` tool, which calls the same endpoint and returns the same data. On the compact MCP profile, the agent finds the `overview.show` operation with search and runs it through `xcloud_execute_read`, which changes nothing.

**Expected result:** a summary of your servers and sites, with the servers that need attention named. To ask about another granted team, name the team in the prompt.

If a list was truncated, the agent can follow `next_action` and page through `servers.index` or `sites.index` the same way.

## What the overview leaves out

- **System sites**, such as a server's phpMyAdmin site, are not in `sites` or in `counts`.
- **Resources you cannot access.** A Server Admin with access to selected servers sees only those servers and their sites, and the counts cover only them. Other teams never appear.
- **Secrets and addresses.** Server passwords and public IPs are not in the response. Use the server detail endpoints for connection details.
- **Live metrics.** No command runs on your servers. A server with no stored disk snapshot shows `null` usage and `false` warning flags.

## Troubleshooting

| Response | Cause | Fix |
|---|---|---|
| `401` | No bearer token, or the token was revoked | Send `Authorization: Bearer <token>` with an active token |
| `403` | The token is missing `read:servers` or `read:sites` | Create a token with both permissions. Tokens cannot be edited |
| `403` with both permissions | Your team role is Site Admin | Ask the team owner for the Server Admin or Team Admin role |
| `403` with `X-Team-Id` | The team is not granted to the token | Call `GET /api/v1/teams` and use a returned UUID |
| A server is missing | You do not have access to that server, or the list was truncated | Check `counts` and `truncation`, then your server access in the team |
| All usage values are `null` | xCloud has no disk snapshot for the server yet | Wait for monitoring to store one, or check the server's connection |

## Frequently asked questions

### Why does GET /api/v1/overview return 403 when my token can list servers?

The overview needs both read:servers and read:sites on the token, and your team role must be Team Admin or Server Admin. A token with only one of the two permissions, or a Site Admin, receives 403.

### Does the overview contact my servers or refresh their metrics?

No. It reads the status and the last monitoring snapshot xCloud has already stored, the same data the dashboard shows. It runs no command on your servers.

### What happens when I have more than 500 servers or sites?

Each list stops at 500 entries in creation order, but the counts still cover everything you can access. truncation.servers or truncation.sites then reports truncated as true and names servers.index or sites.index, the paginated list to read the rest from.

### Why are a server's usage values null?

xCloud has no disk snapshot for that server yet, so every usage figure is unknown. The percentages are null and the warning flags are false until monitoring stores a snapshot.

## Next steps

- Read the full request and response format in the [xCloud Public API reference](https://app.xcloud.host/api/v1/docs), and authentication and rate limits in the [xCloud API documentation overview](/docs/xcloud-api/).
- Deploy from the same token with [Deploy Git Projects with the xCloud Public API and MCP](/docs/deploy-git-projects-with-xcloud-public-api-and-mcp/).

If you run into any issues with the fleet overview, feel free to reach out to our [support team](/docs/access-built-in-support-portal-in-xcloud/) for help.