Auto-scaling HTTP

Use este endpoint para configurar auto-scaling em aplicações HTTP pagas. O projeto mantém um mínimo de instâncias reservadas e pode aumentar instâncias automaticamente durante picos.

Permissões necessárias

Configurar auto-scaling exige project.instances.update em project:<project-id>. Consultar eventos de escala exige project.metrics.read no mesmo projeto. owner tem acesso completo; assistant, member e API Keys precisam do scope específico.

Headers

Header	Obrigatório	Descrição
`x-api-key` ou `Authorization`	Sim	API Key da organização ou token de usuário
`x-organization-id`	Com token de usuário	Organização ativa do projeto. Dispensável com API Key da organização
`Content-Type: application/json`	Sim	Necessário no `PATCH`

Atualizar Auto-scaling

PATCH /v1/project/:id/autoscaling

Limite de requisições: 20 a cada 5 minutos (contado por IP de origem).

Body

Campo	Tipo	Obrigatório	Descrição
`enabled`	boolean	Sim	`true` ativa ou atualiza; `false` desativa
`min_instances`	inteiro	Ao ativar	Mínimo reservado de instâncias (inteiro positivo)
`max_instances`	inteiro	Ao ativar	Máximo permitido durante picos (inteiro positivo)
`target_cpu_utilization_percent`	inteiro	Não	CPU alvo, de 1 a 100. Padrão: `70`
`target_memory_utilization_percent`	inteiro	Não	Memória alvo, de 1 a 100. Padrão: `80`

max_instances deve ser maior ou igual a min_instances. Com enabled: false, enviar qualquer outro campo retorna 400.

Ativar ou Atualizar

{
  "enabled": true,
  "min_instances": 2,
  "max_instances": 8,
  "target_cpu_utilization_percent": 70,
  "target_memory_utilization_percent": 80
}

Desativar

{
  "enabled": false
}

Resposta

{
  "status": "success",
  "message": "project autoscaling updated with success",
  "data": {
    "autoscaling": {
      "enabled": true,
      "min_instances": 2,
      "max_instances": 8,
      "target_cpu_utilization_percent": 70,
      "target_memory_utilization_percent": 80
    }
  }
}

Histórico de Eventos

GET /v1/project/:id/autoscaling/events

Limite de requisições: 100 por minuto (contado por IP de origem).

Retorna o histórico paginado de scale up e scale down registrado pela Zenifra. Use esse endpoint para auditoria, suporte e análise de picos.

Query

Campo	Tipo	Obrigatório	Descrição
`direction`	string	Não	Filtra por `scale_up` ou `scale_down`
`from`	ISO date	Não	Início do período
`to`	ISO date	Não	Fim do período
`page`	number	Não	Página. Padrão: `1`
`limit`	number	Não	Itens por página. Padrão: `50`, máximo: `100`

Resposta

{
  "status": "success",
  "message": "get project autoscaling events with success",
  "data": {
    "events": [
      {
        "id": "6a24f7...",
        "direction": "scale_up",
        "previous_instances": 2,
        "new_instances": 5,
        "desired_instances": 5,
        "min_instances": 2,
        "max_instances": 8,
        "trigger_metric": "cpu",
        "current_cpu_utilization_percent": 91,
        "target_cpu_utilization_percent": 70,
        "current_memory_utilization_percent": 62,
        "target_memory_utilization_percent": 80,
        "reason": "increased_capacity",
        "message": "Automatic scaling increased the project instance count.",
        "occurred_at": "2026-06-05T21:40:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 1,
      "total_pages": 1
    }
  }
}

O histórico é mantido por 13 meses.

Cobrança

Em projetos por hora, a cobrança usa as instâncias observadas no período.

Em projetos mensais ou anuais, o mínimo reservado entra no contrato principal. Instâncias acima do mínimo são cobradas por instância-hora, com o valor do contrato convertido em hora: preço mensal dividido por 720 ou preço anual dividido por 8.760.

Regras

Situação	Resultado
Projeto não é HTTP	Rejeitado
Projeto está parado	Rejeitado
Plano não permite auto-scaling	Rejeitado
Alterar instâncias manualmente com auto-scaling ativo	Rejeitado com `409`

Erros Comuns

Status	Código	Quando acontece
`400`	—	O projeto não é HTTP, ou o corpo é inválido
`403`	`AUTOSCALING_NOT_AVAILABLE_FOR_PLAN`	O plano atual não permite auto-scaling
`409`	`PROJECT_MUST_BE_RUNNING`	O projeto precisa estar em execução para alterar auto-scaling
`409`	`AUTOSCALING_REQUIRES_SHARED_STORAGE`	O projeto precisa de armazenamento compartilhado para usar auto-scaling
`409`	`PROJECT_LIFECYCLE_OPERATION_IN_PROGRESS`	Outra operação do projeto está em andamento
`429`	`AUTOSCALING_UPDATE_IN_PROGRESS`	Já existe uma alteração de auto-scaling em andamento para o projeto
`429`	`AUTOSCALING_TOGGLE_COOLDOWN_ACTIVE`	O auto-scaling foi ativado ou desativado recentemente; a resposta inclui `retry_after_seconds`
`503`	`AUTOSCALING_TEMPORARILY_UNAVAILABLE`	O auto-scaling está temporariamente indisponível; tente novamente em instantes

Próximos Passos

Consulte Instâncias para listar instâncias atuais.
Consulte Métricas e Logs para validar comportamento durante picos.

Nessa página