Documentação da API Alojamento web acessível a todos
PT

Idioma

Français English Deutsch Español Português Italiano
Visitar a LWS
API VPS KVM

Documentação

API de Domínios e E-mail API VPS KVM
Início da documentação

Ler as métricas instantâneas

GET /api/v1/servers/{vmid}/metrics

operationIdgetServerMetrics

Nível exigido
Apenas leitura
Quota
leitura, 3600 chamadas por hora

Leitura pontual. disk_read, disk_write, net_in e net_out são contadores cumulativos desde o arranque da máquina: o débito obtém-se dividindo a sua diferença pelo intervalo entre duas leituras. Os volumes estão em bytes.

cpu é um rácio entre 0 e 1, tal como o hipervisor o reporta; cpu_count acompanha-o. Uma medição que o hipervisor não enviou é null, nunca 0: um 0 falsearia qualquer cálculo de débito.

A leitura é guardada em cache durante 15 segundos: uma chamada mais próxima devolve a mesma leitura, com o mesmo sampled_at. Calcule, por isso, o débito entre duas leituras espaçadas de pelo menos 15 segundos.

Parâmetros do caminho

vmid string obrigatório

Identificador do VPS. Tem de pertencer à conta e ao âmbito da chave.

padrão ^\d+$ Exemplo: 116807

Respostas

200

Leitura instantânea

 
{
  "data": {
    "cpu": 0.9979,
    "cpu_count": 6,
    "memory_used": 3923214336,
    "memory_total": 12884901888,
    "disk_read": 440382802,
    "disk_write": 109911552,
    "net_in": 13343421,
    "net_out": 1733737,
    "uptime": 4291,
    "sampled_at": "2026-08-07T16:14:54+02:00"
  }
}
Campos da resposta 11
  • data object

    Metrics

    obrigatório
  • cpu number (double)

    Carga, rácio entre 0 e 1

  • cpu_count integer (int64)
  • memory_used integer (int64)

    Bytes

  • memory_total integer (int64)

    Bytes

  • disk_read integer (int64)

    Bytes lidos desde o arranque (cumulativo)

  • disk_write integer (int64)

    Bytes escritos desde o arranque (cumulativo)

  • net_in integer (int64)

    Bytes recebidos desde o arranque (cumulativo)

  • net_out integer (int64)

    Bytes enviados desde o arranque (cumulativo)

  • uptime integer (int64)
  • sampled_at string (date-time)
401

Autenticação recusada: invalid_token — cabeçalho Authorization ausente ou mal formado, ou chave desconhecida; access_disabled — acesso à API cortado para esta conta, ou serviço de API momentaneamente suspenso pela LWS.

cabeçalho Authorization ausente ou mal formado, ou chave desconhecida

{
  "type": "https://docs.lws.fr/kvm/errors/invalid-token",
  "title": "Authentification invalide",
  "status": 401,
  "code": "invalid_token",
  "detail": "Clé inconnue ou révoquée.",
  "request_id": "3f9a1c07b2e45d18"
}

acesso à API cortado para esta conta, ou serviço de API momentaneamente suspenso pela LWS

{
  "type": "https://docs.lws.fr/kvm/errors/access-disabled",
  "title": "Accès API désactivé",
  "status": 401,
  "code": "access_disabled",
  "detail": "L'accès API est désactivé pour ce compte. Réactivez-le depuis la page « API / MCP » du panel.",
  "request_id": "3f9a1c07b2e45d18"
}
Campos da resposta 18
  • type string (uri)

    Exemplo: https://docs.lws.fr/kvm/errors/vm-not-found

    obrigatório
  • title string

    Título curto

    Exemplo: VPS introuvable

    obrigatório
  • status integer (int64)

    Estado HTTP

    Exemplo: 404

    obrigatório
  • code string

    Código de máquina estável (ver «Erros» em Primeiros passos)

    Exemplo: vm_not_found

    obrigatório
  • detail string

    Mensagem detalhada

    Exemplo: Aucun VPS 999999 sur ce compte.

    obrigatório
  • request_id string

    Identificador do pedido, a comunicar ao suporte

    Exemplo: 3f9a1c07b2e45d18

    obrigatório
  • errors object

    validation_failed: mensagem por parâmetro incorreto

  • required_level string

    insufficient_scope: nível exigido pela operação

    um de: read, exploitation, full

  • task_id string

    task_already_running: tarefa em curso neste VPS

    Exemplo: tsk_000002d5

  • family string

    rate_limited: família de quota esgotada

    um de: read, mutation, heavy

  • limit integer (int64)

    rate_limited: limite horário da família

  • retry_after integer (int64)

    rate_limited: segundos a aguardar

  • lock string

    server_locked: bloqueio aplicado pelo hipervisor (backup, snapshot, suspended…)

    Exemplo: snapshot

  • reason string

    server_locked: operation_in_progress, há uma operação em curso, tente novamente após Retry-After; suspended, o VPS está em hibernação, inicie-o primeiro; support_notified, bloqueio anómalo, a equipa LWS foi avisada e está a intervir

    um de: operation_in_progress, suspended, support_notified

  • maintenance object

    server_maintenance: natureza da intervenção, início e fim previsto (null para um incidente)

  • kind string

    um de: works, incident

  • started_at string (date-time)
  • expected_end string (date-time)
