---
title: "List your servers (agents)"
method: GET
path: "/platform/servers"
tags: ["Platform"]
---

# List your servers (agents)

`GET /platform/servers`

## Request

- Base URL: `https://api.imprezahost.com/v1`
- URL: `https://api.imprezahost.com/v1/platform/servers`
- Auth: API key in header `X-API-Key` and API key in header `X-API-Secret`

Returns every agent owned by the authenticated client — both
Impreza-provisioned VPSes (with `service_id` linking back to
the underlying hosting service) and bring-your-own external
boxes. Agents whose IP no longer maps to one of your active
services are filtered out.

agent_update includes installed_version, latest_version,
update_available (null if unknown), check_command and update_command.
The customer runs the command after deployments finish. This read
endpoint does not execute updates or modify the server.
update_policy reports the server's channel (stable/beta/pinned),
pinned version, maintenance window and end-of-life status; pinned
servers never receive update offers.

Each server reports its **capacity** — what the agent last
measured on the box, not what the plan promises: CPU load, free
and total memory, free and total disk, with a percentage for each.
That is what makes "which of my servers should this go on?" a
question the caller can answer before deploying, instead of after
running out of room.

The figures come from the agent's heartbeat, so `reported_at` says
when they were true and **`stale` is `true` once they are older
than fifteen minutes** — a quiet box looks idle otherwise, and idle
is exactly the wrong thing to read into silence. Every figure is
`null` on a server that has never reported.

## Response `200`

Server list

## Other responses

- `401`: Invalid or missing API credentials

---

[API](https://skmtc.dev/imprezahost/apis/impreza-host-public-api.md) · [All operations](https://skmtc.dev/imprezahost/apis/impreza-host-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/imprezahost/apis/impreza-host-public-api/revisions/db86511f604f?raw)