403

Acesso recusado: ip_not_allowed — endereço de chamada não autorizado.

 
{
  "type": "https://docs.lws.fr/kvm/errors/ip-not-allowed",
  "title": "Adresse non autorisée",
  "status": 403,
  "code": "ip_not_allowed",
  "detail": "L'adresse 203.0.113.10 ne figure pas parmi les adresses autorisées de ce compte.",
  "request_id": "3f9a1c07b2e45d18"
}
Campos da resposta 18
  • type string (uri)

    Exemplo: https://docs.lws.fr/kvm/errors/vm-not-found

    obrigatório
  • title string

    Título curto

    Exemplo: VPS introuvable

    obrigatório
  • status integer (int64)

    Estado HTTP

    Exemplo: 404

    obrigatório
  • code string

    Código de máquina estável (ver «Erros» em Primeiros passos)

    Exemplo: vm_not_found

    obrigatório
  • detail string

    Mensagem detalhada

    Exemplo: Aucun VPS 999999 sur ce compte.

    obrigatório
  • request_id string

    Identificador do pedido, a comunicar ao suporte

    Exemplo: 3f9a1c07b2e45d18

    obrigatório
  • errors object

    validation_failed: mensagem por parâmetro incorreto

  • required_level string

    insufficient_scope: nível exigido pela operação

    um de: read, exploitation, full

  • task_id string

    task_already_running: tarefa em curso neste VPS

    Exemplo: tsk_000002d5

  • family string

    rate_limited: família de quota esgotada

    um de: read, mutation, heavy

  • limit integer (int64)

    rate_limited: limite horário da família

  • retry_after integer (int64)

    rate_limited: segundos a aguardar

  • lock string

    server_locked: bloqueio aplicado pelo hipervisor (backup, snapshot, suspended…)

    Exemplo: snapshot

  • reason string

    server_locked: operation_in_progress, há uma operação em curso, tente novamente após Retry-After; suspended, o VPS está em hibernação, inicie-o primeiro; support_notified, bloqueio anómalo, a equipa LWS foi avisada e está a intervir

    um de: operation_in_progress, suspended, support_notified

  • maintenance object

    server_maintenance: natureza da intervenção, início e fim previsto (null para um incidente)

  • kind string

    um de: works, incident

  • started_at string (date-time)
  • expected_end string (date-time)
404

Recurso não encontrado: vm_not_found — VPS inexistente ou fora do âmbito da chave.

 
{
  "type": "https://docs.lws.fr/kvm/errors/vm-not-found",
  "title": "VPS introuvable",
  "status": 404,
  "code": "vm_not_found",
  "detail": "Aucun VPS 999999 sur ce compte.",
  "request_id": "3f9a1c07b2e45d18"
}
Campos da resposta 18
  • type string (uri)

    Exemplo: https://docs.lws.fr/kvm/errors/vm-not-found

    obrigatório
  • title string

    Título curto

    Exemplo: VPS introuvable

    obrigatório
  • status integer (int64)

    Estado HTTP

    Exemplo: 404

    obrigatório
  • code string

    Código de máquina estável (ver «Erros» em Primeiros passos)

    Exemplo: vm_not_found

    obrigatório
  • detail string

    Mensagem detalhada

    Exemplo: Aucun VPS 999999 sur ce compte.

    obrigatório
  • request_id string

    Identificador do pedido, a comunicar ao suporte

    Exemplo: 3f9a1c07b2e45d18

    obrigatório
  • errors object

    validation_failed: mensagem por parâmetro incorreto

  • required_level string

    insufficient_scope: nível exigido pela operação

    um de: read, exploitation, full

  • task_id string

    task_already_running: tarefa em curso neste VPS

    Exemplo: tsk_000002d5

  • family string

    rate_limited: família de quota esgotada

    um de: read, mutation, heavy

  • limit integer (int64)

    rate_limited: limite horário da família

  • retry_after integer (int64)

    rate_limited: segundos a aguardar

  • lock string

    server_locked: bloqueio aplicado pelo hipervisor (backup, snapshot, suspended…)

    Exemplo: snapshot

  • reason string

    server_locked: operation_in_progress, há uma operação em curso, tente novamente após Retry-After; suspended, o VPS está em hibernação, inicie-o primeiro; support_notified, bloqueio anómalo, a equipa LWS foi avisada e está a intervir

    um de: operation_in_progress, suspended, support_notified

  • maintenance object

    server_maintenance: natureza da intervenção, início e fim previsto (null para um incidente)

  • kind string

    um de: works, incident

  • started_at string (date-time)
  • expected_end string (date-time)
429

Quota excedida: rate_limited — quota horária da família esgotada.

 
{
  "type": "https://docs.lws.fr/kvm/errors/rate-limited",
  "title": "Quota dépassé",
  "status": 429,
  "code": "rate_limited",
  "detail": "Quota dépassé pour les opérations de type « read » : 3600 appels par heure. Réessayez dans 37 seconde(s).",
  "request_id": "3f9a1c07b2e45d18",
  "family": "read",
  "limit": 3600,
  "retry_after": 37
}
Campos da resposta 18
  • type string (uri)

    Exemplo: https://docs.lws.fr/kvm/errors/vm-not-found

    obrigatório
  • title string

    Título curto

    Exemplo: VPS introuvable

    obrigatório
  • status integer (int64)

    Estado HTTP

    Exemplo: 404

    obrigatório
  • code string

    Código de máquina estável (ver «Erros» em Primeiros passos)

    Exemplo: vm_not_found

    obrigatório
  • detail string

    Mensagem detalhada

    Exemplo: Aucun VPS 999999 sur ce compte.

    obrigatório
  • request_id string

    Identificador do pedido, a comunicar ao suporte

    Exemplo: 3f9a1c07b2e45d18

    obrigatório
  • errors object

    validation_failed: mensagem por parâmetro incorreto

  • required_level string

    insufficient_scope: nível exigido pela operação

    um de: read, exploitation, full

  • task_id string

    task_already_running: tarefa em curso neste VPS

    Exemplo: tsk_000002d5

  • family string

    rate_limited: família de quota esgotada

    um de: read, mutation, heavy

  • limit integer (int64)

    rate_limited: limite horário da família

  • retry_after integer (int64)

    rate_limited: segundos a aguardar

  • lock string

    server_locked: bloqueio aplicado pelo hipervisor (backup, snapshot, suspended…)

    Exemplo: snapshot

  • reason string

    server_locked: operation_in_progress, há uma operação em curso, tente novamente após Retry-After; suspended, o VPS está em hibernação, inicie-o primeiro; support_notified, bloqueio anómalo, a equipa LWS foi avisada e está a intervir

    um de: operation_in_progress, suspended, support_notified

  • maintenance object

    server_maintenance: natureza da intervenção, início e fim previsto (null para um incidente)

  • kind string

    um de: works, incident

  • started_at string (date-time)
  • expected_end string (date-time)
502

Dependência inacessível: hypervisor_unreachable; upstream_unavailable — inventário dos VPS momentaneamente indisponível.

Hipervisor inacessível

{
  "type": "https://docs.lws.fr/kvm/errors/hypervisor-unreachable",
  "title": "Hyperviseur injoignable",
  "status": 502,
  "code": "hypervisor_unreachable",
  "detail": "L'hyperviseur hébergeant ce VPS n'a pas répondu. Réessayez dans quelques instants.",
  "request_id": "3f9a1c07b2e45d18"
}

inventário dos VPS momentaneamente indisponível

{
  "type": "https://docs.lws.fr/kvm/errors/upstream-unavailable",
  "title": "Service momentanément indisponible",
  "status": 502,
  "code": "upstream_unavailable",
  "detail": "Inventaire des VM indisponible.",
  "request_id": "3f9a1c07b2e45d18"
}
Campos da resposta 18
  • type string (uri)

    Exemplo: https://docs.lws.fr/kvm/errors/vm-not-found

    obrigatório
  • title string

    Título curto

    Exemplo: VPS introuvable

    obrigatório
  • status integer (int64)

    Estado HTTP

    Exemplo: 404

    obrigatório
  • code string

    Código de máquina estável (ver «Erros» em Primeiros passos)

    Exemplo: vm_not_found

    obrigatório
  • detail string

    Mensagem detalhada

    Exemplo: Aucun VPS 999999 sur ce compte.

    obrigatório
  • request_id string

    Identificador do pedido, a comunicar ao suporte

    Exemplo: 3f9a1c07b2e45d18

    obrigatório
  • errors object

    validation_failed: mensagem por parâmetro incorreto

  • required_level string

    insufficient_scope: nível exigido pela operação

    um de: read, exploitation, full

  • task_id string

    task_already_running: tarefa em curso neste VPS

    Exemplo: tsk_000002d5

  • family string

    rate_limited: família de quota esgotada

    um de: read, mutation, heavy

  • limit integer (int64)

    rate_limited: limite horário da família

  • retry_after integer (int64)

    rate_limited: segundos a aguardar

  • lock string

    server_locked: bloqueio aplicado pelo hipervisor (backup, snapshot, suspended…)

    Exemplo: snapshot

  • reason string

    server_locked: operation_in_progress, há uma operação em curso, tente novamente após Retry-After; suspended, o VPS está em hibernação, inicie-o primeiro; support_notified, bloqueio anómalo, a equipa LWS foi avisada e está a intervir

    um de: operation_in_progress, suspended, support_notified

  • maintenance object

    server_maintenance: natureza da intervenção, início e fim previsto (null para um incidente)

  • kind string

    um de: works, incident

  • started_at string (date-time)
  • expected_end string (date-time)
503

Servidor anfitrião em intervenção: server_maintenance — servidor anfitrião em intervenção anunciada pela LWS e inacessível; respeite Retry-After.

 
{
  "type": "https://docs.lws.fr/kvm/errors/server-maintenance",
  "title": "Intervention en cours sur le serveur hôte",
  "status": 503,
  "code": "server_maintenance",
  "detail": "Le serveur hébergeant ce VPS fait l'objet d'une intervention programmée par LWS : il est momentanément inaccessible. Fin prévue : 2026-10-21T18:00:00+02:00.",
  "request_id": "3f9a1c07b2e45d18",
  "maintenance": {
    "kind": "works",
    "started_at": "2026-10-21T14:00:00+02:00",
    "expected_end": "2026-10-21T18:00:00+02:00"
  }
}
Campos da resposta 18
  • type string (uri)

    Exemplo: https://docs.lws.fr/kvm/errors/vm-not-found

    obrigatório
  • title string

    Título curto

    Exemplo: VPS introuvable

    obrigatório
  • status integer (int64)

    Estado HTTP

    Exemplo: 404

    obrigatório
  • code string

    Código de máquina estável (ver «Erros» em Primeiros passos)

    Exemplo: vm_not_found

    obrigatório
  • detail string

    Mensagem detalhada

    Exemplo: Aucun VPS 999999 sur ce compte.

    obrigatório
  • request_id string

    Identificador do pedido, a comunicar ao suporte

    Exemplo: 3f9a1c07b2e45d18

    obrigatório
  • errors object

    validation_failed: mensagem por parâmetro incorreto

  • required_level string

    insufficient_scope: nível exigido pela operação

    um de: read, exploitation, full

  • task_id string

    task_already_running: tarefa em curso neste VPS

    Exemplo: tsk_000002d5

  • family string

    rate_limited: família de quota esgotada

    um de: read, mutation, heavy

  • limit integer (int64)

    rate_limited: limite horário da família

  • retry_after integer (int64)

    rate_limited: segundos a aguardar

  • lock string

    server_locked: bloqueio aplicado pelo hipervisor (backup, snapshot, suspended…)

    Exemplo: snapshot

  • reason string

    server_locked: operation_in_progress, há uma operação em curso, tente novamente após Retry-After; suspended, o VPS está em hibernação, inicie-o primeiro; support_notified, bloqueio anómalo, a equipa LWS foi avisada e está a intervir

    um de: operation_in_progress, suspended, support_notified

  • maintenance object

    server_maintenance: natureza da intervenção, início e fim previsto (null para um incidente)

  • kind string

    um de: works, incident

  • started_at string (date-time)
  • expected_end string (date-time)
GET /servers/{vmid}/metrics 
LWS_API_KEY='…'curl -X GET \  "https://panelkvm.lwspanel.com/api/v1/servers/116807/metrics" \  -H "Authorization: Bearer $LWS_API_KEY"
$lwsApiKey = '…';$ch = curl_init("https://panelkvm.lwspanel.com/api/v1/servers/116807/metrics");curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);curl_setopt($ch, CURLOPT_HTTPHEADER, [    "Authorization: Bearer " . $lwsApiKey,]);$res = json_decode(curl_exec($ch), true);
import requestsLWS_API_KEY = "…"res = requests.get(    "https://panelkvm.lwspanel.com/api/v1/servers/116807/metrics",    headers={        "Authorization": "Bearer " + LWS_API_KEY,    },)print(res.json())
const LWS_API_KEY = "…";const res = await fetch("https://panelkvm.lwspanel.com/api/v1/servers/116807/metrics", {  method: "GET",  headers: {    "Authorization": "Bearer " + LWS_API_KEY,  },});const data = await res.json();
lwsApiKey := "…"req, _ := http.NewRequest("GET",    "https://panelkvm.lwspanel.com/api/v1/servers/116807/metrics", nil)req.Header.Set("Authorization", "Bearer "+lwsApiKey)resp, err := http.DefaultClient.Do(req)